Guide · Open source
How to use Jekyll: setup, Markdown posts and static HTML output
Updated · written with AI from the project's own documentation and checked against our catalogue data
Jekyll is a blog-aware static site generator written in Ruby. You write content as plain text files such as Markdown, combine them with templates, and it builds a folder of plain HTML pages that you can host anywhere. This guide explains what you need before starting, how the workflow fits together, and when Jekyll is a better or worse fit than other tools, so you can decide whether to use it.
Jekylljekyll/jekyll · ★ 51.7k · MIT Install options & downloads Quick start
- 1Check Ruby is installed. Confirm Ruby is available on your computer before you start, since Jekyll is written in Ruby.
- 2Clone the repository. Run the git clone command for the jekyll/jekyll repository in the folder where you want the project.
- 3Read the full setup guide. Open the repository README and the homepage at jekyllrb.com for complete installation and build steps, since the README was truncated in this source.
- 4Write your content as Markdown. Create your posts and pages as Markdown files, which Jekyll combines with templates.
- 5Build the site. Run the build process described in the official guide to generate the folder of static HTML pages.
- 6Host the output. Upload the generated HTML folder to any web host that serves static files.
What Jekyll is and who it is for
Jekyll takes your source files, mainly Markdown, and merges them with templates to produce static HTML. Static means the output is plain files with no database and no server-side code. The project describes itself as blog-aware, and its topics include blog engine and Liquid templating.
It suits developers who want a blog or simple website built from text files, writers who prefer Markdown, and projects that need hosting without a database. It is not a good match for non-technical users who want a point-and-click builder, or for sites that need user accounts or live database queries.
- Good fit: blogs and simple websites built from text files
- Good fit: writers who prefer Markdown and want HTML output
- Poor fit: sites that need user accounts or live database queries
- Poor fit: people who want a hosted service instead of running a build tool
What you need before you install Jekyll
Jekyll is written in Ruby, so Ruby is the main prerequisite. You also need to be comfortable with the command line, because setup and everyday use happen in a terminal.
The project is MIT licensed, which means it is free to use. Check the official homepage at jekyllrb.com for the current setup guidance.
- Ruby installed on your computer
- Comfort with the command line
- A text editor for writing Markdown files
Get the Jekyll source code
The README in the source provided for this guide lists one install command: cloning the repository from GitHub. Run it in the folder where you want the project to live. The README was truncated, so the full setup steps are in the repository and on the homepage.
git clone https://github.com/jekyll/jekyllUnderstand how a Jekyll site is built
A Jekyll site is a set of source files. Content is written in files such as Markdown and combined with templates. The build step turns these inputs into a folder of plain HTML pages.
Because the result is static HTML, you can host it on any web server or static host that serves files. You do not need to run Jekyll on the live server, since the output is what gets published.
- Inputs: content files such as Markdown, plus templates
- Process: Jekyll combines them into pages
- Output: a folder of plain HTML files you can host anywhere
Compare Jekyll with other static site generators
The comparable projects named for this item are Hugo, Eleventy, Hexo and Gatsby. Each is a tool that builds websites from source files, so the choice depends on your language preference, template approach and how much you want to customise.
If you already work in Ruby and want a blog-focused generator, Jekyll is a natural starting point. If you prefer a different language or tooling, one of the alternatives may suit you better.
- Hugo
- Eleventy
- Hexo
- Gatsby
What people use it for
- A personal blog written in Markdown and published as static HTML
- A simple project website hosted without a database
- A documentation or notes site built from plain text files
- A writer's site where content lives in version-controlled text files
Frequently asked questions
Is Jekyll free to use?
Yes. Jekyll is released under the MIT licence, which is listed in the project metadata. You can use it without paying for the software itself.
What do I need to run Jekyll?
Jekyll requires Ruby. You also need to be comfortable working from the command line, since setup and use happen there.
Does Jekyll need a database?
No. Jekyll produces static HTML files, so a site built with it can be hosted without a database or server-side code.
Can non-technical people use Jekyll?
It is not a good match for non-technical users who need a point-and-click site builder, because setup requires Ruby and the command line.
What are good alternatives to Jekyll?
Comparable projects named for this item are Hugo, Eleventy, Hexo and Gatsby. Pick based on the language you prefer and how you want to build your templates.
Where do I find full install instructions?
The source for this guide included only one install command, cloning the repository. Full setup steps are in the repository README and on the official homepage at jekyllrb.com.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Jekyll is a good choice for developers and writers who want a blog or simple website made from Markdown files and published as static HTML with no database. It is a poor choice for non-technical users who need a point-and-click builder, or for teams that want a hosted service rather than running a build tool themselves. If you want to avoid Ruby, consider Hugo, Eleventy, Hexo or Gatsby.
Install options & downloads