blume 2.1.3 → 2.2.1

package/skills/blume-migrate/references/jekyll.md

@@ -0,0 +1,253 @@
+# Jekyll (Just the Docs) → Blume
+
+Jekyll is a Ruby static site generator: a `_config.yml`, Markdown pages with front matter, Liquid templating (`{% … %}`, `{{ … }}`) in every page, and Kramdown as the Markdown engine. Docs sites get their navigation from a theme, and the common docs theme is **Just the Docs** (JTD). The work is turning JTD's front-matter navigation into folders and `meta.ts` without moving a URL, and converting the Kramdown and Liquid in every page. Watch for six traps:
+
+- **Navigation lives in front matter** (`parent`, `nav_order`), not in folders. URLs come from the file path or `permalink`, so the nav tree and the file tree often disagree.
+- **Kramdown attribute lists (`{: .note }`) and Liquid (`{% include %}`, `{{ site.x }}`) render as literal text in a Blume `.md` page, with a green build.** Each warns at its line (`BLUME_TEMPLATE_TAG` for Liquid, `BLUME_MD_ATTRIBUTE_LIST` for an IAL). In `.mdx` both fail the build, and `blume check` names each line first: `BLUME_MDX_SYNTAX` for Liquid, `BLUME_MDX_ATTRIBUTE_LIST` for an IAL. Callouts are IALs, so most pages need converting.
+- **URLs end in a slash** (`permalink: pretty`, `/a/b/`) or in `.html` (the default), and relative links were written against those URLs.
+- **The page heading is the body `# H1`.** Front matter `title` is the nav label and `<title>`.
+- **Callout names are the site's own**, declared in `_config.yml`. An IAL whose name isn't declared, or is misspelled, rendered a plain paragraph.
+- **What a page shows depends on Liquid and CSS that ran around it** (`jekyll.environment`, `{% if %}`, `_data`, rules in `_sass/custom` that hide sections or add text). The built site is the record of what readers saw.
+
+Scope: **Jekyll 4.x with Just the Docs** (gem or `remote_theme`) is supported, and so is a JTD site that GitHub Pages builds with its own Jekyll 3 (differences flagged below). Checked against Jekyll 4.4.1, Just the Docs 0.12.0 (navigation as of 0.10: unlimited depth, `ancestor`), kramdown 2.5.2 with kramdown-parser-gfm 1.1.0, jekyll-redirect-from 0.17.0, GitHub Pages' gem set (`github-pages` 232, Jekyll 3.10.0), and an end-to-end migration of artineering-io/flair-docs (61 pages). **Plain Jekyll and other doc themes are manual** (see the end): the codemod's Kramdown, Liquid, link, and redirect passes apply to any Jekyll site; only the navigation is JTD's.
+
+## Detect
+
+- **`_config.yml`** at the root or in `docs/` (GitHub Pages' "deploy from `/docs`"). It's generic Jekyll.
+- **Just the Docs:** `theme: just-the-docs` or `remote_theme: just-the-docs/just-the-docs` (also the old `pmarsceill/just-the-docs`, with or without `@ref`) in `_config.yml`, or `gem "just-the-docs"` in the `Gemfile`. Pages carry `nav_order`/`parent`.
+- **Not Jekyll:** a `_toc.yml` beside `_config.yml` is Jupyter Book; `hexo` in `package.json` is Hexo. A `_config.yml` holding only `theme: jekyll-theme-*` publishes a repo's README with GitHub Pages: one page.
+- **Which Jekyll:** a `Gemfile` with `gem "jekyll", "~> 4…"` is 4.x. `gem "github-pages"`, or no `Gemfile` with a `remote_theme`, is GitHub Pages' Jekyll 3 (3.10 today), which also forces nine plugins on (`jekyll-optional-front-matter`, `-readme-index`, `-titles-from-headings`, `-relative-links`, `-default-layout`, `-github-metadata`, `-gist`, `-paginate`, `-coffeescript`): front-matterless Markdown files are pages, `README.md` is its folder's index when there's no `index.md`, an untitled page takes its first heading as `title`, and `[x](page.md)` links work.
+
+**Where the Blume project goes:** in the Jekyll source directory (the folder holding `_config.yml`), beside `_includes/` and the pages. Set `content.root: "."` and scope `content.include` to the page files (`["*.{md,mdx}", "docs/**/*.{md,mdx}"]`), and list Jekyll's own `exclude` Markdown (`README.md`, `CHANGELOG.md`) plus `vendor/**` and `node_modules/**` in `content.exclude`, which adds to the defaults `"**/_*"` and `"**/.*"` (`references/monorepo.md` §1). `_includes/` and `_data/` stay unpublished because of their underscore. In a code repo whose Jekyll source is `docs/`, that puts `package.json` in `docs/` and keeps `dist/` out of the repo root.
+
+## Build the old site first
+
+The old build is your URL list, your nav tree, your heading ids, and the record of what rendered. Build a copy in a folder outside the repo (`<old>` below, an absolute path), with a project-local bundle. CI usually sets `JEKYLL_ENV=production`, which switches analytics and any `jekyll.environment` branches in includes. From the Jekyll source directory:
+
+```bash
+rsync -a --exclude .git --exclude _site ./ <old>/src/ && cd <old>/src
+bundle config set --local path vendor/bundle && bundle install
+JEKYLL_ENV=production bundle exec jekyll build -d <old>/site
+cd <old>/site && find . -name '*.html' -not -path './assets/*' | sed 's|^\.||; s|/index\.html$|/|' | sort > <old>/old-urls.txt
+```
+
+No `Gemfile` (a GitHub Pages `remote_theme` site): write one with `gem "github-pages", group: :jekyll_plugins`. Recent Rubies moved `csv`, `base64`, `bigdecimal`, and `logger` out of the default gems, so under Bundler an older Jekyll fails to load them: add the one it names to the copy's `Gemfile`. If no build works, use the live site (`pin-heading-ids.mjs --old <url>`) and its `sitemap.xml`, rebuild the nav by hand, and say so.
+
+In `old-urls.txt`, a slashed entry is a page. An `.html` entry is a page on a non-`pretty` site, `404.html`, or a jekyll-redirect-from stub, which GitHub Pages serves without the `.html` (`/old` from `old.html`): `redirects.json` in the build lists those. Non-page files Jekyll copied (`LICENSE`, `.bat` scripts, a `Rakefile`) were published by accident unless a page links them: leave them out and report them. On Jekyll 4, a `.md` file with no front matter wasn't a page either: Jekyll copied it raw.
+
+## Run the codemod
+
+From the Jekyll source directory, dry-run the bundled codemod against the old build, then apply it once, before any hand edits:
+
+```bash
+node <skill>/scripts/jekyll-codemod.mjs --old <old>/site .          # report only
+node <skill>/scripts/jekyll-codemod.mjs --old <old>/site --write .
+```
+
+It's zero-dependency and deterministic, and it runs once: `--write` always writes `jekyll-migration.json` and refuses a folder that already has one, because a second pass would take each page's next H1 as its title and convert what `{% raw %}` protected. To run it again, start from a fresh copy of the Jekyll source. It reads `_config.yml` (`callouts`, `url`, `baseurl`, `permalink`, `defaults` permalinks, `exclude`, plain values for `{{ site.x }}`) and every page and Markdown partial in `_includes/`, and converts what maps exactly:
+
+- callout IALs → directives (Callouts below), `.label` → `<Badge>`, `.no_toc` and `{#id}` on headings → `[!toc]` and `[#id]`, and JTD's utility and button classes dropped; a malformed IAL, or one naming a class `callouts:` doesn't declare, rendered a plain block, so it goes and is reported;
+- the in-page TOC (the list, its `<details>`, its heading, a partial holding only a TOC), `{::comment}`, ALDs;
+- the body H1 → `title` (a different old `title` → `sidebar.label` and `seo.title`), with a variable it showed written in as its value, since Blume leaves front matter as written; an H1 inside an HTML comment or `<pre>` is skipped. The front matter keys follow the table below;
+- `{% include x.md k="v" %}` and `{% include_relative %}` → `<include k="v">/_includes/x.md</include>` (nested ones too, `{{ include.k }}` → `{{k}}`); a parameter the partial reads but the tag leaves out printed nothing in Jekyll, so it's passed as `k=""`. Also `{{ site.x }}` → `{{x}}` variables, `{{ site.baseurl }}`, `relative_url`, `absolute_url`, `{% link %}`, `{% highlight %}`, `{% comment %}`, and `{% raw %}` (unwrapped, its content untouched);
+- links: relative links resolved against each page's old URL, `.md`, `.html`, own-origin, and trailing-slash links → routes; relative Markdown images rebased from the page's new folder, and a relative raw HTML `src` → a root path (Jekyll resolved it against the page's old URL, which the new folders don't mirror);
+- with `--old`, the sidebar the old build rendered → folders, `slug`s, and `meta.ts` files (Navigation below);
+- each page that now needs MDX → `.mdx`, with void tags self-closed, comments as `{/* */}`, a bare `<` as `&lt;`, autolinks as links, and page `<script>`/`<style>` removed, inline code left as written; partials such a page includes get the same;
+- `redirect_from`, `redirect_to`, `.html` URLs, and the variables → `jekyll-migration.json`, for the config:
+
+```ts blume.config.ts
+import { defineConfig } from "blume";
+
+import migration from "./jekyll-migration.json" with { type: "json" };
+
+export default defineConfig({
+  redirects: migration.redirects,
+  variables: migration.variables,
+});
+```
+
+**Every `REVIEW` line is a to-do**, and the sections below say what to do with each: HTML includes, Liquid logic, unknown front matter, MDX hazards (a brace in prose, an indented code block), the CSS rules that hid or added content, and the theme files. A `{{ name }}` that `{% raw %}` kept as written collides with a variable of the same name, which Blume fills in everywhere, code included: rename the variable (its key in `jekyll-migration.json` and the `{{name}}` references the codemod wrote). A site whose `_config.yml` has no `callouts:` (before JTD 0.4 added the option, sites styled `.note`/`.warning` in `_sass/custom/custom.scss`) keeps its callout IALs, and the dry run says so: read those rules for the names, then pass `--callouts note,warning` on the write run.
+
+After the first `blume build`, pin the old heading ids, rebuilding until it reports 0. Jekyll's GFM ids drop underscores (`f_position` → `#fposition`) where Blume keeps them, so about one id in twenty differs:
+
+```bash
+node <skill>/scripts/pin-heading-ids.mjs --old <old>/site --write
+```
+
+## Config: `_config.yml` → `blume.config.ts`
+
+Apply `defaults:` (front matter defaults) to the pages in each `scope.path` that the codemod didn't see through: they often set `layout`, and sometimes `parent` or `nav_exclude`.
+
+| Jekyll | Blume |
+| --- | --- |
+| `title` / `description` | `title` / `description` |
+| `url` | `deployment.site`, unless the target is Vercel or Netlify (SKILL.md). GitHub Pages with a custom domain needs it |
+| `baseurl` (`/repo`) | `deployment: { base: "/repo" }`. **The deployed URL decides:** the GitHub Pages starter workflow passes `--baseurl` from the Pages settings, so a custom domain (a `CNAME`) serves at the root whatever `_config.yml` says |
+| `exclude` / `include` | `content.exclude` / `content.include` (Detect) |
+| `permalink`, `defaults`, `collections` | URLs; above; Collections and posts |
+| `plugins` | Plugins |
+| `kramdown.syntax_highlighter_opts.block.line_numbers: true` | no site-wide switch: drop it and report it. Code without line numbers copies cleanly |
+| `kramdown.toc_levels`, and pages built on H4 sections | Blume's outline shows H2–H3, where Kramdown's TOC listed every level. Count the H4s: when they carry the page (attribute references), set `toc: { maxHeadingLevel: 4 }`; else report it |
+| other `markdown`, `kramdown`, `highlighter`, `sass`, `compress_html`, `liquid` keys | drop |
+| `github_username`, `twitter`, `social.links`, a Discord link | `footer.socials` (bluesky, discord, facebook, github, hacker-news, instagram, linkedin, medium, podcast, reddit, slack, telegram, threads, website, x, youtube) |
+| `repository` (jekyll-github-metadata) | `github: { owner, repo }` |
+| `logo` | `logo`, file moved to `public/`. JTD shows the logo _instead of_ the title, so a wordmark needs `logo: { image, text: "" }`; a custom `_includes/title.html` that shows both keeps the text |
+| `favicon_ico` | the file at `public/favicon.ico` (no config field) |
+| `color_scheme: dark` | `theme.mode: "dark"`. `light`/unset → omit. A custom scheme (`_sass/color_schemes/<name>.scss`): its `$link-color` → `theme.accent` (`$blue-000` is `#2c84fa`; look the rest up in the theme's `_sass/support/_variables.scss`), and an `@import "./color_schemes/dark"` in it → `theme.mode: "dark"` |
+| `aux_links` (`"Label": "url"` or `["url"]`) | `navigation.actions: [{ label, href }]`. `aux_links_new_tab` → drop (Blume opens `http(s)` header links in a new tab) |
+| `nav_external_links` (`title`, `url`) | `navigation.featured` (above the sidebar, where JTD listed them below the pages) |
+| `search_enabled: false` | `search: false`. `search.*` options → drop |
+| `nav_enabled: false` | no site-wide switch: `mode: center` on the pages that showed no sidebar |
+| `mermaid` | delete; ` ```mermaid ` renders natively in `.mdx` |
+| `ga_tracking` | `googleAnalytics({ id })` from `blume/analytics`, one per `G-` id in the comma list. A `UA-` id no longer collects data: report it |
+| `gh_edit_link` + `gh_edit_repository` + `gh_edit_branch` | `github: { owner, repo, branch }`. `gh_edit_source: docs` → `github.dir: "docs"` when `blume.config.ts` sits there |
+| `last_edit_timestamp` | `lastModified: "frontmatter"` when pages set `last_modified_date` (the codemod maps it), else drop: JTD showed no date without it |
+| `footer_content` / `_includes/footer_custom.html` | links → `footer.links`, social links → `footer.socials`; copyright text → `footer.copyright`, plain text: strip the tags, decode entities (`&copy;` → `©`), and turn a Liquid year (`{{ "now" \| date: "%Y" }}`) into `${new Date().getFullYear()}` in a template literal; other text → drop (report) or a `Footer` layout slot (`defineComponents`) |
+| `callouts`, `heading_anchors`, `enable_copy_code_button`, `back_to_top*`, `nav_sort`, `nav_error_report`, `ga_tracking_anonymize_ip`, `gh_edit_link_text`, `gh_edit_view_mode` | drop (the codemod read `callouts`) |
+
+## Navigation: front matter → folders and `meta.ts`
+
+JTD builds one tree from `title`, `parent`, `grand_parent`/`ancestor`, and `nav_order`, wherever the files sit, and shows it as a collapsible tree with only the current section open: set **`navigation.sidebar.display: "group"`**. The codemod rebuilds the tree from the sidebar the old build rendered, so `nav_order` ties, `child_nav_order: reversed`, and `nav_sort` are already resolved, and keeps every URL:
+
+- A parent at `dir/index.md` with its children in `dir/` (the layout JTD's docs recommend) moves nothing.
+- A parent that's a leaf file with its children beside it (`docs/setup.md`, `docs/install.md`) becomes a `(group)` folder: `docs/(setup)/index.md` with `slug: docs/setup`, and the children inside it keep their URLs.
+- A child whose file sits elsewhere moves under its parent with `slug: <old route>`. A child _section_ whose folder sits elsewhere is reported: `git mv` it into the parent's folder (into a `(group)` folder, its URLs stay; into a real one, pin each page's `slug`), or leave it. The parent's `meta.ts` already lists it by its folder name.
+- **A `parent` title that names two pages** (two sections both titled "Setup", told apart by neither `grand_parent` nor `ancestor`): JTD listed the child under both. Blume lists a page once, so it stays under the first and the codemod reports it.
+- Each folder gets a `meta.ts`: `pages` in the old order; `title` only where Blume's label for the folder (its name, humanized) differs from JTD's; `directory: "accordion"` where the old parent page listed its children (JTD's `has_toc`, read from the old build), and `"none"` below it where a page didn't, since `directory` inherits.
+- **The duplicate index row:** Blume links a folder's `index` from the group row and lists it again as the first row, where JTD showed it once. The codemod hides that row (`sidebar.hidden: true`); a page the group row links stays in the sitemap, search, and `llms.txt`. `BLUME_NAV_INDEX_TITLE_MISMATCH`, which fails `validate --strict`, flags a hidden index whose `title` differs from its folder's `meta.ts` `title`, unless its `sidebar.label` names the folder title. An index whose H1 differed from its JTD title gets that title as `sidebar.label`, which is the section label, so it passes too. Where neither the page's `title` nor its `sidebar.label` matches the section label (JTD always labeled a section with its page's `title`, so this is rare), the codemod leaves the row visible and says so. The check accepts three ways out: match the two titles, set the page's `sidebar.label` to the folder title, or show the row (remove `sidebar.hidden`).
+- Pages outside the old sidebar (`nav_exclude`, no `title`, a `parent` that matched nothing) get `sidebar.hidden: true`, which also takes them out of search, the sitemap, and `llms.txt`, where JTD still searched them: set `search: { indexing: { includeHiddenPages: true } }` if they should stay searchable. A hidden home page is the exception: the root URL serves it, so it stays listed. An external `nav_external_links` entry is listed for `navigation.featured`.
+
+What's left for you:
+
+- **A wrapper folder JTD never showed** (the template's `docs/`, any folder whose pages sit at the nav's top level) becomes one group around them. Blume opens a group that's the sidebar's only top-level row by itself, but one beside the home page's row or another section starts closed off its own pages, so the codemod writes `collapsed: false` in its `meta.ts`. A `navigation.tabs` entry instead lifts its pages to the sidebar's top level, but there pages list above groups, so JTD's interleaved order breaks. Keep the group unless the user asks for a tab.
+- **The home page** (`index.md`, often `layout: home` and untitled) stays the content root's `index`. When the old nav never showed it, the codemod hides its row like any page outside the nav; a hidden home page stays in the sitemap, search, and `llms.txt`. Give it a `title` (Blume renders it as the H1, where JTD showed none) or `mode: frame` to keep the sidebar without one. Where the home page headed a JTD section, Blume's root index can't head a group: its children stay in their folders, and the codemod reports it.
+- **Moving a page changes what its relative images resolve against.** The codemod rebases the Markdown images it converted, and turns a relative raw HTML `src` into a root path, with a REVIEW to serve that file from `public/`.
+
+## URLs and redirects
+
+A Jekyll page's URL, for `dir/name.md`:
+
+| `permalink` (global) | `dir/name.md` | `dir/index.md` | Blume route |
+| --- | --- | --- | --- |
+| `pretty` | `/dir/name/` | `/dir/` | `/dir/name`, `/dir` |
+| unset (`date`), `none`, `ordinal` | `/dir/name.html` | `/dir/` | same |
+| a style ending in `/` / in `:output_ext` / neither | `/dir/name/` / `.html` / `/dir/name` (file `name.html`) | `/dir/` | same |
+
+A page's own `permalink:` wins, then one `defaults:` sets for its folder (the most specific `scope.path`), then the global style. The codemod applies all three, and with `--old` it checks each URL against the build: a page the build doesn't have at that URL gets a REVIEW and no `.html` redirect. Blume serves `<route>/index.html`, so `/dir/name/` keeps working on static hosts, and `blume dev` and `preview` redirect it to `/dir/name`.
+
+- **`.html` URLs** become one exact redirect each (a pattern can't strip a suffix). Never add one from `/dir/`, `/dir/index.html`, or `/index.html` (SKILL.md, Redirects).
+- **`redirect_from`** values become redirects as written (`/old` and `/old/` are different `from`s), keeping case (`/w/Main_Page`); one that is the page's own URL is skipped. **`redirect_to`** becomes a redirect from the page's route, and an empty page with it is deleted.
+- **Raw HTML** (`<a href>`, `<img src>`, `<video><source src>`) gains `deployment.base` on a root path, as a Markdown link does, so the root paths the codemod writes from relative links, `{{ site.baseurl }}`, `relative_url`, and `{% link %}` need nothing more. `blume validate` checks a raw `<a href>` against the routes and a media `src` against `public/`.
+- **Jekyll 3's `{% link %}`** doesn't add `baseurl` (Jekyll 4's does, so `{{ site.baseurl }}{% link … %}` doubled it there). The codemod drops both: Blume adds the base itself.
+
+## Content: what the codemod leaves
+
+**HTML includes** (`{% include x.html … %}`) are never spliced: `<include>` embeds a non-Markdown file as code. Replace each use and delete the partial when nothing uses it:
+
+- a figure → a Markdown image, or `<Frame caption="…">` around it;
+- a YouTube iframe → `<YouTube url="…" />`, inside `<Frame caption>` when the include printed a caption; a `width` → drop (report). A playlist URL (`/embed/videoseries?list=…`) works as written;
+- a row of embeds or code blocks in a flex `<div>` → `<Columns cols={2}>`;
+- a jQuery UI accordion (`$(".accordion").accordion()` over alternating question lines and answer `<div>`s) → `<Accordion>` with one `<AccordionItem title>` per question, the first `defaultOpen` as jQuery UI opened it; an `<details>` with Markdown in it → `<Expandable title>` (MDX wraps a `<summary>` and the text after it in one paragraph);
+- a note include (`note.html`, `callout.html`) → a directive.
+
+**Liquid logic** (`{% if %}`, `{% for %}`, `{% assign %}`, `{% capture %}`, a dynamic `{% include {{ var }} %}`, a parameter passed as a variable) → the output the old build shows: split a partial with `{% if include.x %}` into one partial per variant, write a `_data` loop's output once as Markdown, inline `{{ page.x }}`. A `{{ site.x }}` that isn't a plain value in `_config.yml` is left too. Liquid ran inside fenced code as well, unless wrapped in `{% raw %}`, so a REVIEW in a code block means the old page showed the rendered value.
+
+**CSS that changed content.** The codemod lists every `display: none` and `content: "…"` rule in `_sass/` and `assets/css/`. Find what each targets in the pages: content a rule hid wasn't shown, so delete it (and report the anchors that go with it); text a `::before`/`::after` added (`.label::before { content: "New: " }`) belongs in the converted element's text.
+
+**MDX hazards** the codemod lists in `.mdx` pages: a brace in prose (escape it `\{` or put it in backticks), an indented code block (fence it), anything else the build names with a line. A partial with a hazard fails the build at the partial's own line (`blume check` warns `BLUME_MDX_SYNTAX` there first), and an unclosed `<img>` in a partial doesn't fail at all: it pulls the rest of the partial inside its parent element. The codemod self-closes the ones it sees, and `BLUME_MDX_UNCLOSED_ELEMENT` names the partial's line for any left.
+
+**A title in a partial:** a page that's only `{% include api/x.md %}` takes its heading from the partial's H1. Move it into the page's `title` (plain text: no `<kbd>` or backticks) and out of the partial, or Blume renders two.
+
+**Also by hand:** definition lists (`Term` + `: Definition` → a list or `<dl>`), `*[ABBR]:` abbreviations (delete), Font Awesome `<i class="fa…">` icons (`<Icon icon>` with a Lucide name, or drop), and page scripts the codemod removed (an island, a `PageFooter` slot, or static content: two images instead of a before/after slider).
+
+### Callouts
+
+JTD has no built-in callout names: each site declares its own under `callouts:` with a `color` and an optional `title`, which JTD printed uppercase above every callout of that name. The codemod maps by the name's meaning, then by color:
+
+| JTD name (template color) | Blume |
+| --- | --- |
+| `note` (purple), `important` (blue) | `:::note`, `:::important` (an alias of note) |
+| `tip`, `hint` | `:::tip` |
+| `info`, `highlight` (yellow, untitled) | `:::info` |
+| `warning`, `attention`; `caution` | `:::warning`; `:::caution` (an alias of warning) |
+| `danger`; `error` | `:::danger`; `:::error` (an alias of danger) |
+| `new`, `success` (green) | `:::success` |
+| any other name | by its color: blue → `info`, green → `success`, yellow → `warning`, red → `danger`, purple or grey → `note` |
+
+Blume shows a type's icon, not its name, so a configured `title` that only names the directive is dropped and one that says more is kept (`new` titled "New" → `:::success[New]`). `{: .note-title }` takes its title from the blockquote's first paragraph. A callout class on a list, table, or code block rendered no box in JTD (it styles only paragraphs and blockquotes), so it's dropped. The codemod applies each IAL to the block Kramdown did: a list or blockquote that follows a paragraph without a blank line is its own block, and an IAL with blank lines on both sides applies to the next block. An IAL indented under a list item sat inside the item, where Kramdown sometimes boxed the item's paragraph: those are reported, so check the old page and write the callout inside the item by hand.
+
+## Front matter
+
+The codemod maps these, and reports every other key Blume's strict schema rejects:
+
+| Jekyll / JTD | Blume |
+| --- | --- |
+| `title` + body H1 | `title` = the H1; a different old title → `sidebar.label` and `seo.title` |
+| `description`, or `summary` (JTD showed it in child lists) | `description`. JTD only put it in `<meta>`; Blume shows it under the title (report) |
+| `layout: default` / `page` / `home` / `post` / `about` | removed |
+| `layout: minimal`, `nav_enabled: false` | `mode: center` |
+| a custom `layout` from `_layouts/` | reported: pick a `mode` or a custom `.astro` page |
+| JTD nav keys, `permalink`, `redirect_from`, `redirect_to` | removed (Navigation, URLs) |
+| `search_exclude: true` | `search: { exclude: true }` |
+| `last_modified_date` | `lastModified` (ISO date) |
+| `published: false` | `draft: true` |
+| `image` (a string, or `{ path }`), `canonical_url` | `seo.image`, `seo.canonical` |
+| jekyll-seo-tag's `seo:` `type`/`name`/`links` | removed |
+| `sitemap: false` | reported: `seo: { noindex: true }` if it shouldn't be indexed, else delete |
+| `author`, `date`, `lang`, `tags`, `categories`, `excerpt`, `toc` | reported: delete (`tags` → `search.tags` if a hosted search filters on them) |
+
+## Theme, layouts, and assets
+
+- **`_sass/custom/custom.scss`** → a project-root `theme.css` with only the rules whose markup still exists (figure classes, flex rows): JTD selectors (`.main-content`, `.site-nav`, `.site-title`) match nothing in Blume. Turn hard-coded colors into Blume's tokens.
+- **Theme hook includes** (the codemod lists them): `head_custom.html` (favicons → `public/`, `<meta>` → `seo.metatags`, analytics → adapters, icon-font CSS → drop), `header_custom.html` (an announcement → `banner`), `footer_custom.html` (Config), `title.html` (→ `logo`), `nav_footer_custom.html`, `search_placeholder_custom.html`, `toc_heading_custom.html`, `mermaid_config.js`, `js/custom.js`, `lunr/*` → drop and report what each did.
+- **`_layouts/`** and `.html` pages with front matter → `.mdx` (with `mode: custom` for a landing page) or a custom `.astro` page. `404.html`/`404.md` → delete (Blume ships one).
+- **Assets:** a folder the old site served by root path (`/media/…`, `/assets/images/…`) moves whole to `public/` at the same path. Keep files no page references: other sites may link them. List them, and prune only once the user confirms. JTD's own `assets/css` and `assets/js` go.
+- **Root files** (`favicon.ico`, `apple-touch-icon.png`, `site.webmanifest`, `.well-known/`) → `public/`. A `robots.txt` replaces Blume's generated one: keep it only if it says something Blume's doesn't. `CNAME` and `.nojekyll` aren't needed with a GitHub Actions deploy.
+
+## Collections and posts
+
+- **A JTD collection** (`collections: { docs: { output: true, permalink: "/:collection/:path/" } }` plus `just_the_docs.collections.docs.name`): rename `_docs/` → `docs/` so the URLs stay `/docs/…`, then run the codemod; give the folder a `meta.ts` `title` from `name`. `nav_fold: true` → `collapsed: true`. A collection document without `title` took its filename as one: write it in.
+- **`_posts/`** → `type: blog` pages (`docs/advanced/blog.mdx`), with `slug` pinned to the old dated URL (`/:categories/:year/:month/:day/:title.html` by default, so also an `.html` redirect) or redirected; `{% post_url %}` → the post's route; jekyll-feed's `/feed.xml` → a redirect to `/blog/rss.xml`.
+
+## Plugins
+
+| Plugin | Blume |
+| --- | --- |
+| `jekyll-redirect-from` | `redirects` (the codemod) |
+| `jekyll-seo-tag`, `jekyll-sitemap` | built in (the sitemap needs `deployment.site`) |
+| `jekyll-relative-links` | built in: the codemod turns `.md` links into routes |
+| `jekyll-include-cache` (`include_cached`) | same as `include` |
+| `jekyll-remote-theme`, `jekyll-default-layout`, `jekyll-optional-front-matter`, `jekyll-titles-from-headings`, `jekyll-readme-index` | delete; the old build shows the pages and titles they made |
+| `jekyll-github-metadata` (`site.github.*`) | inline the values; `repository` → `github` |
+| `jekyll-last-modified-at` | `lastModified: "git"` |
+| `jemoji` (`:smile:`), `jekyll-mentions` (`@user`), `jekyll-gist` | paste the emoji; write the links; a link or a fence |
+| `jekyll-paginate`, `jekyll-coffeescript`, `jekyll-sass-converter`, `jekyll-compose` | drop |
+| anything else (`_plugins/*.rb` included) | read what it does; report it |
+
+## Plain Jekyll and other themes: manual
+
+Run the codemod without `--old` (or with it, for the URLs): its content and link passes apply to any Jekyll site. The navigation source differs, and there's no tested mapping for it:
+
+- **Plain Jekyll / minima:** `header_pages` (a list of files) or no nav. Lay out folders by topic and report the new sidebar.
+- **Minimal Mistakes** (docs layout): `_data/navigation.yml` holds the sidebar (a key such as `docs:` listing `title` + `children: [{ title, url }]`), and pages opt in with `sidebar: { nav: "docs" }`. Convert it like a config-declared nav (SKILL.md). Notices `{: .notice }` and `.notice--primary`/`--info`/`--warning`/`--success`/`--danger` → pass those names with `--callouts` and map the types by hand; `toc: true` and `toc_*` → delete.
+- **Documentation Theme for Jekyll:** `_data/sidebars/*.yml` (`entries` → `folders` → `folderitems`, then `subfolders` → `subfolderitems`), with `sidebar: <file>` and a flat `permalink: name.html` on every page. `{% include note.html content="…" %}` (also `tip`, `warning`, `important`, and `callout.html` with a `type`) → directives; `summary` → `description`; `keywords` → `search.keywords`; `last_updated` → `lastModified`.
+
+## Repo integration and teardown
+
+- **`package.json`** beside `blume.config.ts` (a Ruby site has none: scaffold it), Node 22.19+, `.gitignore` for `node_modules/`, `.blume/`, `dist/`, `.env.local`.
+- **CI:** replace `bundle exec jekyll build` and the Pages starter workflow with the Blume one (https://useblume.dev/guides/markdown-docs-github-pages). Its `npm ci` needs a lockfile, so commit the `package-lock.json` from `npm install` in the same change. A branch-deployed Pages site moves its source to GitHub Actions in the repo settings, where the custom domain also stays: list both as manual steps. Dependabot's `bundler` entry → `npm`. Scripts that wrapped Jekyll (`serve.bat`, `Rakefile`) → delete or repoint.
+- **Delete** `_config.yml`, `Gemfile`, `Gemfile.lock`, `_layouts/`, `_sass/`, theme hook and HTML includes, JTD's `assets/` files, `_site/`, `.jekyll-cache/`, and `vendor/bundle/`, once everything they declared is harvested. Keep `_includes/` partials pages still `<include>`, and `jekyll-migration.json`.
+- **Grep the whole repo** for moved page paths and for `jekyll` (CODEOWNERS, link checkers, a README "build the docs" section).
+
+## Leftover check
+
+Rerun until it prints only code samples, `{{name}}` variables and include props you defined, and relative links you meant:
+
+```bash
+grep -rnE '\{:[ .#a-z:]|\{%|\{\{|^\*\[|^: |markdown="|<i class="fa|\.html[)#"]|\]\(\.\.?/[^).]*\)|\]\(/[^)]*/(#[^)]*)?\)' \
+  --include='*.md' --include='*.mdx' --exclude-dir={node_modules,vendor,_site,.blume,dist} .
+```
+
+## Dropped — report these
+
+Callout title labels that only named the type, unconfigured or malformed callout IALs left plain, the button and label styling the codemod dropped, `nav_external_links` moved above the sidebar, `back_to_top`, other `footer_content` text and links inside the copyright, theme hooks, custom color schemes beyond the accent, `_sass` rules with no Blume target, content a CSS rule hid, site-wide code line numbers, deeper TOC levels, `UA-` analytics ids, `sitemap: false`, abbreviations, definition-list styling, Liquid logic and `_data` loops now frozen as content, embed widths, page scripts and widgets (sliders, accordions) not rebuilt, icon-font icons with no Lucide match, accidentally published files (`LICENSE`, `.bat`), and every plugin removed without an equivalent.

package/skills/blume-migrate/references/mdbook.md

@@ -0,0 +1,256 @@
+# mdBook → Blume
+
+mdBook is the Rust project's book generator: a `book.toml`, a hand-written `SUMMARY.md` that is the whole table of contents, and chapters in `src/` rendered by pulldown-cmark after preprocessors rewrite them (the built-in `links` expands `{{#include}}`; plugins like mdbook-admonish and mdbook-mermaid add the rest). Watch for five traps:
+
+- **Every URL ends in `.html`** (`src/guide/setup.md` → `/guide/setup.html`, a `README.md` → `index.html`), so every chapter that isn't an index needs an exact redirect.
+- **`SUMMARY.md` is the only navigation, and its nesting rarely exists on disk.** A parent chapter is a page _and_ a group, and its file sits beside its children's folder (`guide.md` + `guide/`) or flat next to them.
+- **`{{#include}}` pulls code from anywhere in the repo, by `ANCHOR` name or line range.** Blume's `<include>` takes whole files from inside the content root only, so code the crate compiles goes through generated excerpts (Includes). Anchors that no longer exist rendered as empty blocks on the old site, with no warning, so expect several.
+- **Fences carry Rust-only syntax.** Hidden `# ` lines and attributes like `rust,ignore` show up as code or kill highlighting if left alone.
+- **The page heading is the body H1, but the sidebar label and `<title>` are the `SUMMARY.md` text**, and the two often differ.
+
+Scope: mdBook 0.4.x and 0.5.x, checked against 0.4.48, 0.4.52, and 0.5.4, mdbook-admonish 1.19.0, mdbook-mermaid 0.15.0, and an end-to-end migration of the Linera manual (39 chapters, mdBook 0.4.48). The syntax of mdbook-katex, -toc, -tabs, and -alerts comes from their docs; it wasn't run.
+
+## Detect
+
+- **`book.toml`**, with `[book]` and usually `[output.html]` tables: only mdBook uses it. It sits at a standalone book's root or in a folder of a code repo (`docs/`, `book/`, `doc/`, `guide/`, `mdbook/`). The chapters live in `[book] src` (default `src/`), which can point outside that folder (`src = "../docs"`).
+- **`SUMMARY.md`** in that `src`. GitBook and HonKit use `SUMMARY.md` too, but with `.gitbook.yaml` or `book.json`, never `book.toml`.
+- CI that runs `mdbook build`/`mdbook test`, `peaceiris/actions-mdbook`, or `cargo install mdbook mdbook-<plugin>`. The workflow that deploys may live in another repo (one that checks the code repo out as a submodule).
+- **Fingerprint the version** from the CI pin. 0.5 removed `curly-quotes`, `multilingual`, `google-analytics`, and `copy-fonts`, rejects unknown `book.toml` keys, and fails on plugins built for 0.4 (mdbook-admonish 1.19.0 and mdbook-mermaid 0.15.0 both do), so most books with plugins still build with 0.4.x.
+
+**Where the Blume project goes.** Beside `book.toml`, the folder `mdbook build` ran in, with `content.root` set to the book's `src` (Blume's default is `docs`, so set it unless `src = "docs"`). That keeps `package.json`, `public/`, and `dist/` out of a Rust repo's root. mdBook has no manifest: scaffold `package.json` there (SKILL.md step 6). **A `src` outside that folder (`"../docs"`) works**, edit links included, and a `meta.ts` there imports `defineMeta` from `blume` as usual. That import needs a Blume release after 2.1.3: earlier ones resolved `blume` only from the meta file's own folder up, so it failed with `BLUME_META_LOAD_FAILED … Cannot find module 'blume'`. On those, export a plain object instead (`export default { title: "Developers", display: "flat", pages: […] };`).
+
+## Build the old book first
+
+Before changing anything, build the book with the version CI pins and its plugins, into a folder outside the repo. Prebuilt binaries of mdBook and most plugins are on their GitHub releases pages (mdbook-admonish has none for Apple Silicon: `cargo install --root <scratch> mdbook-admonish@<version>`); install them in a scratch folder, not globally.
+
+```bash
+mdbook build <book-root> -d /abs/path/old-book
+MDBOOK_OUTPUT='{"markdown": {}}' mdbook build <book-root> -d /abs/path/old-md
+(cd /abs/path/old-book && find . -name '*.html' ! -name print.html ! -name toc.html ! -name 404.html | sed 's|^\.||' | sort) > old-urls.txt
+```
+
+- `old-book` is the old site: its `.html` files are the old URLs, its headings carry the old ids, and its pages show what readers saw. With two or more `[output.*]` tables (`[output.linkcheck]` counts), the HTML lands in `old-book/html/`: use that folder wherever this file says `old-book`.
+- `old-md` is each chapter as Markdown after `{{#include}}` and the other helpers ran (admonish blocks stay as written): what every include actually showed.
+- Under 0.4 a missing plugin only warns, and its blocks render as code; the URLs are still right. Under 0.5 it fails unless `optional = true`.
+
+## Config: `book.toml` → `blume.config.ts`
+
+Map only what's set. CI can override keys with `MDBOOK_BOOK__…`/`MDBOOK_OUTPUT__…` environment variables, so read those too.
+
+| `book.toml` | Blume |
+| --- | --- |
+| `[book] title` | `title`. Unset, mdBook showed no title: take the first chapter's H1, or ask |
+| `description` | `description` |
+| `src` | `content.root` |
+| `language` (not `en`) | a one-locale `i18n` block (`i18n: { defaultLocale: "fr", locales: [{ code: "fr", label: "Français" }] }`); `text-direction = "rtl"` → that locale's `dir: "rtl"` |
+| `authors`, `multilingual`, `[rust] edition`, `[build] build-dir`, `create-missing`, `extra-watch-dirs` | drop. With `create-missing` (on by default) mdBook created an empty page for a `SUMMARY.md` entry whose file was missing: check the old build |
+| `use-default-preprocessors = false` | without `[preprocessor.links]`/`[preprocessor.index]`, `{{#…}}` stayed literal and `README.md` stayed `README.html`: read the old build |
+| `[output.html] site-url = "/repo/"` | `deployment: { base: "/repo" }`. It's a path, not an origin |
+| `cname` | `deployment: { site: "https://<cname>" }`; GitHub Pages isn't auto-detected. A project site with no domain → `{ site: "https://<owner>.github.io", base: "/<repo>" }` |
+| `git-repository-url` on GitHub | `github: { owner, repo }`. Elsewhere → `navigation.actions` (report) |
+| `edit-url-template` | `github.branch` from the segment after `edit/` or `blob/`. Set `github.dir` to the Blume project's path in the repo (`git rev-parse --show-prefix`), not the template's prefix: mdBook fills `{path}` with `<src>/<file>`, so a `src` outside the book root gave the old site broken edit links (`…/edit/main/../docs/x.md`) |
+| `default-theme`, `preferred-dark-theme` | mdBook switches between them on the reader's system preference. Both dark (`coal`, `navy`, `ayu`) → `theme.mode: "dark"`; a light one plus a dark one → omit. A theme switcher deleted from `theme/index.hbs`, or a stylesheet that repaints the default theme, forces one look: read the CSS, not the name |
+| `additional-css` | a root `theme.css` with only the rules whose markup still exists (`.content`, `.sidebar`, `.chapter`, `--links`, `--sidebar-*` match nothing). Read brand colors and fonts into `theme.accent`, `theme.background`, and `theme.fonts`; Blume already defaults to Inter and IBM Plex Mono. Delete `mdbook-admonish.css` |
+| `additional-js` | delete the mermaid, admonish, and KaTeX assets. A gtag loader → `googleAnalytics({ id })` from `blume/analytics`; other scripts → `script()` or report |
+| a `theme/` folder | diff it against `mdbook init --theme` from the same version first: stock files carry nothing to port, and the stock `favicon.png`/`favicon.svg` are mdBook's own logo (report, don't copy). Custom ones: `<head>` meta tags → `seo.metatags`; analytics → adapters; a favicon → `public/`; fonts → `theme.fonts`; the rest drops (report) |
+| `google-analytics` (0.4) | `googleAnalytics({ id })` for a `G-` id; report a `UA-` id |
+| `mathjax-support` | Math (Other syntax) |
+| `smart-punctuation` / `curly-quotes` | Blume always converts quotes and dashes. Where the old site had it off (0.4's default), `--flag` in prose becomes an en dash: put flags in backticks |
+| `no-section-label` | nothing. Without it, mdBook numbered the chapters (`1.`, `2.3.`) in the sidebar, and Blume can't: report it, and fix prose that cites "chapter 4" |
+| `input-404`, `src/404.md` | delete the page; Blume ships a 404 (`pages/404.astro` to customize) |
+| `[output.html.search]` | built in: drop. `search.chapter."<path>" = { enable = false }` → `search: { exclude: true }` on those pages |
+| `[output.html.fold]` | Navigation |
+| `[output.html.redirect]` | URLs and redirects |
+| `[output.html.playground]`, `[output.html.code.hidelines]` | Code blocks |
+| `[output.html.print]`, `hash-files`, `copy-fonts`, `sidebar-header-nav`, `git-repository-icon`, `definition-lists`, `admonitions`, `live-reload-endpoint`, `[output.markdown]` | drop |
+| `[output.linkcheck]`, `[output.linkcheck2]` | `blume validate --strict` (`--external` for web links) |
+| other backends (EPUB, PDF) | `export: { pdf: true }` prints one page at a time; a whole-book PDF or EPUB has no equivalent (report) |
+
+## Preprocessors
+
+| `[preprocessor.X]` | Blume |
+| --- | --- |
+| `links` (built in) | Includes |
+| `index` (built in) | rename every `README.md` chapter to `index.md` |
+| `admonish` | Admonitions |
+| `mermaid` | ` ```mermaid ` works as written in `.mdx`; delete `mermaid.min.js` and `mermaid-init.js` (theme settings in `mermaid-init.js` drop) |
+| `katex` | `$…$` → `$$…$$` inside its sentence; `$$` blocks stay; `\$` → `$`. Custom delimiters → convert from those. A `macros` file has no equivalent: expand the macros |
+| `toc` | delete the `<!-- toc -->` marker (or the configured `marker`): the outline rail replaces it |
+| `pagetoc`, `open-on-gh` | built in (outline rail; `github` edit links): delete |
+| `alerts` | GitHub alerts (Admonitions) |
+| `tabs` | `{{#tabs}}` / `{{#tab name="X"}}` … `{{#endtab}}` / `{{#endtabs}}` → `<Tabs>` / `<Tab title="X">`. `global="…"` drops: Blume syncs same-titled tabs page-wide |
+| `i18n-helpers` (gettext, `po/*.po`) | i18n (Repo integration) |
+| `cmdrun` (`<!-- cmdrun … -->`), `template`, custom ones (`command = "cargo run …"`) | diff `old-md/` against `src/` to see what each one wrote, then freeze that output or move the generator into a prebuild script (report) |
+| `linkcheck` | `blume validate --strict` |
+| other diagram plugins (graphviz, plantuml, svgbob) | render each diagram to an SVG once and commit it, or redraw it in mermaid (report) |
+| anything else | read what it does; report it |
+
+## Navigation: `SUMMARY.md` → folders and `meta.ts`
+
+### How mdBook reads `SUMMARY.md`
+
+- A `# Summary` first line is ignored. **Prefix chapters** are bare `[Title](file.md)` lines before the first list, and can't nest. **Part titles** are `# Title` headings (h1 only) over the numbered chapters that follow: plain headings, not links. **Numbered chapters** are list items (`-`, `*`, or `1.`) that nest by indentation. **Suffix chapters** are bare links after the last list. A **draft** is `[Title]()` (a greyed-out entry, no page). A **separator** is a `---` line; it can also split one part's list, leaving chapters after it under no visible heading.
+- Only listed chapters render. Any other `.md` under `src/` isn't published, but every non-Markdown file there is copied to the site at its own path.
+- A chapter's URL is its path with `.html`; a `README.md` (any case) becomes `index.html`. **The first chapter is also written to `/index.html`.** Its sidebar label and `<title>` are the `SUMMARY.md` text (plus ` - <book title>`); the page shows its own H1.
+
+### Put every chapter in place
+
+Keep each chapter's path, so its route is the old URL minus `.html`, and keep a table of old URL → file → route as you go: it becomes `redirects`.
+
+- **Every `README.md` chapter → `index.md`.** Its route is the folder's, which `x/index.html` already served. Left as is, Blume publishes it at `/x/README`.
+- **A parent chapter beside its children's folder** (`guide.md` + `guide/`): `git mv guide.md guide/index.md`. The route stays `/guide` and the folder row links to it; left in place, `guide.md` is a separate page beside an unlinked "Guide" group. The page moved a level deeper: rewrite its relative links, images, and include paths, and every link to `guide.md`.
+- **Children flat beside their parent** (`ch03-00-concepts.md`, `ch03-01-variables.md`): a `(group)/` folder holding the parent as `index.md` with `slug: ch03-00-concepts`, plus the children. The group adds no URL segment, the `slug` keeps the parent's route, and the group row links to it. Rebase relative paths in every moved file.
+- **The first chapter**, when it isn't the root `README.md`: move it to the content root's `index.md` and redirect its own URL to `/` (`{ from: "/introduction.html", to: "/" }`), since mdBook served it at both.
+- **Ordering prefixes.** Blume drops a leading `\d+[-_.]` from every segment, keeping versions (`1.2.0`) and dates (`2024-01-05`, `12-05-2022`, `2024-01`) whole (`00-overview.md` → `/overview`). Every old URL is redirected anyway, so let Blume drop them (they keep ordering the sidebar) and point those redirects at the new routes, or pin `slug` on each page to keep the old path. Say which.
+- **Files `SUMMARY.md` doesn't list** were never published: a contributors' `README.md` beside the chapters, notes, Markdown that `{{#include}}` pulls in. Prefix them with `_`, move them out of the content root, or add them to `content.exclude` (it adds to the defaults `"**/_*"` and `"**/.*"`). Report them.
+- **A chapter whose body is a `<meta http-equiv="refresh" content="0; url=…">`** is a redirect, not a page to keep: add a redirect from its `.html` URL to the target, a `navigation.featured` link in place of its sidebar entry, and delete it (mdBook's `print.html` ran the same tag, so it sent the whole print page away too). Report it.
+- Delete `SUMMARY.md` once folders and `meta.ts` carry its structure: it would publish as a page.
+- **Check that git sees the new files.** A repo `.gitignore` can cover the content root (pages added before the rule stay tracked), and then every `meta.ts` and partial you create is silently left out of `git add`. Run `git check-ignore -v <content root>/meta.ts` after writing the first one; if it prints a rule, fix that rule or report that each new file needs `git add -f`.
+
+### Parts, order, labels, and folding
+
+- **Display:** set `navigation: { sidebar: { display: "group" } }`. Parent chapters become collapsible rows, like mdBook's tree, and a group keeps leaf chapters between its subgroups in `meta.ts` order (SKILL.md: `flat` can't interleave them).
+- **Part titles** → a folder per part, with `title: "<part title>"` and `display: "flat"` in its `meta.ts`: a heading, not a row. When a part's chapters already share a folder (`developers/`), that folder is the part; otherwise use a `(part)/` folder at the content root, which changes no URL. Chapters after a separator inside a part get the folder they're already in (`appendix/` reads "Appendix"), or the part's heading.
+- **Order** → a `meta.ts` `pages` array in each folder, every child in `SUMMARY.md` order. The root `meta.ts` orders the parts.
+- **Prefix chapters** stay loose pages at the content root, which Blume lists first, as mdBook did.
+- **What files can't express:** at the top of the sidebar, loose pages always list above folders. Suffix chapters, and leaf chapters between parent chapters in a book with no parts, rise above them. Put each in a `(group)/` folder (it adds a heading), or accept the order. When many chapters are affected, an explicit `navigation.sidebar` keeps `SUMMARY.md`'s order exactly: a route string per leaf chapter, `{ label, root: "<route>", items }` per parent chapter, `{ label, display: "flat", items }` per part. It replaces the generated tree, so it needs an entry per new page, as `SUMMARY.md` did. Report which you chose.
+- **Labels:** `title` is the body H1, what the page showed. `sidebar.label` is the `SUMMARY.md` text where it differs, what the sidebar and `<title>` showed. A page with no H1 takes the `SUMMARY.md` text as `title`. Give each parent chapter's folder `title: "<its SUMMARY.md text>"` in `meta.ts`, or its row shows the humanized folder name. Strip Markdown from `SUMMARY.md` text: backticks render literally in `title`.
+- A parent's `index` page also lists as its group's first row, so the label shows twice. To show it once, as mdBook did, set `sidebar.hidden: true` on the index: it stays in `sitemap.xml` and search because the group row still links to it. If its `title` differs from the folder's `meta.ts` title, set its `sidebar.label` to the folder title, or `BLUME_NAV_INDEX_TITLE_MISMATCH` fails `validate --strict`.
+- **`[output.html.fold]`:** with `enable = true`, sections below `level` started closed (0 closes all), which is `group` mode's default; add `collapsed: false` to the folders mdBook opened. Without folding, mdBook showed every section open: add `collapsed: false` to every folder's `meta.ts`.
+- **Drafts and separators** have no equivalent: drop them, and report the drafts as planned chapters.
+
+## Content
+
+### `.md` or `.mdx`
+
+Rename a page to `.mdx` when it ends up with a callout, mermaid, math, tabs, or another component. Those are MDX-only: in `.md` they don't render, and the build stays green (a `:::` callout only warns `BLUME_MD_DIRECTIVE`). Tables, footnotes, strikethrough, task lists, `[#id]` heading ids, `<include>`, `{{variables}}`, and raw HTML work in both (`{#id}` only in `.md`). Fix what fails `.mdx` in each renamed page: HTML comments → `{/* … */}` on one line, unclosed `<br>`/`<img>`, `<https://…>` autolinks, and `{`, `<` in prose (`Vec<T>` outside backticks).
+
+### Includes and the other `{{#…}}` helpers
+
+mdBook expands these as text before parsing, so they work inside fences, inline code, and link URLs, and across a line break (`{{#include` at a line's end, the path on the next, as Prettier wraps it). A path resolves from the including file.
+
+| mdBook | Blume |
+| --- | --- |
+| a fence holding only `{{#include path}}`, the whole file, inside the content root | the whole fence → `<include lang="rust">path</include>` on its own line (the fence's language; its attributes drop) |
+| a fence holding only `{{#include path:anchor}}`, `path:N`, `path:N:M`, `path:N:`, or `path::M`, or any target outside the content root | an excerpt (below), included the same way |
+| a fence mixing includes with hand-written lines | one excerpt that joins `{ "text": "…" }` parts and selections in order, so the block stays generated |
+| `{{#rustdoc_include path:sel}}` | an excerpt of `path:sel`: the selected lines only. The rest of the file sat behind mdBook's expand toggle, which has no equivalent (report) |
+| `{{#playground path attrs}}` | `<include lang="rust">` of the file (an excerpt when it's outside the root); no Run button (report) |
+| `{{#include x.md}}` on its own line | `<include>/_snippets/x.md</include>` (a leading `/` is the content root): a partial must sit under a `_` folder or name, or it publishes as a page. Images in a partial resolve from the partial's own folder (mdBook resolved them from the including chapter), so fix their paths |
+| a one-line file included inline (`{{#include ../VERSION}}` in a URL or a command) | `{{VERSION}}`, with `variables: { VERSION: readFileSync(new URL("../VERSION", import.meta.url), "utf8").trim() }` in `blume.config.ts` (`import { readFileSync } from "node:fs"`). Variables are replaced in links, code, and inline code too |
+| `{{#title X}}` | `seo.title: X` (Blume appends the site title, as for every page) |
+| `\{{#include x}}` (often in a fence that documents mdBook) | drop the backslash, which mdBook removed even inside code. `{{#include x}}` stays literal in code and in `.md`; in `.mdx` prose a `{` fails the build, so put it in inline code |
+
+**Excerpts.** `<include>` fails the build on a target outside the content root (`BLUME_INCLUDE_OUTSIDE_ROOT`) and can't select lines. Pasting each excerpt into its page would freeze code that cargo still compiles and tests, so generate them before every run with the bundled `include-excerpts.mjs`:
+
+1. Copy `<skill>/scripts/include-excerpts.mjs` beside `blume.config.ts`. Its header documents the manifest.
+2. Write `excerpts.json` there: `out` (`<content root>/_excerpts`, relative to the manifest; Blume doesn't publish a `_` folder), and one entry per excerpt, keyed by its file name under `out`. An include's argument works as written once its path is relative to the manifest's folder (`"counter/abi.rs": "../examples/counter/src/lib.rs:contract_abi"`): the script selects anchors and line ranges exactly as mdBook did. A mixed fence is an array: `[{ "text": "impl Contract for Token {" }, "../src/contract.rs:transfer", { "text": "}" }]`.
+3. Run `node include-excerpts.mjs`. It checks every entry first and lists **every** missing file, missing anchor, and line range past the end of its file in one pass, then writes nothing. A clean run writes the excerpts and deletes the ones it wrote earlier that the manifest dropped (never a file it didn't write).
+4. Replace each include with `<include lang="rust">/_excerpts/counter/abi.rs</include>`.
+5. Run it first in `package.json` (`"dev": "node include-excerpts.mjs && blume dev"`, and the same for `build` and a `validate` script), and gitignore `<content root>/_excerpts/`. A host's build command must be `npm run build`, not `blume build`. Rerun it after editing a source file: `blume dev` doesn't watch them.
+
+**Missing anchors.** For each anchor the script reports (the old site showed an empty block, or only a mixed block's hand-written lines), find where the code went (`git log -S "ANCHOR: <name>"`, or search the crate for the item), then:
+
+- **When the team owns the source, re-add the `// ANCHOR: <name>` and `// ANCHOR_END: <name>` comments around the code there.** The entry keeps working as written, and the excerpt follows the code as it changes.
+- Otherwise, point the entry at a line range (`"…/lib.rs:14:23"`). It keeps selecting those line numbers when the file changes, without an error, so say so in the report.
+- Drop the block, with its lead-in sentence, when the code is gone.
+
+Report each one and what you chose. Code that now fills a formerly empty block may contradict the prose around it: list what you notice.
+
+### Code blocks
+
+| mdBook | Blume |
+| --- | --- |
+| ` ```rust,ignore `, `rust,no_run,noplayground`, `rust,should_panic`, `rust,compile_fail`, `rust,edition2021`, `rust,editable`, `rust,mdbook-runnable`, `rust,hidelines=…` | ` ```rust ` (a comma-glued language doesn't highlight, and warns `BLUME_UNKNOWN_CODE_LANGUAGE`; written with a space, ` ```rust ignore `, the keyword does nothing and warns `BLUME_CODE_FENCE_OPTION`) |
+| ` ```ignore `, or no language: rustdoc tests an unlabeled block as Rust, so books label diagrams and shell lines `ignore` | ` ```text `, or the real language |
+| **hidden lines** in a Rust block: first non-space character `#`, then a space or the end of the line | delete the line, and a blank line it leaves at the top of the block: readers saw it only through the eye toggle, which has no equivalent. `##x` shows as `#x`; `#[derive]` and `#!` lines are code. Lines with a `[output.html.code.hidelines]` prefix (`python = "~"`), or a fence's `hidelines=<prefix>`, go the same way |
+| the play button, `editable` | static code (report) |
+| `mdbook test` | nothing compiles Blume's code blocks. Excerpts stay tested by cargo; hand-written blocks that `mdbook test` compiled aren't any more (report; drop the CI step and whatever it built only for that) |
+
+### Admonitions
+
+**mdbook-admonish** writes ` ```admonish <type> ` with options (`title="…"`, `collapsible=true`, `id`, `class`), the older `admonish <type> "Title"`, or `~~~`/four-backtick outer fences around inner code. Each becomes a callout in `.mdx`, with a longer `::::` outer fence around a nested one:
+
+| admonish type (aliases) | Blume |
+| --- | --- |
+| `note`, `example` | `:::note` |
+| `info` (`todo`), `abstract` (`summary`, `tldr`), `question` (`help`, `faq`) | `:::info` |
+| `tip` (`hint`, `important`) | `:::tip` |
+| `success` (`check`, `done`) | `:::success` |
+| `warning` (`caution`, `attention`) | `:::warning` |
+| `danger` (`error`), `failure` (`fail`, `missing`), `bug` | `:::danger` |
+| `quote` (`cite`) | a blockquote |
+| **any other word** (`admonish warn`) | `:::note`: admonish rendered it as a note titled "Note". Don't keep the word: Blume reads `:::warn` as a warning. Report it, with the type the author probably meant |
+
+- `title="T"` → `:::type[T]`; `title=""` → no title. An untitled block showed the word it was written with as its title bar (`Example`, `Hint`, `TL;DR`), and an untitled Blume callout shows none: where that word isn't the Blume type's name, keep it as the title (`:::note[Example]`).
+- `collapsible=true` → `<Expandable title="T">` (the type's name when untitled); its color drops.
+- Custom directives (`[[preprocessor.admonish.custom]]`) → the closest callout, with the label as title.
+- Each block had an anchor (`#admonition-<title>`, `-1` for repeats). Links to one fail `blume validate --strict`: point them at the nearest heading or drop the fragment.
+
+**GitHub alerts** (`> [!NOTE]`, built into 0.5 and the `alerts` plugin) render as callouts in `.mdx` as written: `NOTE` and `IMPORTANT` as a note, `TIP` a tip, `WARNING` a warning, `CAUTION` a danger callout. In `.md` they stay a blockquote with a literal `[!NOTE]` and warn `BLUME_MD_GITHUB_ALERT`: rename the page to `.mdx`. A 0.4 book without the plugin showed them as plain quotes: rendering them changes the page (report).
+
+### Other syntax
+
+| mdBook | Blume |
+| --- | --- |
+| `## Heading {#id}` | the same in `.md`; `[#id]` in `.mdx` |
+| `## Heading { #id .class }` | `{#id}` or `[#id]`; classes drop. Left as is, the spaced form stays in the heading text and makes a garbage id; `BLUME_MD_CURLY_ANCHOR` flags it only when no class follows the id (in `.mdx` it fails the build) |
+| footnotes, tables, strikethrough, task lists | unchanged |
+| definition lists (`term` then `: definition`, on by default in 0.5) | a list or table, or raw `<dl>`; Blume renders them as one paragraph |
+| MathJax (`mathjax-support`): `\\( … \\)`, `\\[ … \\]` | `$$…$$` inside the sentence, or on lines of its own for a block, in `.mdx`. Undo the Markdown escapes mdBook needed inside the math (`\\\\` for a LaTeX `\\`, any `\_` or `\*`): `$$` math is read verbatim |
+| `<i class="fa fa-x"></i>` | `<Icon icon="<lucide>" />` in `.mdx`, or delete (the icon map in `references/mintlify.md`) |
+| `class="left"`/`"right"` floats; `class="hidden"` | drop the class; delete hidden elements (report) |
+
+### Links and images
+
+- mdBook only rewrote `x.md` links to `x.html`. Blume resolves a relative `.md` link to the page that file publishes: keep them, and fix the ones into or out of every moved file.
+- Rewrite `.html` links (`installation.html#cargo`) to their `.md` files: Blume serves no `.html` URLs, so they'd depend on the redirects. `blume validate` reports each one left (`BLUME_BROKEN_ASSET`, with the page's route).
+- **A link to `README.md` was already dead:** mdBook wrote `README.html`, a page it never creates. Point it at the renamed `index.md`.
+- Root-relative links (`/guide/x.md`) land on the page that file publishes, read from the content root, like relative ones.
+- Images relative to the page work as written. So does a linked download (a PDF, an archive) that mdBook copied from `src/`: Blume publishes a file a relative link names with the page, at a new URL. Move it to `public/` at the same path only if its old URL is linked from elsewhere.
+
+## URLs and redirects
+
+| Source file | mdBook URL | Blume route |
+| --- | --- | --- |
+| `src/guide/setup.md` | `/guide/setup.html` | `/guide/setup` |
+| `src/guide/README.md` | `/guide/index.html` | `/guide` |
+| the first chapter, `src/intro.md` | `/intro.html` and `/index.html` | `/` once moved to `index.md` |
+| `src/01-basics.md` | `/01-basics.html` | `/basics`, or `slug: 01-basics` |
+
+- **One exact redirect per chapter that isn't an index**, `{ from: "/guide/setup.html", to: "/guide/setup" }`, built from `old-urls.txt` and your table: a pattern can't strip `.html`. Skip `/index.html` and `/x/index.html`: static hosts serve Blume's `x/index.html` there already.
+- **`[output.html.redirect]`**: each key is a path from the site root, and its value is a URL relative to the key's folder (`"../infra/x.html"`), root-relative, or external. Resolve the value against the key's folder, then map it like a chapter (`.html` → route, `index.html` → its folder); external URLs stay. Check each target against the old build: one that already led to a 404 → the page that replaced it, or drop it, and report.
+- **Fragment redirects** (`"/page.html#old" = "other.html#new"`, 0.4.52 and later): servers never see fragments. A heading renamed on the same page → pin the old id on it (`[#old]`); moved to another page → no server equivalent (report). A deleted page's own entry is its redirect.
+- **No equivalent, no redirect:** `print.html` (the whole book on one page, `noindex`), `toc.html` (the sidebar frame, `noindex`), and `404.html` (Blume writes its own). Mention `export: { pdf: true }` for printing.
+- **Hosts:** a static build writes each redirect as a meta-refresh page at `dist/<from>/index.html`, plus `_redirects` and `vercel.json`. On Netlify use `netlify({ output: "static" })` for real 301s (SKILL.md). GitHub Pages reads neither file and serves the meta-refresh page; how it answers `/x.html` there is unverified, so check a few old URLs after deploying.
+- **Heading anchors:** mdBook 0.5 ids match Blume's for most headings; 0.4 lowercases ASCII only (`## Über` → `#Über`), and both count the H1, so `# Install` then `## Install` gives `#install-1`. After the first build, run `node <skill>/scripts/pin-heading-ids.mjs --old old-book` (add `--map dist/blume-redirects.json` when routes changed, built with no host adapter; `--write` to apply), and rebuild until it reports 0.
+- **Check every old URL** after `blume build`. With no host adapter (static), from the Blume project:
+
+  ```bash
+  node -e '
+  const fs = require("node:fs");
+  const moved = new Map(JSON.parse(fs.readFileSync("dist/blume-redirects.json", "utf8")).map((r) => [r.from, r.to]));
+  const built = (to) => /^https?:/.test(to) || fs.existsSync(`dist${to.replace(/#.*/, "").replace(/\/$/, "")}/index.html`);
+  const misses = fs.readFileSync("old-urls.txt", "utf8").split("\n").filter(Boolean).filter((url) => {
+    const to = url.endsWith("/index.html") ? url.slice(0, -"index.html".length) : moved.get(url);
+    return !(to && built(to));
+  });
+  console.log(misses.length ? misses.join("\n") : "every old URL resolves");'
+  ```
+
+  Then run `blume audit --only redirects`.
+
+## Repo integration and teardown
+
+- **`package.json`** beside `blume.config.ts`: `blume` plus the `dev`/`build`/`preview`/`validate` scripts, with the excerpt step first. Commit the lockfile (SKILL.md step 6).
+- **`.gitignore`:** replace `book/` with `dist/`, `.blume/`, `node_modules/`, `.env.local`, and `<content root>/_excerpts/`.
+- **CI:** replace `mdbook build`/`mdbook test`, `peaceiris/actions-mdbook`, and the plugin installs with Node 22, an install, `npm run build`, and `npm run validate`. A deploy workflow in another repo needs the same change: list it as a follow-up. For GitHub Pages, follow https://useblume.dev/guides/markdown-docs-github-pages (Actions as the Pages source), with `npm run validate` and `npm run build` in place of its `blume` steps so the excerpts exist, run from the Blume project's folder, and that folder's `dist` uploaded. A deploy that pushes a branch must publish `.nojekyll`, or Jekyll drops Blume's `_astro/` folder; `peaceiris/actions-gh-pages` adds it by default.
+- **`cargo doc` output published beside the book** (`/api/…`): keep building it in CI and copy `target/doc` into the build output, or link to docs.rs. Blume doesn't generate it.
+- **Several builds of the book** (a stable tag and `main`, `MDBOOK_BOOK__LANGUAGE` per language): migrate the current one; older versions → `versions`, or stay on the old host (report). Translations in `po/*.po` (mdbook-i18n-helpers) apply at build time: render each language's Markdown with `MDBOOK_BOOK__LANGUAGE=<xx>` and the Markdown renderer into `<xx>/`, then set `i18n`. Report it.
+- **Prettier** on the book: extend its `*.md` overrides to `*.mdx`, and keep `{/* */}` comments on one line. Prettier 3 skips what `.gitignore` ignores, so a `.gitignore` that covers the content root also makes a `prettier --check` CI step check nothing.
+- **A hand-written `llms.txt` in `src/`:** Blume generates `/llms.txt`, so delete the file. Its intro goes to `agents.llmsTxt.details`. A per-page summary becomes that page's `description` only where it reads well as the page's lede, since Blume shows `description` under the title; report the rest, and the sections that list things other than pages.
+- **Delete** `book.toml`, `SUMMARY.md`, `theme/`, the `additional-css`/`additional-js` files once ported, `mdbook-admonish.css`, `mermaid.min.js`, `mermaid-init.js`, and the `book/` folder. Grep the repo for `mdbook`, `book/`, and the old `.html` URLs (READMEs, CONTRIBUTING, examples, bots).
+
+## Dropped — report these
+
+Section numbers, separators, and draft chapters; suffix chapters and leaf chapters that moved above folders; the print page; the theme switcher and themes beyond one light and one dark; search options; the play button, the editor, and runnable or editable examples; hidden lines and their toggle; `mdbook test` coverage of hand-written blocks; `rustdoc_include` context; admonish title bars, colors, icons, custom directives, and anchors; fragment redirects across pages; the old site's empty blocks from missing anchors, and what you did with each; definition-list styling; Font Awesome icons with no Lucide match; `class="hidden"` content; plugin output you froze (cmdrun, templates, custom preprocessors); a hand-written `llms.txt`; whole-book PDF or EPUB output; and every plugin you removed without an equivalent.