What Is Jekyll and What Is It Used For?
Jekyll is a static site generator: it takes Markdown or HTML content, applies Liquid templates and layouts, and writes a complete set of plain HTML, CSS, and JavaScript files into an output folder (by default _site). You would use it when you want a fast, version-controllable site — typically a blog, documentation set, or project homepage — and you are comfortable editing text files rather than a database-backed CMS. It is not the same thing as OpenBVE, the train simulator project whose homepage happens to share the "Jekyll" keyword in site metadata; the two are unrelated.
How the build workflow fits together
Jekyll separates your source material from the finished site:
- Source files — Markdown (
.md) or HTML pages, plus data files (YAML, JSON, CSV) and static assets like images. - Templates and layouts — Liquid files that define reusable structure. A layout wraps a page; includes pull in repeated fragments such as a header or footer.
- Configuration —
_config.ymlholds site-wide settings: title, base URL, collections, plugins, and build options. - Output — running the build writes the rendered site to
_site/. That folder is what you deploy; it contains no server-side code.
A page's front matter (the YAML block between --- lines at the top of a file) tells Jekyll which layout to use and supplies variables the templates can read. Liquid tags then insert those values, loop over posts or collection items, and apply filters.
Common use cases
| Use case | Why Jekyll fits |
|---|---|
| Personal or project blog | Posts are dated files; pagination, categories, and feeds come from plugins or built-in support |
| Documentation | Content lives in Markdown, so it diffs cleanly in Git and reviews like code |
| Project or product homepage | Static output is cheap to host and fast to serve |
| GitHub Pages | GitHub Pages has built-in Jekyll support, so a repository can be published without a separate build server |
The GitHub Pages point is the one most people encounter first: pushing Markdown to a supported branch lets the host run Jekyll for you. If you need plugins that GitHub Pages does not allow, you build locally or in your own CI and publish the resulting _site instead.
What you need to start locally
- Ruby — Jekyll is a Ruby gem, so a working Ruby installation is the prerequisite.
- The Jekyll gem — install it with
gem install jekyll(or manage it through Bundler). - A project —
jekyll new my-sitescaffolds a starter site with a default theme, a sample post, and a config file. - A local server —
bundle exec jekyll servebuilds the site and serves it, usually athttp://localhost:4000, rebuilding when source files change.
Expected result: after the serve command, editing a Markdown file and saving it should update the page in your browser without restarting the server. If that does not happen, the usual causes are a missing gem in your Gemfile, a Ruby version mismatch, or a configuration error that the terminal output will name.
Where people get stuck
- Confusing the tool with a specific site. Search results for "Jekyll" mix the generator with unrelated projects that use the word in their metadata. Check whether a page is about static site generation before following its instructions.
- Editing
_siteby hand. That directory is regenerated on every build; changes there are overwritten. Edit the source files instead. - Assuming hosting is automatic. GitHub Pages runs Jekyll for supported setups, but other hosts serve whatever files you upload — you must build first.
- Underscore-prefixed folders. Directories like
_posts,_layouts, and_dataare special to Jekyll and are not copied verbatim into the output; only their rendered results appear.
If your goal is a text-driven site you can version and deploy as static files, Jekyll is a direct fit. If you need a database, user accounts, or server-side rendering, a static generator is the wrong layer and you should look at a CMS or application framework instead.