Blume vs Jekyll.Jekyll docs, without the Ruby toolchain.
Just the Docs on Jekyll gives you a Ruby site that GitHub Pages can build for you. Blume turns the same Markdown into a site with llms.txt, API references, versioning, and translations built in, and no Ruby to install.
npx blume migrate jekyll --codex| Blume | Jekyll | |
|---|---|---|
| You maintain | BlumeA folder of Markdown, plus one optional config file | JekyllA Ruby site: _config.yml, a Gemfile, and Liquid includes |
| License | BlumeFree and open source (MIT) | JekyllFree and open source (MIT), Jekyll and Just the Docs alike |
| Hosting | BlumeAny host: Vercel, Netlify, Cloudflare, Node, or static files | JekyllAny static host; GitHub Pages' default build runs allowlisted plugins only |
| Search | BlumeLocal search with no keys, or Pagefind, Algolia, and more by adapter | JekyllLunr search built into Just the Docs, with no results page |
| Agent features | Blumellms.txt, Markdown mirrors, and a JSON API by default; an opt-in MCP server | JekyllCommunity plugins for llms.txt and Markdown copies, outside GitHub Pages' allowlist |
| API references | BlumeOpenAPI, AsyncAPI, and GraphQL, with a Try it playground | JekyllNot built into Jekyll or Just the Docs |
| Versioning | Blumeblume version snapshots with a switcher and scoped search | JekyllNot built in; an open Just the Docs request since 2021 |
| Languages | Blumeblume translate fills in every locale with your coding agent | JekyllCommunity plugins such as Polyglot; Just the Docs has no i18n |
Jekyll details are from its own pages as of October 7, 2026: Releases, Requirements, GitHub Pages plugins, GitHub Pages versions, Search, Versioning request. Something out of date? Let us know
Your docs come with you.Every URL stays put, and an agent does the move.
- Callouts become directives.
- Each
{: .note }attribute list becomes a:::directive, matched by the callout's name or color in_config.yml, and labels become badges. - The sidebar moves into folders.
- Just the Docs'
parentandnav_orderfront matter becomes folders andmeta.tsfiles, rebuilt from your old build without moving a URL. - Liquid becomes includes and variables.
- Markdown includes become
<include>, plain{{ site.x }}values become variables, and{% link %}and relative links become routes. - Old URLs and anchors keep working.
redirect_fromand.htmlURLs become redirects, and a script pins every old heading anchor that Blume would spell differently.
Jekyll
Blume
- _config.ymlblume.config.ts
- {: .warning }:::warning
- {: .label }<Badge>
- nav_ordermeta.ts
- {% include x.md %}<include>
- {{ site.title }}{{title}}
- redirect_fromredirects
When Jekyll might suit you better.Blume isn't the right fit for every team.
- You want GitHub to build it for you.
- GitHub Pages builds a Jekyll site straight from a branch, with no workflow to write, as long as it sticks to the allowlisted plugins. Blume on GitHub Pages builds in an Actions workflow.
- You extend your site in Ruby.
- Jekyll plugins are Ruby: generators, converters, Liquid tags and filters, and build hooks, from a gem or a
_pluginsfolder. A Ruby team can extend the build in the language it already writes. - You build pages from data files.
- Jekyll loads YAML, JSON, CSV, and TSV from
_dataand loops over it with Liquid in any page. Blume pages are Markdown and MDX, so the migration writes those loops out as static content.
- 1
Run one command in your docs project.
Using Claude Code? Swap
--codexfor--claude. - 2
Review the agent's edits.
It follows Blume's migration playbook for MintlifyFumadocsDocusaurusStarlightNextraGitBookMkDocsReadMeVitePressFernRedoclyVuePressDocsifyDocusmdBookJekyllGitHub Wiki, rewriting your config and pages in place, so you review the whole move as one diff.
- 3
Preview the result.
Run
npx blume dev, then read the agent's summary of anything it dropped or approximated.
Questions, answered.About moving from Jekyll to Blume.
Why move from Jekyll and Just the Docs?
Jekyll's latest release is 4.4.1, from January 2025, and GitHub Pages' own build runs Jekyll 3.10.0 with allowlisted plugins only. llms.txt, versioning, translations, and API references aren't built into Jekyll or Just the Docs. Blume ships all four, with no Ruby toolchain to install.
Can I keep my Just the Docs pages?
Yes. npx blume migrate jekyll --codex runs a codemod that turns callout attribute lists into ::: directives, Markdown includes into <include>, and parent and nav_order into folders and meta.ts, without moving a URL.
Do I still need Ruby?
No. Blume runs on Node.js 22.19 or later, so the Gemfile and Bundler go, and the agent swaps bundle exec jekyll build in your CI for the Blume build.
Can my docs stay on GitHub Pages?
Yes. blume build outputs static files, and a GitHub Actions workflow deploys them to Pages, with your baseurl as deployment.base. The assistant and the MCP server need a server host, such as Vercel, Netlify, Cloudflare, or Node.
What doesn't the migration carry over?
Just the Docs' layouts and color schemes beyond the accent, _sass rules with no Blume equivalent, callout labels that only name the type, Kramdown abbreviations and site-wide code line numbers, page scripts and jQuery widgets, and plugins with no equivalent. Liquid logic and _data loops become static content, and the agent reports each item so you can decide what to do with it.
Upgrade your docs with Blume.
Install today and ship a production-grade docs site in minutes. Free and open source, forever.
npx blume init