Skip to content
Blume
Esc
↑↓navigate↵open⌘Jpreview

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 and Jekyll at a glance
BlumeJekyll
You maintainBlumeA folder of Markdown, plus one optional config fileJekyllA Ruby site: _config.yml, a Gemfile, and Liquid includes
LicenseBlumeFree and open source (MIT)JekyllFree and open source (MIT), Jekyll and Just the Docs alike
HostingBlumeAny host: Vercel, Netlify, Cloudflare, Node, or static filesJekyllAny static host; GitHub Pages' default build runs allowlisted plugins only
SearchBlumeLocal search with no keys, or Pagefind, Algolia, and more by adapterJekyllLunr search built into Just the Docs, with no results page
Agent featuresBlumellms.txt, Markdown mirrors, and a JSON API by default; an opt-in MCP serverJekyllCommunity plugins for llms.txt and Markdown copies, outside GitHub Pages' allowlist
API referencesBlumeOpenAPI, AsyncAPI, and GraphQL, with a Try it playgroundJekyllNot built into Jekyll or Just the Docs
VersioningBlumeblume version snapshots with a switcher and scoped searchJekyllNot built in; an open Just the Docs request since 2021
LanguagesBlumeblume translate fills in every locale with your coding agentJekyllCommunity 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' parent and nav_order front matter becomes folders and meta.ts files, 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_from and .html URLs 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 _plugins folder. 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 _data and loops over it with Liquid in any page. Blume pages are Markdown and MDX, so the migration writes those loops out as static content.
Migrate from
  1. 1

    Run one command in your docs project.

    Using Claude Code? Swap --codex for --claude.

  2. 2

    Review the agent's edits.

    It follows Blume's migration playbook for , rewriting your config and pages in place, so you review the whole move as one diff.

  3. 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