Running on Jekyll?

Jekyll site stuck on an ancient Ruby? We bring it back.

A Jekyll site is often the oldest thing in a company, which also means it is the one with a Gemfile no laptop can bundle and a plugin list GitHub Pages no longer whitelists. We pick these up, port them onto a Ruby you can still install, and either keep them on GitHub Pages where that still makes sense or move them onto Netlify or Cloudflare Pages where the restrictions no longer apply.

  • Since 2015Fixing technology
  • FreeEstimates
  • US teamReal engineers

jekyll-serve.log

still broken

What it is

Jekyll at a glance

Jekyll is a static site generator written in Ruby, created by Tom Preston-Werner in 2008 and still the engine behind GitHub Pages. Content is written in Markdown with YAML front matter, layouts and includes use the Liquid template language, and the output is a folder of static HTML suitable for hosting almost anywhere.

The GitHub Pages integration made Jekyll the default choice for developer blogs and documentation sites for many years. GitHub Pages runs a pinned Jekyll version with a short whitelist of plugins, which is why many sites migrated to running their own Jekyll on Netlify, Cloudflare Pages or a CI build. Hugo, Eleventy and newer SSGs have taken a lot of new projects, but a large installed base of Jekyll sites is still quietly deployed.

Type
Static site generator
First released
2008
License
MIT
Maintained by
The Jekyll core team
Typically used for
Developer blogs, project documentation, GitHub Pages sites, long-running marketing microsites

The honest version

Jekyll pros and cons

No technology is all upside. This is where Jekyll earns its place and where it tends to cause trouble.

Where Jekyll is strong

  • GitHub Pages is still essentially free hostingA Jekyll site in a public repository is served on github.io without infrastructure, which is hard to beat for personal and open-source project sites.
  • The content model is simple and durableMarkdown, front matter, _posts and _layouts have changed very little since 2008. Posts written then still render now, which matters when a blog has a decade of archives.
  • Liquid is readable if plainTags, filters and includes are easy for non-developers to read, and the error surface is small compared to full programming languages in templates.
  • Themes are reusable through gemsA theme distributed as a Ruby gem can be upgraded independently of the site, which keeps content and presentation cleanly separate when it is set up that way.
  • Build output is just static HTMLAny CDN, any bucket, any web server can host the result. There is no runtime to patch, and there are no servers to keep up.

Where Jekyll bites

  • Ruby version compatibility is the usual pain pointJekyll 3 struggles on modern Ruby versions, Jekyll 4 wants a maintained set of gems, and older sites pin to gems that no longer compile cleanly on current platforms.
  • GitHub Pages plugin whitelist is restrictiveAnything outside the whitelist needs the site to build in CI and push the compiled HTML, which is often the step that finally moves a site off Pages entirely.
  • Build speed is not Jekyll's strengthLarge sites with thousands of posts take tens of seconds to minutes to build, where Hugo on the same content is single-digit seconds.
  • Plugin ecosystem is agingMany popular plugins have not seen a release in years, and the authors have moved on. A site that depends on three or four of them is exposed to the next Ruby or Jekyll bump.
  • Liquid is limited for complex pagesLoops, conditionals and filters are there but anything more complex pushes you into a plugin written in Ruby, which GitHub Pages will then refuse to run.

Sound familiar?

Common Jekyll problems we fix

The Jekyll problems that bring people to us, and what you have once each one is fixed.

Could not find gem in sources

bundle install no longer succeeds

A Gemfile.lock pinned to versions that are no longer on rubygems, or a native gem that does not build on the current Ruby. The site cannot be served or deployed locally.

Dependencies updated and lockfile valid

Liquid syntax error: Unknown tag

Liquid error after an upgrade

A custom Liquid tag provided by a plugin that is no longer loaded, or a Jekyll-Compose shortcut that stopped being supported. The build halts on the first file that uses it.

Templates valid on the current Jekyll

GitHub Pages: plugins directive excluded

GitHub Pages refuses to build the site

A plugin not on the whitelist, a configuration key the Pages gem does not recognize, or a theme being set directly instead of through remote_theme. The repository builds locally but Pages does not deploy it.

Pages build succeeds, or move handled

Jekyll 3.9 on Ruby 3.2 fails

Modern Ruby refuses to run an old Jekyll

Ruby 3 removed implicit conversions and tightened keyword arguments, and Jekyll 3 code paths trip on both. A machine on current macOS cannot run the site at all.

Running on a supported Ruby and Jekyll

Layout 'post' does not exist

Layouts and includes are mismatched

A theme upgrade removed a layout the posts still reference, or an old post front matter set a layout that was never defined in this site. Pages render but without the surrounding chrome.

