dotfiles/dot_agents/skills/blume-migrate/references/docusaurus.md

Docusaurus → Blume

Docusaurus is a React site; navigation comes from sidebars.js (explicit or autogenerated) plus per-folder _category_.json. Admonitions are already directive syntax, which eases the content transform — but note the source major version: v2 (MDX v1) and v3 (MDX v3) have different content hazards, called out below.

Detect

• docusaurus.config.{js,ts} at the root; a sidebars.{js,ts} file and per-folder _category_.json files.
• Content under docs/ (often plus blog/, src/pages/, static/, versioned_docs/); @docusaurus/* deps.
• v2 vs v3: check the @docusaurus/core major in package.json.

Config: docusaurus.config → blume.config.ts

Read themeConfig, presets, and plugins:

Docusaurus	Blume
title	title
tagline	description
themeConfig.navbar.title / .logo	title / logo (move the image into public/)
themeConfig.navbar.items (doc items)	navigation.tabs (for section links)
themeConfig.navbar.items (external/utility links — Blog, GitHub, Discord…)	navigation.featured ({ label, href, icon? }, pinned above the sidebar on every route); the GitHub link → the github config instead
themeConfig.colorMode.defaultMode	theme.mode (respectPrefersColorScheme: true → "system")
themeConfig.prism.theme / .darkTheme	markdown.codeBlocks.theme: { light, dark } (map Prism theme names to Shiki themes, e.g. github/github-dark)
themeConfig.metadata / themeConfig.image	per-page seo frontmatter / seo.og; report what doesn't fit
url + baseUrl	url → drop (deployment.site auto-detects); baseUrl (when not /) → deployment.base
preset docs.routeBasePath — including the default!	Docusaurus serves docs at /docs/… by default; the "map only declared fields" rule does not apply here because the URLs are load-bearing. Either keep them with top-level basePath: "/docs" (invisible to the sidebar), or intentionally move to root and emit a redirects entry per page. Decide explicitly and say which. (routeBasePath: '/' = docs-only mode — nothing to do.)
preset docs.editUrl	github (owner/repo/branch; a path after the branch → github.dir)
themeConfig.footer	drop → Footer override (defineComponents layout slot)
themeConfig.announcementBar	banner ({ content, dismissible, id } — isCloseable → dismissible; colors drop)
i18n.locales / defaultLocale	i18n — translated files live at i18n/<locale>/docusaurus-plugin-content-docs/current/…; move them to <locale>/… under content.root
themeConfig.algolia	drop — Blume ships built-in search (Orama); remove the Algolia dep
@docusaurus/plugin-client-redirects	static redirects: [{from, to}] arrays convert 1:1 to Blume redirects (a from array = one entry per item); only createRedirects functions are truly dynamic → host rules
@docusaurus/theme-mermaid	delete the dep — ```mermaid renders natively (in .mdx)
remark-math + rehype-katex	delete — block $$…$$ renders in .mdx with no config (no markdown.math field exists); inline $…$ is not supported — convert or drop (report)
Multi-instance docs plugins (plugin-content-docs with id)	one folder (and usually one navigation.tabs entry) per instance

Static assets — required move

Every Docusaurus repo serves static/ at the site root (static/img/foo.png → /img/foo.png). Blume serves public/. Move static/* (and any extra staticDirectories) into public/ — all root-relative references then keep resolving unchanged. Without this, every image and download 404s.

Navigation: sidebars.js + _category_.json

• Autogenerated sidebar ({ type: 'autogenerated', dirName: '...' }) → Blume's default filesystem navigation. Docusaurus strips numeric prefixes (01-) exactly like Blume, so the convention round-trips; no config needed.
• Explicit sidebar (arrays of doc IDs, categories, links) → restructure into folders where possible; use navigation.sidebar only for shapes files can't express. A category { type: 'category', label, items } → a folder (label → meta.ts title); collapsed → meta.ts collapsed, and collapsible rendering → that folder's meta.ts display: "group" (or navigation.sidebar.display: "group" once in config when every category collapses).
• _category_.json (also .yml) ({ label, position, collapsed, collapsible, link, className, customProps }) → a folder meta.ts: label→title, position→order, collapsed→collapsed. link.type: 'generated-index' → an index page in the folder — and the old URL was /docs/category/<slug>, so add a redirect and rewrite inbound links. link.type: 'doc' → make that doc the folder's index. collapsible/className/customProps → drop (report).
• src/pages/ — inventory, don't nuke. Nearly every repo has a React landing page (src/pages/index.tsx) and often extra Markdown pages. Markdown pages → content pages; the React home page → rebuild as a docs index or a custom .astro page under content.pages — report either way.

Versioned docs

Docusaurus versioned_docs/version-X/ + versions.json (+ versioned_sidebars/) → recommend migrating the latest released version only. Mind the URL scheme: by default the latest release serves at /docs/ and the work-in-progress docs/ folder serves at /docs/next (lastVersion: 'current' flips this) — pick the folder that matches what users see at /docs/. If older versions must stay, put each under its own folder and wire a navigation.selectors entry of kind: "version".

Blog

A Docusaurus blog/ → Blume type: blog pages. Dates come from filenames/folders (2024-01-31-foo.md) — extract each into date frontmatter and strip the date from the filename (the old dated URLs /blog/2024/01/31/foo need redirects). Strip <!-- truncate --> / {/* truncate */} markers. authors.yml refs → inline author objects in each post's authors frontmatter. RSS stays at /blog/rss.xml on both sides.

