blume 2.1.3 → 2.2.1

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

@@ -0,0 +1,267 @@
+# GitBook → Blume
+
+GitBook is a hosted editor. This reference covers the Markdown it writes when a space syncs to GitHub or GitLab (Git Sync): `SUMMARY.md` (a space's navigation), `.gitbook.yaml` (where its files live, plus redirects), and, on site-wide Git Sync, `gitbook-docs.yaml` (which space maps to which directory). Theme, logo, header and footer links, custom domain, site redirects, and access control live in the GitBook app, not the repo. Two things set this migration apart:
+
+- **URLs follow `SUMMARY.md`, not the file tree.** Moving a page in the editor changes its URL but not its file. Blume derives route _and_ sidebar from the file path, so the core move is putting each file at its old URL.
+- **Blocks are Liquid-style tags (`{% hint %}`) and raw HTML inside `.md`.** Almost every page becomes `.mdx`, and MDX rejects several things GitBook writes.
+
+## Detect
+
+- **`.gitbook.yaml`** or **`.gitbook.yml`** (GitBook reads both) at the root or in a space directory; **`gitbook-docs.yaml`** for site-wide Git Sync.
+- A **`SUMMARY.md`** (GitBook writes it opening `# Table of contents`; a hand-written one may open `# Summary`), with `* [Title](path.md)` items and `## Group` headings, beside a **`.gitbook/`** folder (`assets/`, `includes/`, maybe `vars.yaml`). `.gitbook.yaml` is optional, so this pair can be the only sign.
+- Pages that open with a `# Title` line and use `{% hint %}`, `{% tabs %}`, `{% content-ref %}`; sync commits titled `GITBOOK-<n>: …`.
+- **Not this format:** `book.toml` + `src/SUMMARY.md` is mdBook. `book.json` + `SUMMARY.md` is the legacy GitBook CLI or HonKit — see [Legacy GitBook CLI](#legacy-gitbook-cli-bookjson).
+
+## First, collect what the repo doesn't hold
+
+Do this while the GitBook site is still published. Nothing moves before step 1.
+
+1. **Old URLs.** `<site>/sitemap.xml` indexes one `sitemap-pages.xml` per published space (`/sitemap-pages.xml`, `/de/sitemap-pages.xml`, …); fetch them all. They list every canonical page, hidden and generated OpenAPI pages included, but not `noIndex`/`noRobotsIndex` pages (take those from `SUMMARY.md`). `<site>/llms.txt` lists the same pages with their `.md` URLs. Save the paths, one per line, outside the content root.
+2. **Site redirects** (Settings → Redirects). The app has no export: `GET https://api.gitbook.com/v1/orgs/{organizationId}/sites/{siteId}/redirects?limit=1000` with a token (paginated: while the response has `next.page`, fetch again with `&page=<it>`), or ask the user. With neither, report it as a follow-up.
+3. **Site customization.** `GET https://api.gitbook.com/v1/orgs/{organizationId}/sites/{siteId}/customization` with a token. Without one, read the published HTML: logo and favicon URLs go through `~gitbook/image?url=<original>` (decode `url` and download it), the header carries a light logo (`class="block dark:hidden …"`) and, when one is set, a dark one (`hidden dark:block`), and the inline CSS declares the primary color as an RGB triplet, `--primary-original`.
+4. **Spaces not in the repo.** Compare the sitemap index with the repo's directories. A space with `content.directory: null`, or a language or version the site serves but the repo lacks (often GitBook-made translations), has no Markdown here. Ask: export it (Git Sync that space into a branch, or `POST https://api.gitbook.com/v1/spaces/{spaceId}/git/export`) and migrate it; regenerate it with `blume translate` once `i18n` is set; or drop it and redirect its URLs (see URLs and redirects). Report the choice.
+
+## Config
+
+Map what step 3 found or the user supplies; leave the rest at Blume's defaults.
+
+| GitBook | Blume |
+| --- | --- |
+| Site title (`gitbook-docs.yaml` `site.title`) | `title` |
+| Logo (light and dark) | `logo: { image: { light, dark } }`, files in `public/` (SKILL.md covers monochrome SVGs and wordmarks) |
+| Icon (favicon) | `public/icon.svg` or `icon.png` (a dark one → `icon-dark.*`); no config field. An emoji icon has no file: make one or report it |
+| Primary color | `theme.accent` |
+| Default mode, fonts, code theme | `theme.mode`, `theme.fonts.{body,display,mono}`, `markdown.code.theme` (nearest Shiki themes) |
+| Theme style, tint and semantic colors, corner, depth, link, and sidebar styles | drop (report); a root `theme.css` if one matters |
+| Header links; a button-styled one | `navigation.actions`; `navigation.cta` |
+| Announcement | `banner` (`{ content, link, dismissible, id }`) |
+| Footer | `footer.links`, flattened into one row; copyright → `footer.copyright`; group titles and logo drop (report) |
+| Social accounts | `footer.socials` |
+| Social preview image | `seo.image` on the landing page (Blume renders a card for every other page) |
+| Git Sync repository and branch | `github: { owner, repo, branch }`, plus `dir` or `host` when needed; GitLab has no equivalent (report) |
+| Page actions: Markdown and AI providers, MCP, PDF | defaults; `agents.mcp.enabled` plus server output (follow-up); `export` |
+| GitBook Assistant | `ai.assistant` plus server output (follow-up), or drop |
+| Integrations | adapters in `analytics` from `blume/analytics`; others `script()` or report |
+| Custom domain | the DNS record moves to the new host; keep the URL as `deployment.site` unless the host is Vercel or Netlify |
+| Custom subdirectory (`example.com/docs`) | `deployment: { base: "/docs" }` |
+| Share links, authenticated access | host-level protection (the deployment docs' **Private docs**); report |
+| `.gitbook/vars.yaml` | `variables` (see Variables) |
+
+**Content root.** `root: ./docs/` is Blume's default `content.root`. With `root: ./`, `git mv` the space (pages, `SUMMARY.md`, `.gitbook/`) into `docs/` — routes are relative to the content root, so they don't change — or scope `content.include` (`references/monorepo.md` §1). Left unscoped, the repo's `README.md` and every stray `.md` publish.
+
+## Navigation: `SUMMARY.md` → folders
+
+### How GitBook builds a URL
+
+- The first `SUMMARY.md` item (`structure.readme`, `README.md` by default) is served at the space root; its own slug (`/readme`) redirects there.
+- Every other page: the space's prefix (see Site structure), then its `## Group`'s slug, each ancestor page's slug, and its own. A page's slug comes from its file name at import (a `README.md` → its folder's name), lowercased; a group's, from its heading (emoji dropped) or the `id` of an `<a id="…">` inside it.
+- **The file's own path doesn't count.** A page filed at `configuration/post-install.md` but listed under group "Deployment" → parent `deployment/permissions/README.md` publishes at `/deployment/permissions/post-install`.
+
+Compute every page's URL from `SUMMARY.md`, then check them against the sitemap list; the sitemap wins.
+
+### Put every file at its old URL
+
+One `git mv` per page keeps both the route and the sidebar:
+
+- A page with no children → `<url>.mdx`; with children → `<url>/index.mdx`; the landing page → `index.mdx` at the content root (`.md` for a page that stays plain). Lowercase every segment: Blume keeps a file name's case, so `OCR.md` would publish at `/OCR` where GitBook served `/ocr`.
+- **`README.md` isn't an index in Blume** (`guides/README.md` publishes at `/guides/README`): every README becomes `index`.
+- Each `## Group` becomes a top-level folder named for its slug.
+- Keep a table of old file → new file → route: links, includes, and image paths are rewritten from it.
+- A file not in `SUMMARY.md` was never published. Delete it, or prefix it with `_` to keep it unpublished, and report it.
+- Delete `SUMMARY.md` once the folders and `meta.ts` files carry its structure; it would publish as a page.
+
+### Order, labels, and display → `meta.ts`
+
+- **Order.** Each folder's `meta.ts` lists its children in `SUMMARY.md` order (`pages`); the content root's lists the loose pages, then the group folders.
+- **Labels.** A page's title is its `SUMMARY.md` link text, and a link title (`[Title](page.md "Label")`) → `sidebar.label`. A group folder's `meta.ts` `title` is the heading text, and **a parent page's folder gets `title: <its SUMMARY text>` too** — otherwise the row shows the humanized folder name (`deployment-guides` → "Deployment Guides" for a page titled "Getting started").
+- **Display.** GitBook shows groups as plain headings and each parent page as one expandable row. Set `navigation: { sidebar: { display: "group" } }`, `display: "flat"` in each group folder's `meta.ts`, and `sidebar: { hidden: true }` on each parent's `index`: the folder row already links to it, so without this the parent lists twice.
+- **Contents pages.** A parent whose body is empty or only content-refs to its own children → delete those and set `directory: "card"` in the folder's `meta.ts`. It inherits: set `directory: "none"` on a nested folder that isn't a contents page.
+- **Order Blume can't match.** Loose top-level pages always list above groups and folders. A parent page among loose pages (Overview, Editions ▸, Use Cases) drops below them, and pages after a `***` divider in `SUMMARY.md` (top-level again: `/uninstall`, not `/other/uninstall`) rise above the groups. Move such pages into a parenthesized group folder (`(more)/`, which adds no URL segment) ordered in the root `meta.ts`, or accept the order; report either.
+- **External links** (`* [Website](https://…)`) → `navigation.featured` or `navigation.actions`; report the move.
+- **Hidden pages.** GitBook's `hidden: true` hides a page's whole subtree; Blume's hides one page, so set it on the index and every descendant (a folder whose pages are all hidden leaves the sidebar).
+- A list item that is a YAML block with `type: builtin:openapi` is a generated API reference (see OpenAPI).
+
+### Site structure: `gitbook-docs.yaml`
+
+`site.structure` nests `section-group`, `section`, `space`, and `external-link` entries. Every entry has a `key` (meaningless to Blume), a `title`, and maybe `localizedTitle`; most can carry `draft` or `condition`. Sections and spaces have a `path` and maybe `default: true` (a section group has no `path`); section groups, sections, and external links can have an `icon`; a space can be `hidden` and has `content.directory` (`null` when not synced) and maybe `content.language`. Skip `draft` entries, and treat a `condition` like adaptive content (report it).
+
+- **URL prefixes.** The default section's default space is at the site root. Another space → `/<section>/<space>`; a non-default section's default space → `/<section>`. A site without sections serves its default space at the root and the rest at `/<space>`.
+- **Sections** → a top-level folder each plus a `navigation.tabs` entry (`icon` → Lucide). The default section stays at the content root; add `{ label, path: "/" }` to show it as a tab.
+- **Section groups** → a dropdown tab scopes the sidebar by one `path`, so give each section its own tab (the grouping is lost; report) or move them under one prefix (URLs change; pattern redirects).
+- **Spaces within a section:** languages → `i18n` (Blume puts the locale first, site-wide: `/payments/fr/x` → `/fr/payments/x`); versions → `versions` (top-level `/<id>/…`, ids start with a letter); products → a folder each and a `navigation.selectors` dropdown. Redirect the old prefixes.
+- A space's directory can sit inside another's (`./home/fr` in `./home`): separate them, then do the `SUMMARY.md` work per space. A `hidden: true` space is still published but left out of the space switcher: keep its pages, leave it out of `navigation.selectors`, and report it. `localizedTitle` → a per-locale tab label.
+- **External links** (`external-link`, at the root or in a section group) → `navigation.actions` entries (`{ label, href }`; `localizedTitle` → a per-locale `label`, the `icon` drops).
+
+## Content and components
+
+### `.md` or `.mdx`
+
+Rename to `.mdx` every page with a `{% … %}` block, `$$` math, a mermaid fence, or a component after conversion. Directives, components, math, mermaid, `package-install`, and `ts2js` are MDX-only: in `.md`, a leftover `{% hint %}` or `:::note` is literal text with a green build (each `{% … %}` tag warns `BLUME_TEMPLATE_TAG` at its line, a `:::note` `BLUME_MD_DIRECTIVE`), and in `.mdx` a leftover `{% … %}` fails it (`BLUME_MDX_SYNTAX`, which `blume validate` and `blume check` report too). Plain pages can stay `.md`; tables, footnotes, fence meta, `<include>`, `{{variables}}`, `[#id]`, and raw HTML work in both. An include is spliced as text, so it's parsed in the including page's format.
+
+### MDX hazards
+
+Each of these fails `blume build` in `.mdx` (`blume check` and `validate` name the ones MDX can't parse as `BLUME_MDX_SYNTAX`, at their line):
+
+- **Unclosed `<img …>` and `<br>`** (`BLUME_MDX_UNCLOSED_ELEMENT` names each). Close them — better, convert images to Markdown.
+- **HTML comments** → `{/* */}`.
+- **A `{` outside code.** GitBook's `\{{x\}}` isn't enough; write `` `{{x}}` `` or `\{\{x\}\}`. Braces inside raw HTML (`<code>CN={{DeviceId}}</code>`, `<td>${EMAIL}</td>`) compile, then fail the render: `blume build` names each as `BLUME_MDX_UNDEFINED_NAME` at its line. Turn `<code>`, `<strong>`, `<a>`, `<p>`, and `<br>` inside table cells into Markdown.
+- **Markdown inside JSX** (`<Tab>`, `<Step>`, `<Frame>`) needs blank lines around it.
+
+GitBook's `\<` and entities (`&#x20;`, `&#x3C;`) are fine (an escaped `\<Name` can still warn `BLUME_UNKNOWN_COMPONENT`; the page renders correctly). Strip the U+200B/U+200C characters GitBook leaves at the start of some code lines.
+
+### Blocks
+
+| GitBook | Blume |
+| --- | --- |
+| `# Title` (the first line) | frontmatter `title`; delete the line |
+| `{% hint style="info" %}` (`success`, `warning`, `danger`) | `:::info` (`:::success`, `:::warning`, `:::danger`); legacy plugin `tip` → `:::tip`, `working` → `:::note`. A directive takes no `icon`: keep one that matters as `<Callout type="<type>" icon="<lucide>">`, else drop it; inside another directive, give the outer one a longer fence (`::::`) |
+| `{% tabs %}` + `{% tab title="X" icon="y" %}` | `<Tabs>` + `<Tab title="X" icon="<lucide>">`; `fullWidth` drops. Blume switches same-titled tabs together page-wide (`sync={false}` opts a group out) |
+| `{% code title="a.js" lineNumbers="true" overflow="wrap" expandable="true" %}` | fence meta: ` ```js title="a.js" lineNumbers wrap expandable `; `fullWidth` drops. **A fence with no language takes `text`** (` ```text lineNumbers `), or the first option becomes the language (`BLUME_UNKNOWN_CODE_LANGUAGE`) |
+| `<pre class="language-x" data-title="…" data-line-numbers data-overflow="wrap"><code>` | a fence built from those attributes (others drop), entities decoded, `<strong>`/`<em>` stripped |
+| `{% stepper %}` + `{% step %}` | `<Steps>` + `<Step>`. **A step that opens with a heading keeps it as the first line inside `<Step>`**: GitBook publishes it as an anchored heading in the outline, and `title` renders a plain paragraph with no anchor. A bold-line opener → `title` |
+| `{% columns %}` + `{% column %}` | `<Columns cols={n}>` + `<Column>`; widths drop |
+| `<details><summary>T</summary>` (`open`) | `<Expandable title="T">` (`defaultOpen`); a run → `<Accordion>` + `<AccordionItem title="T">`. A title renders inline Markdown, so write a summary's `<code>`, `<strong>`, and `<a>` as Markdown in it: raw HTML there shows as text |
+| `{% content-ref url="x.md" %}`; legacy `{% page-ref page="x.md" %}` | `<Card title="<x's title>" href="<x's route>" />` (the link text is a file name, so look the title up); a run → `<CardGroup>`; links to a parent's own children → `directory: "card"` |
+| `[text](x.md#h "mention")` | a plain link without `"mention"`, its text replaced by the target's title |
+| `{% embed url="…" %}`, often with no `{% endembed %}` | YouTube → `<YouTube url="…" />` (`?t=122` → `start={122}`; `url` ignores `t`); anything else → `<Card title="…" href="…" />`. A caption → `<Frame caption="…">` around it (YouTube's `title` only reaches screen readers) |
+| `{% file src="…" %}caption{% endfile %}` | `[caption](../assets/x.pdf)`, relative to the page: Blume publishes a file a relative link names with the page. For a URL that never changes, put the file in `public/files/` and link `/files/x.pdf` |
+| `<figure><img src alt><figcaption>` | `![alt](relative/path.png)` (optimized); a caption → `<Frame caption="…">` around it; `<div data-with-frame="true">` → `<Frame>`. A raw `<img>` with a relative `src` works too, but unoptimized |
+| `<img class="gitbook-drawing">` | a Markdown image |
+| inline `<img data-size="line">` | a Markdown image (renders at its own size), or `<img src="/<public path>" alt="" height="20" />` to stay text-height (report) |
+| `<picture>` with a dark-mode source | the light image (report) |
+| `<table data-view="cards">` | `<CardGroup cols={3}>` (`data-card-size="large"` → `cols={2}`), a `<Card>` per row: first text cell → `title`, other text → body, the `data-card-target` link → `href`, the `data-card-cover` file → `img`, relative to the page like a Markdown image (`img="../assets/cover.png"`), an `<i class="fa-…">` cell → `icon` |
+| other `<table>` (`data-header-hidden`, `data-search`, cells with `<p>`/`<br>`) | a GFM table (a hidden header's first row becomes the header); a cell's `<ul><li>` can stay inline in `.mdx` |
+| `$$…$$`, a ` ```mermaid ` fence | unchanged, in `.mdx` |
+| Emoji: `:rocket:`, escaped `:ballot\_box\_with\_check:`, `<span data-gb-custom-inline data-tag="emoji">☑️</span>` | the character itself: Blume renders no shortcodes |
+| `<i class="fa-x">:x:</i>` | `<Icon icon="<lucide>" />`, or delete it |
+| `<a class="button primary">`, `<button data-action="…">` | a link or a `<Card>` with `cta`; search and ask buttons drop |
+| `<mark style="color:…">` | `<mark>` or bold; report colors that carried meaning |
+| `## Heading <a href="#x" id="x"></a>` | works as written: the heading takes `x` as its id. `## Heading [#x]` is the tidier spelling |
+| `[^1]` annotations | unchanged: footnotes at the page's end, not hover popups |
+| `{% updates %}` + `{% update date="…" %}` | `type: changelog` pages (SKILL.md "Changelogs"), or dated `##` sections |
+| `{% prompt description="…" %}` | `<Prompt description="…">` |
+| `{% if visitor… %}` | keep what the public saw, drop the tags (report) |
+
+### Links
+
+- Every moved file breaks the relative links into and out of it. Rewrite internal links from your table as root-absolute routes (`/deployment/permissions#roles`): Markdown links, content-ref URLs, card `href`s, and `href`s in HTML. A `README.md` target → its folder's route; absolute links to the old domain → routes.
+- Cross-space links `https://app.gitbook.com/s/<spaceId>/<path>` (or `…/o/<orgId>/s/…`) → the target space's prefix plus `<path>`; `GET https://api.gitbook.com/v1/spaces/{spaceId}` gives its `urls.published`. Links into `…/~/changes/…` or to `/broken/pages/<id>` were already broken: fix or report them.
+
+### Images and assets
+
+- Move `.gitbook/assets/` to `assets/` at the space root and replace the string `.gitbook/assets/` with `assets/`, then recompute the paths in every moved page.
+- File names have spaces and parentheses. `![](<../assets/image (1).png>)` and `../assets/image%20(1).png` both work, in a page and in an `_includes/` partial alike: a partial's images are rebased onto the including page in any form.
+- GitBook keeps every upload, so many files in `assets/` may be referenced by nothing. Report them and offer to prune.
+
+### Variables and expressions
+
+- `.gitbook/vars.yaml` → `variables`; `<code class="expression">space.vars.NAME</code>` → `{{NAME}}`.
+- `page.vars.NAME` (from `vars:` frontmatter) has no page scope: write the value inline. Read inside an include, it becomes a prop: `<include name="Computer">/_includes/x.md</include>` with `{{name}}` in the partial (prop names are lowercase).
+- An expression with logic (`a ? "x" : "y"`) → evaluate it and write the result.
+- Once `variables` is set, an undefined `{{name}}` in prose fails the build: placeholders that are content (`{{DeviceId}}`) go in inline code.
+
+### Includes (reusable content)
+
+- `.gitbook/includes/x.md` → `_includes/x.md` at the content root, and `{% include "../../.gitbook/includes/x.md" %}` → `<include>/_includes/x.md</include>` on its own line (a leading `/` resolves from the content root).
+- **Demote every heading in an include one level:** GitBook renders an include's `#` at a page's `##`.
+- Delete includes nothing references. One referenced by ID (`{% include "/reusable-content/…" %}`) isn't in the repo: copy it from the app.
+
+### OpenAPI
+
+GitBook has five forms: a `SUMMARY.md` YAML item `type: builtin:openapi` naming an organization spec (`dependencies.spec.ref.spec: <slug>`); `{% openapi src="…" path method %}`; `{% openapi-operation spec="<slug>" path method %}` and `{% openapi-schemas %}`; the older `{% swagger src="…" path method %}`; and hand-written `{% swagger method path baseUrl %}` blocks with `swagger-parameter` and `swagger-response` (oldest: `{% api-method %}`).
+
+- **Specs.** Vendor each one into the repo — a `<slug>`'s file comes from the app's OpenAPI panel or `GET https://api.gitbook.com/v1/orgs/{organizationId}/openapi/{specSlug}/versions/latest/content/raw` — and add `openapi({ spec })` from `blume/reference` with a `navigation.tabs` entry (SKILL.md "OpenAPI").
+- **`builtin:openapi`** → set `route` to the old reference's path and keep its parent page's prose under it. Operation URLs change, so redirect each old one in the sitemap (SKILL.md "OpenAPI" covers generating them).
+- **Inline operations** → a link or `<Card>` to the generated page. `{% openapi-schemas %}` has no counterpart (report).
+- **Hand-written blocks** → a `<ParamField query|path|header|body="…">` per parameter (a `cookie` has no slot), the responses as titled fences in `<ResponseExample>`, and `api: "GET /path"` frontmatter when it's the page's only endpoint (`baseUrl` → `api.server`).
+- `x-codeSamples` carries over; GitBook's other `x-*` extensions are ignored (report).
+
+## Frontmatter
+
+| GitBook | Blume |
+| --- | --- |
+| `# Title` / `SUMMARY.md` link text | `title`; where they differ, GitBook published the `SUMMARY.md` text |
+| `SUMMARY.md` link title | `sidebar.label` |
+| `description` (often folded `>-`) | `description` (quote a plain value containing `: `) |
+| `icon` (Font Awesome) | `icon`, in Lucide (see Icons) |
+| `hidden: true` | `hidden: true`, on the page and every descendant |
+| `noIndex: true` | `search.exclude: true` + `noindex: true`, on the page and every descendant |
+| `noRobotsIndex: true` | `noindex: true`, on the page and every descendant |
+| `cover`, `coverY`, `coverHeight`, `tags`, `if` | drop (report); a cover worth keeping → an image at the top of the body |
+| `vars` | inline the values, then drop |
+| keys left by older tooling (`category`, `order`) | drop: GitBook ignored them |
+
+`layout`:
+
+| GitBook `layout` | Blume |
+| --- | --- |
+| every part visible, `width: default` | delete the block |
+| `tableOfContents.visible: false` | `mode: center`; with `title.visible: false` too, `mode: custom` |
+| `outline.visible: false`, or `width: wide` | `mode: wide` |
+| `title.visible: false`, sidebar shown | `mode: frame` |
+| `pagination.visible: false` | `pagination: false` |
+| other parts hidden; a preset (`layout: landing`) | drop (report); for a preset, match the published page |
+
+A Blume mode hides more than one part: `center` and `wide` also hide the outline, and `frame` hides it and the page-end links and footer. Report it where GitBook kept those.
+
+Blume's frontmatter is strict: remove every key the tables drop.
+
+## Icons
+
+GitBook uses Font Awesome names in frontmatter `icon`, `<i class="fa-…">`, tab, hint, and button icons, and section icons. Blume is Lucide-only.
+
+- **Frontmatter:** `node <skill>/scripts/mintlify-codemod.mjs <content-dir>`, then `--write`. Its icon pass is the same Font Awesome → Lucide map, and GitBook frontmatter has none of the keys its other rules touch.
+- **Everything else by hand,** with the table in `references/mintlify.md`. Common GitBook names: `circle-info` → `info`, `clock-rotate-left` → `history`, `sliders` → `sliders-horizontal`, `handshake-angle` → `handshake`, `angles-up` → `chevrons-up`, `puzzle-piece` → `puzzle`, `life-ring` → `life-buoy`, `shield-halved` → `shield`, `file-contract` → `file-text`.
+- **Check every name** against the set Blume bundles; an unknown name renders nothing:
+
+  ```bash
+  node -e 'const b=require.resolve("blume/package.json");const s=require(require.resolve("@iconify-json/lucide/icons.json",{paths:[b]}));for(const n of process.argv.slice(1))console.log(n,!!(s.icons[n]||s.aliases?.[n]))' zap history sliders-horizontal
+  ```
+
+## URLs and redirects
+
+With every file at its old URL, pages need no redirects. The rest are below. GitBook answers all of them with a 307, except a permanent site redirect (308). Blume's default `status` is 301: keep it for a settled move (`.gitbook.yaml` redirects, recovered automatic redirects), and set `status: 307` where the target may change (group paths, dropped translations).
+
+- **`.gitbook.yaml` `redirects`** (`old/path: new/file.md`, relative to the space) → `{ from: "/<space prefix>/old/path", to: "<new/file.md's route>" }`.
+- **Site redirects** (`source`, `destination`, `permanent`, `captureWildcard`, `draft`) → `{ from: source, to, status: permanent ? 308 : 307 }`. `destination` is an object, not a URL: `kind: "external"` carries `url`; `site-page` (`siteSpaceId`, `pageId`), `site-space`, and `site-section` name ids. Resolve those to the old URL — `GET …/sites/{siteId}/site-spaces` gives each site space's `urls.published` and `space.id`, `…/sites/{siteId}/sections` each section's `urls.published`, and `GET /v1/spaces/{spaceId}/content` each page's `path` within its space — then to the Blume route at that URL. A trailing `*` with `captureWildcard` → `{ from: "/old/:path*", to: "/new/:path*" }`; without it, every match goes to the one `to`. Skip drafts (the list leaves them out by default), and write `from` without the site base.
+- **Automatic redirects.** GitBook quietly 307s every former URL of a moved or renamed page, and lists them nowhere. Recover them: run every historical `SUMMARY.md` (`git log --format=%h -- SUMMARY.md`, then `git show <sha>:SUMMARY.md`) through the URL rule above, add the route each file's path implies, and request each candidate from the live site (`curl -s -o /dev/null -w '%{http_code} %{redirect_url}'`). Each 307 to a page you kept becomes a redirect.
+- **Group paths and the landing slug.** GitBook redirects a group's own path to its first page, and `/readme` to `/`. Add both (`status: 307` for the group paths).
+- **Dropped translations.** GitBook translates group slugs (`/de/zahlungen/…` for group "Payments"), so `/de/:path*` → `/:path*` sends most translated URLs to 404s. Diff each language's `sitemap-pages.xml` against the default one, add a pattern per translated group (`{ from: "/de/zahlungen/:path*", to: "/payments/:path*", status: 307 }`), then each language's catch-all last: patterns are tried in order.
+- **Case.** GitBook matched URLs case-insensitively; Blume doesn't. Lowercased files cover the canonical URLs; report mixed-case inbound links.
+- **Markdown URLs.** GitBook serves `<url>.md`, and so does Blume; redirects move the `.md` URL with its page.
+- Rewrite internal links **before** adding redirects: `blume validate` accepts a redirect's `from` as a link target.
+
+### Heading anchors
+
+GitBook makes heading ids its own way: colons, slashes, and a spaced dash become one hyphen each, dots stay, an id that would start with a digit gets `id-`, and ids stop at 100 characters (`AppConfig:OCSP:UseAuthorizedResponder` → `appconfig-ocsp-useauthorizedresponder`, where Blume writes `appconfigocspuseauthorizedresponder`). Every `#anchor` link GitBook wrote to such a heading fails `blume validate`, and links from other sites land at the top of the page. A rule predicted only 890 of 934 ids on a real site, so read them instead. After `blume build`, from the project:
+
+```bash
+node <skill>/scripts/pin-heading-ids.mjs --old https://docs.example.com          # report
+node <skill>/scripts/pin-heading-ids.mjs --old https://docs.example.com --write  # pin
+```
+
+It fetches each old page once (one request at a time, cached in `.pin-heading-ids-cache/`; delete it after), pairs its headings with the build's by text, and appends the old id to each differing source heading — `[#id]` in `.mdx`, `{#id}` in `.md`, `\{#id\}` in a partial. Rebuild and rerun until it reports 0. A `NOTE … no source line` is a heading the source doesn't spell out (a component renders it, or it was reworded): pin it by hand. `--only-linked` pins only ids that content links to. A page whose URL changed (a space under a new prefix) is looked up on the old site through `--map`, a JSON list of exact `{ from, to }` entries (patterns are skipped): `dist/blume-redirects.json` works as it is, but a build writes it only when no host adapter is set. Any `BLUME_BROKEN_ANCHOR` left after that was already dead on GitBook: retarget the obvious ones, drop the fragment from the rest, and report them.
+
+### Final check
+
+Request each old URL from `blume dev` or `blume preview` (both apply pattern redirects) with `curl -sL`, or check it against `dist/` and `dist/blume-redirects.json` (written only when no host adapter is set), then run `blume audit --only redirects` after the build.
+
+## Legacy GitBook CLI (`book.json`)
+
+The old `gitbook-cli` toolchain and its fork HonKit:
+
+- **`book.json`:** `root`, `structure`, `title`, `description`, `variables`, `plugins`. Map `title` and `description`; `root` → `content.root`; plugins → whatever Blume has built in, else report.
+- **URLs are file paths:** `a/b.md` → `/a/b.html`, a `README.md` → its folder's `index.html`. Keep the files where they are, rename READMEs to `index`, and add an exact redirect from each `.html` URL (a pattern can't strip the extension).
+- **`SUMMARY.md`** nests the same way, but `### Part` headings and `---` lines add no URL segment → `(part)/` group folders. Entries pointing at anchors (`page.md#x`) aren't pages.
+- **Still applies:** `{% hint %}` → directives; `{% include "./x.md" %}` → `<include>`; `{{ book.name }}` → `variables` and `{{name}}`; other Nunjucks logic → evaluate and inline; `LANGS.md` → `i18n`, with the default language at the content root; `GLOSSARY.md` → no equivalent (report).
+
+## Teardown
+
+- **Turn off Git Sync** for every mapped space before the converted content reaches the synced branch: GitBook imports each push to it and commits its own edits back. Keep the GitBook site published until the domain moves.
+- Delete `SUMMARY.md`, `.gitbook.yaml`/`.gitbook.yml`, `gitbook-docs.yaml`, and the emptied `.gitbook/`.
+- Check CI and scripts that read `.md` files or `.gitbook/assets/`: a Markdown link checker breaks on root-absolute routes and skips `.mdx` (replace it with `blume validate --strict`), and an image de-duplication script that greps `*.md` would now delete images in use. Remove GitBook agent instructions (an `AGENTS.md` block, a vendored GitBook skill).
+- A synced repo usually has no `package.json`: scaffold one (SKILL.md step 6).
+
+## Dropped — report these
+
+Site themes and styles beyond accent, fonts, and mode; footer group titles and logo; page covers; page and update tags; adaptive content and visitor authentication; GitBook Assistant unless the user adds `ai.assistant`; hint icons you didn't keep; button styles and search/ask buttons; `<mark>` colors; `fullWidth` and column widths; non-YouTube embeds as players; dark card covers and theme-aware images; inline image sizing; `{% openapi-schemas %}` and GitBook `x-*` spec extensions; automatic redirects you couldn't recover; case-insensitive URLs; page-group icons; sidebar positions Blume can't match (parent pages among loose pages, `***` dividers, external links); section groups flattened into tabs; spaces and translations not in the repo; integrations with no adapter; site redirects nobody could export; anything set only in the app that the user didn't supply.

package/skills/blume-migrate/references/github-wiki.md

@@ -0,0 +1,259 @@
+# GitHub Wiki → Blume
+
+A GitHub wiki is a git repository beside the main one (`https://github.com/<owner>/<repo>.wiki.git`) that GitHub renders at `https://github.com/<owner>/<repo>/wiki`. It has no config file and no build: every file in a markup format GitHub renders is a page, `_Sidebar.md` and `_Footer.md` add the chrome, and pages link each other with `[[Page Name]]`. Five things set this migration apart:
+
+- **Folders don't count.** A page's URL is its file name, wherever the file sits (`codebase/compiler/Codebase-Compiler-Binder.md` is `/wiki/Codebase-Compiler-Binder`), and relative links and images resolve from `/<owner>/<repo>/wiki/`, never from the file's folder.
+- **`[[Link text|Page Name]]` puts the text first** in Markdown pages. GitHub's docs show the reverse, which is right only in `.mediawiki` pages, and Obsidian's `[[Page|text]]` is the reverse too, so don't point the `obsidian()` source at a wiki.
+- **Blume renders `[[…]]` as literal text.** It warns `BLUME_WIKILINK_UNSUPPORTED` only for a wiki link that names one of the site's pages or has a `|`, so `[[Page that doesn't exist]]` ships with a green build. Every wiki link has to be converted.
+- **The old URLs live on github.com,** which you can't redirect. What you can do there is in URLs and the old wiki below. Never tell the user the old links will redirect, and add no `redirects` for them.
+- **Nothing pins the routes,** so the new site gets clean ones: one flat lowercase route per page, as the wiki had one flat namespace, with the sidebar groups as `(group)/` folders.
+
+Scope: Markdown pages fully. Pages in the other formats GitHub renders get converted to Markdown first (Other markup formats). Checked against GitHub's wiki docs, the live rendering of public wikis (microsoft/TypeScript, microsoft/vscode, koreader, ruTorrent, qBittorrent, mpv, gollum, fzf, AdGuardHome) in October 2026, and an end-to-end migration of the microsoft/TypeScript wiki (77 pages). GitHub Enterprise Server wikis use the same files but weren't checked.
+
+## Detect
+
+`blume migrate` can't detect a wiki: name it, `npx blume migrate github-wiki`. A wiki clone has:
+
+- a remote ending in `.wiki.git` (`git remote -v`);
+- `Home.md` (or `Home` in another format) at the root, often `_Sidebar.md` and `_Footer.md`;
+- page files named like URLs (`Getting-Started.md`, `Standalone-Server-(tsserver).md`, sometimes `Roadmap‐2021‐2022.md` with U+2010 hyphens), `[[Page Name]]` links, no config, and usually no `package.json`.
+
+**Not this format:** Docsify keeps a lowercase `_sidebar.md` beside an `index.html` that sets `window.$docsify` (`references/docsify.md`). On macOS and Windows the file system ignores case, so `_Sidebar.md` and `_sidebar.md` are the same name to `ls`, `test -e`, and Node's `existsSync`: check the real case with `git ls-files`.
+
+**Get the pages from the default branch.** `git clone https://github.com/<owner>/<repo>.wiki.git`, then `git remote show origin` names the HEAD branch. GitHub publishes only that branch, so other branches never showed. If the wiki is mirrored from a normal repository (a sync workflow, or a footer saying "fork it and send a pull request"), the wiki clone is still what readers saw.
+
+## Where the Blume project goes
+
+The wiki repository can't host the new site: GitHub runs no Actions in it, serves no Pages from it, and accepts no pull requests. Ask the user where the docs will live:
+
+- **A folder in the main repository** (the usual choice: the docs then change in the same pull requests as the code). Follow `references/monorepo.md` for a code repo's root `package.json`, `dist/`, and workspace.
+- **A new repository**, for docs with their own maintainers.
+
+Without an answer, convert a copy of the wiki clone in place: `blume.config.ts` and `package.json` at its root, the pages moved into `docs/`, so the user can move the folder as one unit. **Before you start, run `git remote remove origin` in the copy.** Pushing the migrated tree to the wiki would publish `blume.config.ts`, every moved page, and the stubs you prepare later as wiki pages.
+
+Wiki history doesn't come along with a plain copy. To keep it for `git log --follow` and blame, bring the wiki in with `git subtree add --prefix=<folder> https://github.com/<owner>/<repo>.wiki.git <branch>` and say so in the report. Every page gets moved and edited either way, so `lastModified: "git"` would date every page to the migration commit until it's edited again (Blume follows a rename only when the file didn't change).
+
+## Run the codemod
+
+From the copy of the wiki clone (when the docs go into another folder, copy the wiki's files there first and run it from there), before any hand edits:
+
+```bash
+node <skill>/scripts/github-wiki-codemod.mjs routes --repo <owner>/<repo>            # report
+node <skill>/scripts/github-wiki-codemod.mjs routes --repo <owner>/<repo> --write    # write the route table
+# classify the pages in wiki-routes.json (next section)
+node <skill>/scripts/github-wiki-codemod.mjs convert --repo <owner>/<repo>           # dry run
+node <skill>/scripts/github-wiki-codemod.mjs convert --repo <owner>/<repo> --write   # apply
+```
+
+It's zero-dependency, deterministic, and idempotent (a second `convert` skips the pages it already moved). Add `--mirror <owner>/<repo>-wiki` when a repository mirrors the wiki, and `--emoji emojis.json` (from `curl -s https://api.github.com/emojis`) when pages use `:shortcodes:`.
+
+- **`routes`** lists the pages the way GitHub serves them and writes `wiki-routes.json` (page name → new route) and `wiki-files.json` (page name → file) beside `blume.config.ts`. It prints the files GitHub never served, routes that clash, digit-led routes, non-Markdown pages, and its guesses at moved notices and non-content pages. It never overwrites an existing table: it lists what differs instead.
+- **`convert`** does everything in the Navigation, Content, and Images sections below that the table and `_Sidebar.md` decide: moves each kept Markdown page to `docs/(group)/<route>.md` (`.mdx` when it needs MDX) with its frontmatter, converts wiki links, wiki URLs, alerts, fences, headings, named anchors, and duplicate link definitions, moves the wiki's images beside the pages, and writes every `meta.ts`. It prints the `navigation.featured` entries for `blume.config.ts`, the footer's text, and a `REVIEW` line for everything that needs judgment. **Every `REVIEW` line is a to-do**; the sections below say what to do with each.
+- **`check`** (after `blume build`) and **`stubs`** (for the old wiki) are in URLs and the old wiki.
+
+The sections below are the rules the codemod applies, for checking its output and for anything you do by hand.
+
+## The page list and the route table
+
+**Which files are pages.** Every file whose extension GitHub renders: `.md`, `.markdown`, `.mdown`, `.mkdn`, `.mediawiki`, `.wiki`, `.textile`, `.rst`, `.rest`, `.org`, `.creole`, `.asciidoc`, `.adoc`, `.asc`, `.pod`, `.rdoc`. The page name is the file name without its last extension (`README.html.md.md` is the page `README.html.md`), with spaces read as `-`. Matching is case-insensitive, `-` and space are the same, and U+2010 is not `-`.
+
+- **Not pages:** `_Sidebar.*` and `_Footer.*`, in any folder (GitHub even took `_Sidebar.html.md` as a sidebar). Every other `_`-prefixed file is a page (`_ [obsolete] Config.rest`), and Blume skips `_` files by default, so the rename matters.
+- **Two files with the same name** in different folders share one URL, and GitHub serves one of them (the root one, on the wiki checked). The other was never reachable: leave it out and report it.
+- **Every other file** (images, PDFs, `LICENSE`) is served raw at `/wiki/<path>`, which redirects to `https://raw.githubusercontent.com/wiki/<owner>/<repo>/<path>`.
+- **GitHub's own list** is `https://github.com/<owner>/<repo>/wiki/_pages` (every page, each linked at its URL). Compare the table with it.
+
+**Old URLs.** `Home` is `https://github.com/<owner>/<repo>/wiki` (`/wiki/Home` 301s there); every other page is `https://github.com/<owner>/<repo>/wiki/<Page-Name>`, percent-encoded.
+
+**New routes.** Each page's route is its name, lowercased, with apostrophes dropped and every other run of characters that aren't letters or digits turned into one `-` (`Standalone-Server-(tsserver)` → `/standalone-server-tsserver`, `What's-new-in-TypeScript` → `/whats-new-in-typescript`, `tsconfig.json` → `/tsconfig-json`); non-Latin letters stay. `Home` becomes `/`. Give one of two clashing pages another route by hand. A route that starts with digits and a separator (`/5-0-release-notes`) would lose them as an ordering prefix, so `convert` pins it with `slug`.
+
+**Classify every page** by editing its entry in `wiki-routes.json`:
+
+- **Content:** keep the route.
+- **A moved notice** (the whole page says it moved: "This page has moved to <URL>"): set its entry to that URL, or to the target page's route (with its `#anchor`) when the URL is another page of this wiki. It becomes no page; links to it go straight to the target. A short page that points elsewhere without saying it moved ("An introduction can be found in the handbook") is content: keep it.
+- **Not content:** a mirror repository's `README.md`, `SECURITY.md`, or `CONTRIBUTING.md`, test pages, script fixtures, and pages that only say "deprecated" with nowhere to point. Set the entry to `null` and list it in the report (SKILL.md step 2).
+
+`routes` prints its guesses for the moved notices and the non-content pages; confirm each one.
+
+## Config
+
+Wikis have no config: map what the repository and the special pages say.
+
+| GitHub wiki | Blume |
+| --- | --- |
+| Repository name | `title` (the project's name, or "`<Project>` wiki") |
+| Repository description (About) | `description` |
+| The repository | `navigation.repo: "https://github.com/<owner>/<repo>"` for the footer link. Set `github: { owner, repo, branch, dir }` only once the pages live in a repository, so **Edit on GitHub** opens the new file. Leave it unset while the home is unknown, and report it |
+| An image at the top of `_Sidebar.md` | `logo`, with the file in `public/` |
+| External links in `_Sidebar.md` | `navigation.featured`: `convert` prints the array |
+| `_Footer.md` links | `footer.links` |
+| `_Footer.md` text | a copyright or license line → `footer.copyright`, as plain text (Markdown stripped); other text → drop (report), or a `PageFooter` layout slot (`defineComponents`). A "contribute to this wiki" footer drops with its link: edit links replace it |
+| "edited this page … · N revisions" under each title | drop (report). `lastModified: "git"` would show the migration date on every converted page |
+| Wiki search, the Pages list, the per-page outline, the clone URL box | built in, or drop |
+| Site URL | none existed. Ask where the site deploys and set `deployment` (SKILL.md). GitHub Pages: https://useblume.dev/guides/markdown-docs-github-pages, with `deployment: { site: "https://<owner>.github.io", base: "/<repo>" }` for a project site |
+
+## Navigation: `_Sidebar.md` → `(group)/` folders
+
+GitHub showed two things in the right rail: the **Pages** list (every page, alphabetical) and, under it, `_Sidebar.md` rendered as Markdown. The sidebar becomes folders, and every page from the Pages list stays reachable.
+
+- **Each sidebar group becomes a `(group)/` folder** (SKILL.md): it adds the sidebar group and no URL segment, so every route stays the flat one from the table. Its `meta.ts` has `title` (the label as written) and `pages` (every child in sidebar order). The content root's `meta.ts` lists the groups in sidebar order.
+- **Group labels** are whatever heads a list: a bold line (`**News**`), a heading (`## Contributing`), or an unlinked list item with children (`* Testing`, a nested `(group)/` folder with `display: "group"`). A heading that links a page (`# [Tips and Tricks](…/wiki/Tips-and-Tricks)`) makes that page the group's own: a real folder with the page as its `index.md`. A heading that links outside (`## [User documentation](https://…)`) is a `navigation.featured` link.
+- **A page with nested pages under it** becomes a real folder named for its route, holding the page as `index.md`, its children, and a `meta.ts` with `pages` and `display: "group"`. Each child gets `slug: <its route without the slash>` so its route stays flat. Without `display: "group"`, a nested folder lists after every loose page of its parent group, not where the sidebar had it. Blume shows the parent both as the group header and as its first row; that's expected, so don't hide it.
+- **External links** can't sit inside a generated group, so they move to `navigation.featured` (above the sidebar, on every page); report the move. A link to a heading (`[Installation](…/User-patches#installation)`) has no row in Blume: drop it (the page's outline lists it) and report it.
+- **A page listed twice** stays in its first group; report the other entry. `[[Home]]` in the sidebar drops: the home page is `docs/index.md`, listed first, outside every group.
+- **Pages the sidebar doesn't list** were still in the Pages list: they go in a last group, `(more)/` with `title: "More pages"`, `display: "group"`, `collapsed: true`, and a `pages` list sorted by title (Blume's own order goes by file name, which differs for names like `'this' in TypeScript`). Pages that shared a wiki folder can get their own collapsed group instead (`(codebase)/`); report the groups you made.
+- **No `_Sidebar.md`:** GitHub showed only the Pages list, so the pages sit at the content root (Blume sorts them by title), or in groups by the wiki's folders if it had any; report the choice.
+- **A `_Sidebar.md` inside a folder** replaced the root one for that folder's pages. Usually it's a translation (`ru/_Sidebar.md` beside `ru/Home.ru.md`): map the folder to `i18n` when the pages pair up, else to a `navigation.tabs` entry, and report it.
+- Prose, images, and HTML lists in the sidebar have no place in Blume's sidebar: move a logo to `logo`, put useful prose on the home page, and report the rest.
+
+## Content
+
+### Page files and titles
+
+- **Each kept page** lands at `docs/(group)/<route>.md`, `Home` at `docs/index.md`. It stays `.md` unless it needs MDX (GitHub alerts, mermaid, math), then it's `.mdx` (MDX hazards below).
+- **`title`** is the page name as GitHub showed it above the page: `-` → space, U+2010 → `-` (`Standalone-Server-(tsserver)` → `Standalone Server (tsserver)`, `'this'-in-TypeScript` → `'this' in TypeScript`), quoted in YAML where needed.
+- **Body H1s.** GitHub drew the name as the title and every `#` in the body below it, so a page's H1s are sections, not its title (`# TypeScript 5.3` on a page named "API Breaking Changes"). A leading H1 that repeats the page name (ignoring case and punctuation) is deleted. If the page still has an H1, every heading is demoted one level (`#` → `##`, `##` → `###`, …; `######` stays), and a one-line setext heading becomes ATX one level down (`===` → `##`, `---` → `###`). A setext heading over several lines has no ATX form: `convert` reports it, so rewrite it as one `###` line by hand. Heading ids come from text, so demoting changes none.
+- **`sidebar.label`** is the sidebar's text for the page, when it differs from `title` by more than case and `-` versus space.
+
+### Wiki links
+
+Every `[[…]]` outside code converts. GitHub leaves `[[ … ]]` in fenced code alone (bash tests), and so does `convert`: it skips fenced (in a quote too) and indented code, inline code spans, `<code>` and `<tt>` elements, and HTML comments. An indented block that holds `[[` gets a `REVIEW` line, since list continuation and code look alike there. A code span that runs across lines isn't seen as code, so check any `REVIEW` line that quotes shell syntax (`[[ -f x ]]`).
+
+- **Inside an HTML block** (a line opening with `<div>`, `<p>`, `<table>`, `<details>`, and the like, up to the next blank line), Markdown shows as text, but gollum, the engine behind GitHub's wikis, resolves `[[…]]` before the Markdown is parsed, so it made a link there: `convert` writes `<a href="/page-name">text</a>` there, and a bare wiki URL too. An image tag there gets a `REVIEW` line: write it as `<img src="…" />` with the relative path the line gives (Blume publishes the file with the page), or move it out of the block. A `#` line inside the block is text, not a heading, so it isn't demoted.
+- **`'[[Page]]`** (an apostrophe right before, none right after) is gollum's escape for literal brackets: `convert` leaves it and reports it. Check the live page, and drop the apostrophe if it showed the brackets.
+- **`\[\[Page\]\]`** converts as a wiki link, because pandoc writes them that way (Other markup formats), with a `REVIEW` line: on a page that was always Markdown, GitHub showed those brackets, so restore them there.
+
+| GitHub (`.md` pages) | Blume |
+| --- | --- |
+| `[[Page Name]]` | `[Page Name](/page-name)`: the text as written, the route from the table |
+| `[[Link text\|Page Name]]` | `[Link text](/page-name)` |
+| `[[Page Name#anchor]]`, `[[text\|Page Name#anchor]]` | `[…](/page-name#anchor)`, the anchor as written |
+| `[[text\|https://…]]` | `[text](https://…)` |
+| `[[Home]]` | `[Home](/)` |
+| a page the wiki doesn't have (GitHub drew it as a link to create the page), or one set to `null` | plain text; reported |
+| a moved notice | a link to its target |
+| `[[image.png]]`, `[[/images/x.png\|alt=Text]]`, `[[x.png\|align=center,frame,alt=Text]]`, `[[https://…/x.png\|alt=Text]]` | an image: `![Text](…)` (Images and files). Any first part with an image extension is an image, whatever follows; options are separated by `,` or `\|`. A leading `/` is the wiki root. A path the root doesn't have but the page's own folder does resolves there, reported. Options other than `alt=` (`width=`, `align=`, `frame`, stray text) drop; reported |
+| `[[text\|docs/spec.pdf]]` (a file stored in the wiki) | left as is and reported: copy the file into `public/` and link its root path |
+| `[[_TOC_]]` | deleted: GitHub lists a table of contents among unsupported syntax, and Blume's outline shows the headings |
+
+(In this table `\|` is the table's escape for a single pipe.) GitHub trims spaces around the pipe (`[[Mailing list | https://…]]`), and inside a Markdown table cell the pipe may be written `\|`. Pages are looked up the way GitHub did: by name, ignoring case, with `-` and space interchangeable and folders ignored. **Anchors are case-sensitive in Blume** and weren't on GitHub, wherever they appear: when `blume validate` reports one (`#TSDeclFiles` for a heading pinned `[#TsDeclFiles]`), match the id's case.
+
+### Markdown links
+
+| Link | Blume |
+| --- | --- |
+| `https://github.com/<owner>/<repo>/wiki/Page-Name` (any case of owner and repo, `http`, `www.`), `/<owner>/<repo>/wiki/Page-Name`, or bare `Page-Name` / `./Page-Name` | the page's route through the table, keeping `#anchor`, percent-decoded (`%28` is `(`) |
+| `…/wiki`, `…/wiki/`, `…/wiki/Home` | `/` |
+| a mirror repository's copy of a page (`https://github.com/<owner>/<repo>-wiki/blob/<branch>/Page.md`) | the page's route (`--mirror`): the mirror goes stale with the wiki |
+| a bare wiki URL in prose, or `<https://…/wiki/Page>` | `[Page title](/route)` |
+| a page's file by its path (`dir/Page.md`, `…/wiki/dir/Page.md`), which GitHub served raw | the page's route; reported |
+| `#user-content-x` | `#x` (GitHub's ids carry that prefix, so both forms worked there) |
+| relative links that leave the wiki (`../issues/12`, `../blob/main/src/x.ts`, `../../other-repo`) | the absolute URL each resolved to from `https://github.com/<owner>/<repo>/wiki/<page>` (`../issues/12` → `https://github.com/<owner>/<repo>/issues/12`) |
+| a link to a page that doesn't exist (`./formatter.md`, `GLOSSARY.md#x`: GitHub served nothing there) | left as is and reported: it was broken on GitHub too, so retarget it (often the page moved to another repository) or unlink it |
+| `…/wiki/_pages`, `…/wiki/<Page>/_history`, revision URLs | left and reported: they point at the wiki's UI and stop working with it |
+| another repository's wiki | unchanged |
+
+`#123` and `@user` are plain text in wikis (GitHub doesn't autolink them there), so they stay. Bare URLs autolink in both. A raw HTML `<a href>` to a wiki page gets the route too (and a wiki link in an HTML block becomes one); Blume adds `deployment.base` to its root path like a Markdown link's.
+
+### Link definitions
+
+`blume validate` checks every link reference definition the page uses, including ones nothing cites; when a label is defined twice it checks only the first, which CommonMark uses. Wikis kept by scripts collect definitions that never rendered:
+
+- **A later definition of a label** never rendered: `convert` deletes it.
+- **A Foam or VS Code block** of autogenerated definitions (`[//begin]: # "Autogenerated link references…"` … `[//end]: #`) goes too: once the wiki links are converted, nothing uses it.
+- **A line like `[1]: <src/file.ts - function x(`** with no closing `>` isn't a definition at all: it shows as text, on GitHub and in Blume alike. Leave it, or delete it if it's leftover tooling syntax, and report it.
+
+### GitHub Markdown
+
+| GitHub | Blume |
+| --- | --- |
+| `> [!NOTE]`, `[!TIP]`, `[!IMPORTANT]`, `[!WARNING]`, `[!CAUTION]` at the start of a line | `:::note`, `:::tip`, `:::note`, `:::warning`, `:::danger`, in `.mdx`. Blume renders an alert itself as the same callout in `.mdx`, so `convert` leaves one indented in a list, or with lazy lines, as written and makes the page `.mdx`. One with text after its marker, or no body, is reported: convert it by hand. In a `.md` page an alert renders as a quote with a literal `[!NOTE]` and warns `BLUME_MD_GITHUB_ALERT`: rename the page to `.mdx`. The older `> **Note**` form is a plain quote on GitHub today: leave it |
+| ` ```mermaid ` | the same fence, in `.mdx` |
+| ` ```math ` | a `$$` block, in `.mdx` |
+| `$…$`, ``$`…`$``, `$$…$$` | by hand: `$$…$$` in `.mdx` (inline ones stay in their sentence; SKILL.md "Math") |
+| ` ```geojson `, `topojson`, `stl` | a code block: maps and 3D models drop; reported |
+| Fence languages | lowercased (`TypeScript` → `typescript`), which only tidies: Blume reads them in any case, as GitHub did. `posh` → `powershell`. Any other name Shiki lacks renders as plain text and warns `BLUME_UNKNOWN_CODE_LANGUAGE`: change it to a Shiki language, or `text` |
+| `:emoji:` shortcodes | the character, with `--emoji`. GitHub slugged a heading's shortcode name, so a heading with one is reported: convert it and pin the old id (`## ⚠️ Known issues [#warning-known-issues]`) |
+| `<a name="x"></a>` in a heading | deleted, with `[#x]` pinned on the heading (Blume would give the heading the id `x` anyway). Elsewhere it stays: links to `#x` work, and `blume validate` resolves them |
+| task lists, tables, footnotes, strikethrough, autolinks, `<details>` | unchanged |
+| `style=`, `<script>`, `<iframe>`, `<form>`, `<input>` | by hand: GitHub's sanitizer removed them, so readers never saw them, while Blume renders raw HTML as written. Delete them, or keep one deliberately and report it |
+
+Heading ids need no pinning beyond the rows above: GitHub and Blume both slug with `github-slugger` (identical ids for all 710 headings on the wiki pages checked). The exception is a heading that ends in an emoji or symbol after a space: GitHub keeps the trailing dash (`## Features ✨` → `#features-`), Blume drops it (`#features`); `blume validate` reports the links to fix. Deleting a leading H1 can shift the `-1` suffix of a later heading with the same text; `blume validate` reports the links that break. `pin-heading-ids.mjs` can't read a wiki anyway: GitHub puts each id on a link beside the heading, not on the heading.
+
+### MDX hazards
+
+MDX rejects things GitHub's Markdown accepts, and a page renamed to `.mdx` fails `blume build` on them. In prose (outside code), `convert` fixes the mechanical ones in the pages it renames: a `<` that doesn't start a tag (`TypeScript >=1.6, <7` → `&lt;7`), bare `{` and `}` (escaped `\{`), HTML comments (`{/* */}` on one line), unclosed void tags (`<br>` → `<br />`), `<https://…>` autolinks, and indented code (MDX has none, so a top-level indented block gets a fence; a backslash-escaped backtick doesn't start inline code, so braces after it get escaped too). It reports the rest:
+
+- **A tag-like word** (`Array<string>` outside code, `<placeholder>`): MDX reads it as an unclosed JSX element. Put it in backticks.
+- **Raw HTML blocks** (`<details>`, `<div>`, `<table>`) with Markdown inside: MDX parses that Markdown only with blank lines around it, and fails on tags interleaved with list items. Add the blank lines, or turn the block into Markdown.
+- **Indented code inside a list:** fence it by hand, at the list item's indentation.
+
+### Other markup formats
+
+Convert each non-Markdown page to Markdown before `convert` (which skips and lists them): `pandoc -f <format> -t gfm-raw_html --wrap=preserve page.<ext> -o page.md` (`mediawiki`, `textile`, `rst`, `org`, `creole`, `asciidoc`, `pod`). `.rdoc` has no pandoc reader: convert it by hand. Delete the original, point the page's entry in `wiki-files.json` at the new `.md` file, and rerun `convert`.
+
+- **MediaWiki pages put the target first,** `[[Page Name|text]]`, as MediaWiki does. Pandoc turns them into `[text](Page_Name "text")`, with `_` for spaces, and `convert` maps those to routes.
+- **In the other formats** pandoc escapes `[[…]]` to `\[\[…\]\]`, and `convert` reads those as Markdown wiki links (text first).
+- Heading ids differ in these formats. Compare each converted page with the live one, and list every conversion in the report.
+
+## Frontmatter
+
+GitHub reads no frontmatter, so wiki pages have none. Each page gets `title`, plus `sidebar.label` and `slug` where the sections above say so. If a page opens with a `---` block anyway, check the live page for what readers saw, keep that as content or drop it, and report it.
+
+## Images and files
+
+- **Files stored in the wiki** (`https://raw.githubusercontent.com/wiki/<owner>/<repo>/<path>`, `https://github.com/<owner>/<repo>/wiki/<path>`, or a relative `<path>`, which resolves from the wiki root whatever the page's folder) go away with the wiki. `convert` moves each referenced one into `docs/` at the same path (`docs/images/x.png`) and points the page at it relatively (`../images/x.png` from a `(group)/` page): Blume optimizes and validates relative Markdown images.
+- **A relative image that pointed at nothing** (it climbs out of the wiki root, like `../../screenshots/x.png`, or names a file the wiki doesn't have) was broken on GitHub too, and fails `blume build`: `convert` drops it and reports it.
+- **Uploaded attachments** (`user-images.githubusercontent.com`, `github.com/user-attachments/assets/…`, `private-user-images.githubusercontent.com`) are served outside the wiki and keep working for a public repository. `convert` reports each one: download and vendor it next to the pages (one request at a time) unless the user objects. From a private or internal repository they need a GitHub login, so vendoring is required.
+- **`https://github.com/<owner>/<repo>/blob/<ref>/<path>`** shown as an image is an HTML page anywhere but GitHub: `convert` uses `https://raw.githubusercontent.com/<owner>/<repo>/<ref>/<path>`.
+- **Raw `<img>` alone on its line** becomes a Markdown image; its `width`/`height`/`align` drop and are reported. A raw `<img>` of a wiki file inside other HTML (a table cell, a `<p>`) is reported: its `src` still reads from the wiki root, which isn't the page's new folder. Copy the file into `docs/` at the same path, as `convert` does for the others, and point `src` at it relative to the page (`../images/x.png`), which Blume publishes with the page, unoptimized; or make it a Markdown image.
+- **Linked files** (PDFs, archives, an image opened as a link) are reported: copy each into `docs/` at the same path and link it relative to the page, which publishes it with the page, or into `public/` and link its root path for a URL that never changes.
+- `#gh-dark-mode-only` / `#gh-light-mode-only` pairs: keep the light image (report).
+- Files nothing references stay in the wiki (other sites may hotlink them): report them, don't copy them.
+
+## URLs and the old wiki
+
+Every old URL is on github.com. GitHub has no redirect setting for wiki pages, and it sanitizes their HTML (no `<script>`, no `<meta>` refresh), so nothing on the old wiki can forward a reader. Don't add Blume `redirects` for them either: they would only match paths on the new site. The route table is the record instead: each old page name maps to its new route, a target URL, or `null`.
+
+**Check the table against the build** after `blume build`: `node <skill>/scripts/github-wiki-codemod.mjs check` confirms every route in the table exists in `dist/` (`dist/client/` on a server build), anchors included. Given the old URLs instead (every line of a saved `_pages` list, for one), it prints each one's new route: `ok`, `moved` for a moved notice's outside target, `DROPPED` for a page set to `null`, or `MISSING` for a page the table lacks.
+
+**What the user can do on the old wiki** (prepare it, but never commit or push it, even with push access: `stubs` only writes files, and whether and when anything goes to `<repo>.wiki.git` is the user's decision, after the new site is live):
+
+1. **Restrict editing** (Settings → Features, under Wikis: **Restrict editing to collaborators only**) as soon as the migration starts, so the content stops drifting.
+2. **Stop anything that syncs the wiki, before pushing anything to it.** Otherwise it reverts the stubs or copies them on. Look for a workflow triggered `on: gollum` (wiki edits) in the main repository, a mirror repository (`<repo>-wiki`) whose workflow pushes to `<repo>.wiki.git` on push or on a schedule, a copy of that workflow inside the wiki itself, and wiki-publishing actions. List every one you find.
+3. **Point readers at the new site:** a notice at the top of `Home` and `_Sidebar.md` (the sidebar shows on every page). In a fresh clone of the wiki (not the Blume project: `stubs` refuses to run beside `blume.config.ts`), with `wiki-routes.json` and `wiki-files.json` copied in (don't commit them there): `node <skill>/scripts/github-wiki-codemod.mjs stubs --site https://docs.example.com --notice-only --write`.
+4. **Or replace every page with a link stub,** so deep links from issues, search results, and bookmarks land one click from the new page: the same command without `--notice-only`. Each page keeps its file name, so its URL keeps working; `_Footer` files go, `_Sidebar.md` becomes the notice, images stay for sites that hotlink them, and pages set to `null` are listed for the user to decide. `--site` is the new site's URL with its base path, so regenerate the stubs once the real URL is known.
+5. **Disable the wiki** (Settings → Features → Wikis), once the repository's own links point at the new site. GitHub hides every page, stubs included, without erasing them. It's the user's call; it's never required.
+
+Whether search engines matter: `curl -sI https://github.com/<owner>/<repo>/wiki | grep -i x-robots-tag` prints `none` for a wiki GitHub keeps out of search results (GitHub indexes only wikis with 500+ stars and editing restricted to collaborators). Without it, search results keep sending readers to the old pages for a while, and the stubs are what they find.
+
+**Inbound links in the main repository.** Search its clone with `git grep -n -i -E 'github\.com/<owner>/<repo>/wiki'`: README, CONTRIBUTING, `docs/`, `.github/ISSUE_TEMPLATE/`, `SECURITY.md`, code comments and test fixtures, `package.json` `homepage`. A large repository doesn't need a full clone: `git clone --depth 1 --filter=blob:none --sparse <url>`, then `git sparse-checkout set --no-cone '/*' '!/tests/baselines/'` (excluding its biggest generated folders). Map each URL through the table with `check`, which also verifies its anchor against the build and suggests ids for one that's gone:
+
+```bash
+node <skill>/scripts/github-wiki-codemod.mjs check https://github.com/<owner>/<repo>/wiki/FAQ#common-bugs
+# MISSING ANCHOR  …/wiki/FAQ#common-bugs → /faq#common-bugs (ids like: common-bugs-that-arent-bugs)
+```
+
+An old link can carry an anchor that was already dead on GitHub: fix it to a real id, don't copy it. Rewrite each link with the new site's origin (or ask first, when the user only wants a report), and set the repository's About → Website to the new site if it pointed at the wiki. Links in issues, pull requests, and other repositories can't be rewritten: the stubs catch them. List the files you changed or would change.
+
+### Leftover check
+
+Rerun until it prints only code samples you mean to keep:
+
+```bash
+grep -rnE '\[\[|user-content-|(^|\s):[a-z0-9_+][a-z0-9_+-]*:(\s|$)' docs
+grep -rniE 'raw\.githubusercontent\.com/wiki/|github\.com/<owner>/<repo>/wiki' docs   # any case of owner and repo
+```
+
+An alert left in a `.md` page warns `BLUME_MD_GITHUB_ALERT`, and an unknown fence language `BLUME_UNKNOWN_CODE_LANGUAGE`, so `blume build` lists those.
+
+## Teardown
+
+- **Files left behind.** Converting in place leaves the pages you didn't keep where they were: moved notices, `null` pages, the files GitHub never served, and unreferenced images. `convert` lists them. Delete them from the project (nothing under the root publishes, but they confuse later edits): the wiki keeps them, and `wiki-files.json` records their paths for the stubs. Delete `_Sidebar.md` and `_Footer.md` once `convert` has harvested them (a later `convert` then leaves the `meta.ts` files as they are).
+- **Wiki tooling** (a `package.json` for a Markdown generator, link-rewriting scripts, sync scripts and workflows) stays only if it still applies to the pages: run each script in its dry or check mode against `docs/` and see whether any page still uses the syntax it converts. If none does, it goes, with the dependencies only it used. Say which you kept.
+- **Lockfiles:** a mirror repository's `.gitignore` often ignores `package-lock.json` or `yarn.lock`. Remove those lines, so the lockfile SKILL.md step 6 regenerates gets committed.
+- Keep `wiki-routes.json` and `wiki-files.json` beside `blume.config.ts` until the stubs are pushed and the inbound links are rewritten.
+- Scaffold `package.json` (SKILL.md step 6) if the docs' new home has none.
+
+## Dropped — report these
+
+The Pages list and the clone box; footer text other than a copyright line, and its link; sidebar prose, images, anchor links, and duplicate entries; external sidebar links moved to `navigation.featured`; the per-page "edited … · N revisions" line; image sizes and wiki image options; images that were broken on GitHub; maps and 3D models; theme-aware image pairs; raw HTML GitHub had stripped; links to missing pages (GitHub's create-page links) and links that were already broken; shadowed link definitions; pages left out (mirror files, tests, fixtures, deprecated stubs) and moved notices mapped to their targets; pages GitHub never served (same-name shadows); non-Markdown pages converted with pandoc; wiki-UI links (history, revisions, `_pages`); and every old URL, which stays on github.com: say what you prepared for it (notice, stubs, or neither), which sync workflows must stop first, and that nothing redirects.