Layouts resolving for every page

kramdown-parser-gfm LoadError

Markdown parser changed under the site

Older sites used kramdown, newer ones use kramdown-parser-gfm for GitHub-flavored Markdown, and a mismatch between the Gemfile and the config produces a load error at build time.

Markdown parsing consistent and tested

Permalink conflict

Two pages generate the same URL

A collection permalink rule that collides with the posts default, or two posts with the same slug in different folders. Jekyll overwrites one with the other silently.

Permalinks unique and documented

Regenerating: 94.7 seconds

The build takes minutes on a laptop

A large archive with no incremental build enabled, SCSS compilation that re-runs every time, and plugins that walk every post on every file change.

Build times back to seconds

What we do

Jekyll help, from rescue to upkeep

Call us for one failing build, or hand us the whole site.

Rescue
A Jekyll site that will not bundle, will not serve or will not deploy on GitHub Pages any more. We get it building on a current Ruby first and explain what was wrong second.
Ruby and gem upgrades
Porting a pinned, aging site onto a supported Ruby and Jekyll, replacing abandoned gems with maintained equivalents, and leaving a lockfile that a new laptop can install.
Off GitHub Pages
Moving a Jekyll site from the Pages build onto Netlify, Cloudflare Pages or a CI that pushes compiled HTML, so plugins and themes outside the whitelist become possible.
Themes and layouts
A theme written or tidied so posts, collections and pages render consistently, with layouts and includes documented so writers and future developers can see how the site fits together.
Migration off Jekyll
When the Ruby maintenance burden stops paying for itself, we move content to Hugo, Eleventy or a headless CMS, keeping URLs intact so existing links still resolve.
Managed Tech
Ruby and gem watch, periodic upgrade work, build monitoring and a team on call when the Pages build starts returning red on push.

How it works

From first message to fixed

  1. Look Free estimate

    Tell us what's going wrong. We look at it, then tell you plainly what's wrong and what it will cost.

  2. Fix

    We fix the cause, not the symptom. If something is down, getting it back up comes first.

  3. Harden

    Backups, monitoring, updates and access, so the same problem can't quietly come back.

  4. Hand back or stay on

    You get a plain-language write-up. Or we stay on for hosting, upkeep and new work.

Often found together

Running Jekyll alongside something else?

We work on the whole stack, so the problem can be wherever it actually is.

Questions

Jekyll questions

Something else? Call+1 737 727 7327

Why does our Jekyll site refuse to build on a current laptop?

Usually a Gemfile.lock full of gem versions that no longer compile on a modern Ruby, combined with a Jekyll 3 runtime that does not play well with Ruby 3. The honest fix is to port the site onto a supported Jekyll and gem set rather than pinning the laptop to a Ruby from 2017; we do that port in a branch and keep the existing content untouched.

Should we stay on GitHub Pages or move off it?

For small blogs and project sites where the plugin whitelist is not a constraint, GitHub Pages is still the right answer. Once you want a plugin outside the whitelist, SEO features Pages does not support, or a custom build step, you move the build into CI and deploy to Netlify, Cloudflare Pages or an S3 bucket. The Pages URL can be redirected so links keep working.

Why is the GitHub Pages build failing on push?

The common causes are a plugin that is not whitelisted, a theme set in a way the Pages gem does not recognize, a Gemfile that disagrees with the Pages Ruby version, and a recently added Liquid tag that Pages treats as unsafe. The GitHub Pages build log is the source of truth, and every failure has a specific line we can act on.

Can you migrate our Jekyll blog to Hugo?

Yes, and it is a frequent request. Jekyll's Markdown is largely portable, front matter translates with a small script, and the real work is in rebuilding the layouts in Go templates and preserving the existing permalink structure so inbound links still resolve. We leave the Jekyll repo in place until the new build is live and verified.

How do we handle a Jekyll site with ten years of posts?

The content itself is almost always fine. The Gemfile, the Ruby version, the theme and a handful of plugins are where the work is. We rebuild the dependency graph against a current Jekyll, replace or rewrite any plugin that has stopped being maintained, and move the build into CI so the setup is reproducible rather than tied to one engineer's laptop.

How much does Jekyll help cost?

We give estimates for free. Send us the repository or the Gemfile and the current error, and we respond with a price before any work is done.

Free estimate

Jekyll giving you trouble?

Tell us what you're running and what's going wrong. A person reads it and comes back with an estimate.

  • No charge to find out what it will take
  • If it's urgent, say so

Replies come from a person. By sending, you authorize us to email you back. No marketing.