Blume vs Starlight.Astro docs, with nothing to set up.
Both build on Astro. Starlight is a theme for an Astro project you own; Blume generates and runs the project for you, with llms.txt, an MCP server, API references, and versioning built in rather than added as plugins.
npx blume migrate starlight --claude| Blume | Starlight | |
|---|---|---|
| You maintain | BlumeA folder of Markdown, plus one optional config file | StarlightAn Astro project: astro.config, a content collection, and your overrides |
| Built on | BlumeAstro, generated and run for you | StarlightAstro, as an integration in your project |
| Search | BlumeLocal search with no keys, or Pagefind, Algolia, and more by adapter | StarlightPagefind built in; Algolia DocSearch through an official plugin |
| Agent features | Blumellms.txt, Markdown mirrors, and a JSON API by default; an opt-in MCP server | StarlightCommunity plugins for llms.txt, Markdown pages, and copy buttons |
| API references | BlumeOpenAPI, AsyncAPI, and GraphQL, with a Try it playground | StarlightOpenAPI through the community starlight-openapi plugin |
| Versioning | Blumeblume version snapshots with a switcher and scoped search | StarlightThrough the community starlight-versions plugin |
| Blog and changelog | BlumeBlog and changelog page types, with RSS | StarlightCommunity plugins, such as starlight-blog |
| Languages | Blumeblume translate fills in every locale with your coding agent | StarlightBuilt-in i18n with fallback content and right-to-left support |
Starlight details are from its own pages as of September 23, 2026: Setup, Search, i18n, Plugins. Something out of date? Let us know
Your docs come with you.Astro to Astro, and an agent does the move.
- Content stays where it is.
- Blume reads
src/content/docsin place. Pages with asides become.mdx, since Blume renders directives in MDX. - Asides keep their names.
:::note,:::tip,:::caution, and:::dangercarry over, titles and all.- Plugins map to built-ins.
- starlight-openapi, starlight-blog, and starlight-versions become Blume config, and link validation and image zoom are already built in.
- Overrides map to layout slots.
- Starlight component overrides map nearly one to one to Blume's layout slots, so a custom header or footer comes along.
Starlight
Blume
- starlight({ … })blume.config.ts
- <CardGrid><CardGroup>
- <LinkCard><Card>
- <TabItem label="…"><Tab title="…">
- pagefind: falsesearch.exclude: true
- lastUpdated: truelastModified: "git"
- customCsstheme.css
When Starlight might suit you better.Blume isn't the right fit for every team.
- You already have an Astro site.
- Starlight adds docs as routes inside your own Astro project, sharing its config, pages, and adapter. Blume generates a separate project for your docs.
- You want the Astro team's theme.
- Starlight is maintained by the Astro team, tracks Astro releases closely, and runs production docs like Cloudflare's and Netlify's.
- You write in Markdoc.
- Starlight supports Markdoc through an official package. Blume supports Markdown and MDX.
- 1
Run one command in your docs project.
Using Codex? Swap
--claudefor--codex. - 2
Review the agent's edits.
It follows Blume's migration playbook for MintlifyFumadocsDocusaurusStarlightNextra, 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 Starlight to Blume.
Blume and Starlight both use Astro. What's the difference?
Starlight is an integration you add to an Astro project you own and configure. Blume generates and runs the Astro project for you from a folder of Markdown, and builds in what Starlight leaves to plugins: llms.txt, an MCP server, API references, versioning, and blog posts with RSS.
Can I still customize components?
Yes. Replace any MDX component or layout slot with your own, write islands in React, Vue, or Svelte, or run blume eject for a standalone Astro app.
Do I have to rename my .md files?
Only pages that use asides or other directives. Blume renders ::: directives in .mdx files, so the agent renames those pages, and plain Markdown can stay .md.
Where can I host Blume?
Anywhere: Vercel, Netlify, Cloudflare, a Node server, or any static host. blume build outputs static files by default.
What doesn't the migration carry over?
Splash and hero pages, which you rebuild as custom pages, plus head entries, non-GitHub social links, and plugins without a Blume equivalent. The agent reports each one.
Upgrade your docs with Blume.
Install today and ship a production-grade docs site in minutes. Free and open source, forever.
npx blume init