Content & components

• .md vs .mdx — both majors need renames, for opposite reasons. Blume parses .md as plain Markdown: no directives, no JSX, no $$ math, no mermaid/package-install fences. v3 treats .md as MDX (so a .md with imports/JSX/{} renders them as literal text in Blume); v2 content is looser MDX v1. Rule: rename any .md that contains admonitions, JSX, imports, or math to .mdx — for typical Docusaurus repos that is most files.
• Admonitions are directives — but check the version. v3: :::note, :::tip, :::info, :::warning, :::danger pass through; :::caution → :::warning (or rely on Blume's alias); titles :::note[Title] work. v2: titles are space-separated (:::note Your Title) — rewrite to brackets or the title is silently lost; and v2's :::warning rendered red/danger — audit whether it should become :::danger.
• Tabs: <Tabs>/<TabItem label="…" value="…"> → <Tabs>/<Tab title="…">. Drop groupId/queryString/value; strip the @theme/Tabs imports.
• Theme JSX in content: <DocCardList/> (standard on category index pages) → hand-write Card/CardGroup links or delete (a Blume group page lists its children); <TOCInline/> → drop (report); <CodeBlock> JSX → a fenced code block; <Admonition> → the matching directive; <details>/<summary> → <Accordion>/<AccordionItem> or leave as raw HTML.
• @theme/* / @site/* imports — strip @theme/* (Blume injects components globally); rewrite @site/ asset/module paths to /public URLs or inline. MDX partials (_partial.mdx imports) → inline the partial's body (Blume's default **/_* exclude already hides the partial files themselves).
• Code blocks: title="file.js" → works as-is; showLineNumbers → lineNumbers; magic comments (// highlight-next-line, highlight-start/end) → {ranges} or // [!code highlight] — unconverted they ship as literal comments in every sample; ```bash npm2yarn → ```package-install.
• MDX v1 (v2 sources) pitfalls: unescaped </{ in prose, HTML comments <!-- --> (→ {/* */}), string style="…" attributes (→ objects). Fix as build errors surface.

Frontmatter

Docusaurus	Blume
title / description	pass through
id	usually drop (routing is filesystem-based); use slug to pin a route
slug	slug
sidebar_label	sidebar.label
sidebar_position	sidebar.order
unlisted	hidden: true + noindex: true
last_update.date	lastModified
draft	draft
tags	search.tags (or drop if only used for the blog tag index)
image	seo.image
keywords	drop → use seo
sidebar_class_name / sidebar_custom_props / pagination_next / pagination_prev / pagination_label / hide_title / hide_table_of_contents / toc_min_heading_level / toc_max_heading_level / displayed_sidebar / custom_edit_url	drop (report)

Remove any duplicated H1 in the body — title renders the H1.

Icons

Docusaurus has no built-in icon-name system (icons are usually inline SVG/emoji/CSS). Where you add sidebar/tab icons, use Lucide names. Convert any FontAwesome/react-icons usage in content to Lucide <Icon> or drop it.

Teardown

Remove @docusaurus/* and Algolia deps; delete docusaurus.config.*, sidebars.*, babel.config.js, and src/ theme customizations (after the src/pages/ inventory above; re-implement what matters via defineComponents layout slots or blume eject). Repoint start/build/serve scripts → blume dev/blume build/blume preview; add blume.

Dropped — report these

Custom/swizzled theme components (layout slots or blume eject), footer columns, Algolia config, sidebar_custom_props and the other dropped frontmatter keys, createRedirects functions (→ host rules), React pages under src/pages/, <TOCInline>, per-category className/customProps, and any @theme/* component with no Blume equivalent.