SHSelfHostIndex

Jekyll

Simple, blog-aware static site generator

Blogging Platforms ★ 51.7k stars Medium setup MIT

Jekyll is a popular open-source static site generator that transforms Markdown and Liquid templates into static blogs and websites. It pioneered the modern static-site approach and integrates with GitHub Pages.

Official siteSource code

Key features

  • Blog-aware by design
  • Markdown and Liquid templating
  • Large plugin ecosystem
  • GitHub Pages support

Pros & cons

Strengths

  • Mature and well documented
  • Great for personal blogs

Trade-offs

  • Slower builds on large sites
  • Ruby toolchain required

Jekyll replaces

Self-hosted WordPress alternativesSelf-hosted Blogger alternatives

Last reviewed Aug 26, 2026 · 984 words

Choose Jekyll in 2026 for one of two reasons: you publish on GitHub Pages, where it builds for free with no pipeline to maintain, or you already have a Ruby toolchain and want the largest back-catalogue of themes, plugins, and answered questions any static generator has accumulated since 2008. If neither applies and you are starting a self-hosted blog from a blank directory, Hugo does the same job as one binary and builds an order of magnitude faster, and I say that as someone whose first static site was Jekyll and who still runs one. The MIT licence, the Markdown-plus-front-matter model, and the _posts convention Jekyll invented are now the shared vocabulary of the whole category; what you are choosing is the Ruby runtime that comes with them.

Ruby is the install; Jekyll is just a gem

Nearly every bad Jekyll experience is a Ruby experience: a system Ruby that is too old, gems installed as root, native extensions failing to compile. On Debian or Ubuntu, this sequence follows the official docs and avoids all three:

sudo apt install ruby-full build-essential zlib1g-dev
echo 'export GEM_HOME="$HOME/gems"' >> ~/.bashrc
echo 'export PATH="$HOME/gems/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
gem install jekyll bundler
jekyll new blog && cd blog
bundle exec jekyll serve --livereload

The preview is on port 4000 and rebuilds on save. On macOS, skip the bundled system Ruby entirely and install one through Homebrew or a version manager, then do the same GEM_HOME trick. Always run Jekyll through bundle exec so the gems from the site's Gemfile.lock are the ones used; the bare jekyll command picks whatever is newest on the machine and that mismatch is the classic "works here, breaks in CI" story. If you would rather not touch Ruby on the host at all, the official ruby:3 image builds a site in one line: docker run --rm -v "$PWD:/site" -w /site ruby:3 sh -c "bundle install && bundle exec jekyll build".

GitHub Pages runs Jekyll 3 with a plugin allowlist

This is the trap the catalogue's "GitHub Pages support" highlight does not mention. The built-in Pages build uses the github-pages gem, which pins Jekyll to the 3.x line and permits only a fixed list of plugins. Jekyll 4 features and any plugin outside that list are silently ignored, and people spend an evening wondering why their site renders differently from the local preview. The fix is to switch the repository's Pages source to GitHub Actions and use the starter Jekyll workflow, which runs whatever Gemfile you specify and deploys the built artifact. Self-hosting removes the constraint entirely, since the server never sees Ruby.

Posts, front matter, and the three plugins every blog needs

Content goes in _posts/2026-08-26-my-title.md with YAML front matter at the top; layouts in _layouts, partials in _includes, structured data in _data, and everything is wired through _config.yml. A minimal config that gets the SEO plumbing right on day one:

title: A Blog
url: https://blog.example.com
permalink: /:title/
plugins:
  - jekyll-feed
  - jekyll-seo-tag
  - jekyll-sitemap

Add those three gems to the Gemfile, put {% seo %} in the layout's <head>, and you have an RSS feed, Open Graph and JSON-LD tags, and sitemap.xml with no further work. permalink: /:title/ drops the date from URLs, which you will want the first time you update a post. Themes are gems too; the default minima is deliberately plain and swapping it is a one-line change, but a theme that also ships its own plugins will need the Actions build if you are on Pages.

Build time is the real con, and it scales with post count

Jekyll builds are roughly linear in page count and the constant is high: on my hardware a few hundred posts build in a handful of seconds, a couple of thousand take a minute or more, and every Liquid loop over site.posts inside a layout multiplies that. --incremental exists but is marked experimental and misses changes that affect other pages, so I do not rely on it. bundle exec jekyll build --profile prints a table of which templates cost the most, and the usual culprit is a related-posts or tag-cloud include doing a full scan per page. For a personal blog this never matters; for a 5,000-page site it is why Hugo vs Jekyll has a clear answer in one direction.

Self-hosting means hosting the output, not Jekyll

There is no Jekyll server to run. bundle exec jekyll build writes plain HTML into _site/, and that directory is the entire deployment. Build it in CI (Gitea Actions or Woodpecker both handle a Ruby container) or on your laptop, then rsync -av --delete _site/ server:/srv/blog/ and serve it:

blog.example.com {
    root * /srv/blog
    file_server
    encode zstd gzip
}

That is a complete Caddy site with automatic TLS. The server has no runtime, no database, and nothing to patch, and a plain HTML page behind gzip passes Core Web Vitals without effort, which core web vitals on static sites goes into. Jekyll's Ruby dependency lives on the build machine only, which is the strongest argument for keeping it if you already like it.

What I'd do

On GitHub Pages: keep Jekyll, switch the build to Actions so you can use Jekyll 4 and any plugin, add the three plugins above, and never think about it again. Self-hosting from scratch with no Ruby on the machine: start with Hugo instead. Self-hosting with an existing Jekyll site: do not migrate, it is not worth the broken URLs; build in CI, rsync to Caddy, and enjoy a blog whose server side needs zero maintenance.

Compare Jekyll

31 head-to-head comparisons.

Similar blogging platforms apps