@mintlify/cli 4.0.1763 → 4.0.1764

package/migrate/sources/gitbook.md

@@ -0,0 +1,120 @@
+# GitBook
+
+Hosted GitBook sites (`*.gitbook.io` or a custom domain) and GitBook content synced to GitHub or GitLab. GitBook calls each content container a section (older docs: space); a site publishes one or more sections, each optionally with variants.
+
+## Detect
+
+- Rendered HTML has `<meta name="generator" content="GitBook ...">` and loads assets from `/~gitbook/static/` and `/~gitbook/image`.
+- `<page-url>.md` returns markdown containing `{% hint %}`, `{% tabs %}` or `<figure>` blocks.
+- In a repo: `.gitbook.yaml`, `SUMMARY.md`, `.gitbook/assets/`, `.gitbook/includes/`, or `gitbook-docs.yaml`.
+
+## Get the source
+
+### From the repo
+
+A Git Sync repo, one per section and variant. Layout:
+
+- `.gitbook.yaml`: `root` (content directory, default `./`), `structure.readme` (default `README.md`), `structure.summary` (default `SUMMARY.md`), `redirects`. Resolve all paths relative to `root`. Reference: https://gitbook.com/docs/docs-as-code/git-sync/content-configuration
+- `SUMMARY.md`: the navigation and the inventory.
+- `.gitbook/assets/`: uploaded images and files. `.gitbook/includes/`: reusable content. `.gitbook/vars.yaml`: section variables.
+- `gitbook-docs.yaml`, when present, maps the site's sections to directories.
+
+### From an export
+
+The export is the Git Sync repo. The customer enables Git Sync per section with the direction GitBook → GitHub/GitLab into an empty repo, then gives you a clone. The opposite direction overwrites their GitBook content; tell them to confirm the direction. Repeat for every published section and variant. Steps: https://www.mintlify.com/docs/migration/gitbook.md
+
+### From the live site
+
+Every published page serves raw markdown at `<page-url>.md`; `llms.txt` and `llms-full.txt` list pages. `sitemap.xml` is a `<sitemapindex>` with one `sitemap-pages.xml` per section and language. Quirks (`mint migrate --topic discovery`, Mirror the raw source):
+
+- The site or section root does not answer on `<root>.md`; fetch `<root>/readme.md`.
+- Strip the leading `> For the complete documentation index, see [llms.txt]...` line and everything from `\n---\n# Agent Instructions...` to end of file.
+- Published `.md` shows variable expressions, not their values. Resolve them from the rendered page.
+
+Private sections, unpublished changes and reusable-content source are not reachable here (`mint migrate --topic discovery`, Gated content).
+
+## Config → docs.json
+
+GitBook site customization is not in the repo. Read it from the published HTML.
+
+| GitBook                                                  | docs.json                                                      |
+| -------------------------------------------------------- | -------------------------------------------------------------- |
+| Site title                                               | `name`                                                         |
+| Logo (light/dark)                                        | `logo.light`, `logo.dark`                                      |
+| Site icon / favicon                                      | `favicon`                                                      |
+| Primary / tint color                                     | `colors.primary`                                               |
+| Header links                                             | `navbar.links`                                                 |
+| Footer links                                             | `footer.links`                                                 |
+| Sections shown as top-level tabs                         | `navigation.tabs`                                              |
+| Variants used for versions                               | `navigation.versions` if the customer migrates them            |
+| Variants used for languages                              | `navigation.languages` if the customer migrates them           |
+| `.gitbook/vars.yaml` variables                           | `variables` (`mint migrate --topic conversion`, Template tags) |
+| `.gitbook.yaml` `redirects` and site-level redirects     | `redirects` (see URLs and redirects)                           |
+| Site sharing, visitor auth, adaptive content             | drop and report                                                |
+| Integrations (analytics, chat, feedback), custom scripts | drop and report                                                |
+| Search and AI assistant settings                         | drop and report                                                |
+
+## Navigation
+
+Walk `SUMMARY.md`. Without a repo, rebuild the same tree from the rendered sidebar of each section.
+
+- `## Heading` lines become groups, in order.
+- `* [Title](path.md)` becomes a page; indented children make it a nested group whose own page goes first.
+- `[Title](path.md "Label")`: the quoted text is the sidebar label (`mint migrate --topic conversion`, Frontmatter).
+- External links become navigation links where Mintlify supports them.
+- Pages with frontmatter `hidden: true` stay reachable but out of navigation; (`mint migrate --topic navigation`, Structure rules).
+- Page frontmatter `icon` maps to the page `icon` (`mint migrate --topic conversion`, Icons).
+
+## Content conversion
+
+Run these in order on every file. Match every `{% ... %}` with a non-greedy pattern such as `\{%[\s\S]*?%\}`, never `\{%[^%]*%\}`, because attribute values contain URL-encoded `%`.
+
+| GitBook                                                                     | Mintlify                                                                                     |
+| --------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
+| `{% hint style="info" %}`                                                   | `<Info>`                                                                                     |
+| `{% hint style="success" %}`                                                | `<Check>`                                                                                    |
+| `{% hint style="warning" %}`                                                | `<Warning>`                                                                                  |
+| `{% hint style="danger" %}`                                                 | `<Danger>`                                                                                   |
+| `{% tabs %}{% tab title="X" %}`                                             | `<Tabs><Tab title="X">`                                                                      |
+| `{% stepper %}{% step %}`                                                   | `<Steps><Step title="...">`; title from the step's first heading or bold line, else `Step N` |
+| `{% columns %}{% column %}`                                                 | `<Columns>`                                                                                  |
+| `{% code title="f.js" lineNumbers="true" overflow="wrap" %}` around a fence | fence with `title="f.js"`, `lines`, `wrap`                                                   |
+| `<details><summary>X</summary>`                                             | `<Accordion title="X">`                                                                      |
+| `<table data-view="cards">`                                                 | `<CardGroup>` of `<Card>`; target from the `data-card-target` column                         |
+| `{% content-ref url="x.md" %}` (and legacy `{% page-ref %}`)                | `<Card>` linking to the page                                                                 |
+| `{% embed url="X" %}`                                                       | YouTube/video embed if supported, else a link `[X](X)`                                       |
+| `{% file src="X" %}`                                                        | download link to the copied file                                                             |
+| `{% include "../.gitbook/includes/x.md" %}`                                 | snippet (`mint migrate --topic conversion`, Reusable content)                                |
+| `{% updates %}` entries                                                     | `<Update>` (see `mint migrate --topic changelog`)                                            |
+| `<code class="expression">space.vars.X</code>`, `page.vars.X`               | `{{X}}` (`mint migrate --topic conversion`, Template tags)                                   |
+| `$$...$$`                                                                   | LaTeX, unchanged                                                                             |
+| `<a class="button primary" href>`                                           | plain link; report                                                                           |
+| `<mark style="color:...">text</mark>`                                       | `text`                                                                                       |
+| `<figure><img src alt><figcaption>` / `<picture><source srcset>`            | image with alt; keep a non-empty caption in `<Frame caption>`                                |
+
+Then:
+
+- Convert `<div data-gb-custom-block data-tag="hint|tabs|tab" ...>` variants to the same components as their `{% %}` forms, then drop remaining `data-gb-custom-block` openers and their closers.
+- Strip any `{% ... %}` still present after mapping.
+- Unescape GitBook backslash escapes (`\[ \] \( \) \{ \} \_ \*`) before MDX escaping.
+- Remove the empty heading anchors GitBook emits (`<a href="#x" id="x"></a>` inside or above headings). GitBook heading ids differ from Mintlify's (`mint migrate --topic conversion`, Heading IDs).
+
+## Assets
+
+- Repo: copy `.gitbook/assets/` into `images/` keeping relative structure. Asset filenames often contain spaces and parentheses (`mint migrate --topic conversion`, Images and files).
+- Live site: images appear as `/files/<id>`, `https://<n>-files.gitbook.io/~/files/v0/b/...?alt=media&token=...` and `/~gitbook/image?url=<encoded>` (a resized proxy; decode `url=` for the original).
+- `/files/<id>` URLs that 404 on the site usually exist in `.gitbook/assets/`; recover them from the repo before reporting them missing.
+
+## URLs and redirects
+
+- Page URLs come from the `SUMMARY.md` hierarchy, not file paths. Keep each page at its published path; `README.md` pages publish at the directory path (`mint migrate --topic conversion`, Files).
+- Scraped markdown links pages by id: `/pages/<id>` and `/spaces/<id>/pages/<id>`. Resolve them from the rendered page links (`mint migrate --topic conversion`, Links).
+- Convert `.gitbook.yaml` `redirects` (old path → file) to `redirects`, prefixing the section path, because GitBook scopes them to one section (`mint migrate --topic navigation`, Redirects). Ask the customer for site-level redirects; they are not in the repo.
+- The default variant may be served without its slug; add redirects for both forms.
+
+## Known gaps
+
+- Visitor authentication, adaptive content and site sharing settings.
+- OpenAPI blocks: specs live at organization level, not in the section export. Ask the customer for the spec file or URL; then follow `mint migrate --topic api`.
+- Buttons, inline icons (`<i class="fa-...">`), and integration blocks with no equivalent.
+- Reusable content owned by a section outside the export.

package/migrate/sources/github-wiki.md

@@ -0,0 +1,90 @@
+# GitHub Wiki
+
+## Detect
+
+- The user names a wiki or gives `https://github.com/<owner>/<repo>/wiki`. A wiki is a separate git repository; nothing in the main repo signals it.
+- In a clone: the remote ends in `.wiki.git`; `Home.<ext>` at the root; optional `_Sidebar.<ext>` and `_Footer.<ext>`; files named like page titles; `[[...]]` links; no config file.
+- Not a wiki: Docsify, which uses a lowercase `_sidebar.md` beside an `index.html` that sets `window.$docsify`. Check real filename case with `git ls-files`.
+
+## Get the source
+
+### From the repo
+
+- `git clone https://github.com/<owner>/<repo>.wiki.git`. Only the default branch is published.
+- Every file in a markup format GitHub renders is a page (https://github.com/github/markup#markups). Convert non-Markdown pages to Markdown first (for example `pandoc -t gfm`).
+
+### From an export
+
+None; use the `.wiki.git` clone.
+
+### From the live site
+
+GitHub's own page list: `https://github.com/<owner>/<repo>/wiki/_pages`. Use the clone for sources.
+
+Reference: https://docs.github.com/en/communities/documenting-your-project-with-wikis
+
+## Config → docs.json
+
+Wikis have no config.
+
+| Wiki source                                               | docs.json                         |
+| --------------------------------------------------------- | --------------------------------- |
+| repository name / About description                       | `name` / `description`            |
+| repository URL                                            | `navbar.links` (`type: github`)   |
+| image at the top of `_Sidebar.md`                         | `logo`                            |
+| external links in `_Sidebar.md`                           | `navigation.global.anchors`       |
+| `_Footer.md` links                                        | `footer.links` / `footer.socials` |
+| `_Footer.md` prose, revision info, wiki search, clone box | drop and report                   |
+
+## Navigation
+
+- `_Sidebar.md` is free-form Markdown. A heading, bold line or unlinked list item with children → group; nested lists → nested groups; a heading that links a page → group with that page as `root`; each page link → a page, in order.
+- Sidebar links to headings (`Page#section`) have no sidebar slot: report.
+- A page listed twice keeps its first position. `[[Home]]` is the home page.
+- Pages missing from `_Sidebar.md` were still reachable from GitHub's page list: ask the user where they go.
+- No `_Sidebar.md`: GitHub showed only the alphabetical page list.
+- A `_Sidebar.md` inside a folder applies to that folder's pages, often a translation: report it.
+
+## Content conversion
+
+- Flat namespace: a page's name is its file name without extension; folders do not count. Names match case-insensitively and treat `-` and space as the same. Build a page name → new path index (`Home` → the index page; `mint migrate --topic conversion`, Links); resolve name clashes by hand.
+- The page title is the file name with `-` shown as a space. GitHub renders it above the body, so a body `# H1` is a section heading: drop it only if it repeats the page name.
+
+| Wiki                                                                                                   | Mintlify                                                         |
+| ------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------- |
+| `[[Page Name]]`                                                                                        | `[Page Name](/<path>)` via the table                             |
+| `[[Link text\|Page Name]]` (text first in Markdown pages; Gollum order)                                | `[Link text](/<path>)`                                           |
+| `[[Page Name#anchor]]`                                                                                 | `/<path>#anchor`                                                 |
+| `[[text\|https://...]]`                                                                                | `[text](https://...)`                                            |
+| `[[image.png]]`, `[[/path/image.png\|alt=Text]]`                                                       | `![Text](/path/image.png)`; other image options drop             |
+| `[[Page\|Text]]` in `.mediawiki` pages                                                                 | MediaWiki order: page first                                      |
+| `[[...]]` to a page that does not exist                                                                | plain text; report                                               |
+| `[[_TOC_]]`                                                                                            | delete                                                           |
+| `https://github.com/<owner>/<repo>/wiki/Page-Name`, `/<owner>/<repo>/wiki/Page-Name`, bare `Page-Name` | `/<path>` via the table                                          |
+| relative links that leave the wiki (`../issues/12`, `../blob/main/x`)                                  | absolute GitHub URLs resolved from `/<owner>/<repo>/wiki/<page>` |
+| `#user-content-x`                                                                                      | `#x`                                                             |
+| `> [!NOTE]` style alerts                                                                               | (`mint migrate --topic conversion`, GitHub alerts)               |
+| `:emoji:` shortcodes                                                                                   | the emoji                                                        |
+
+Skip `[[...]]` inside code. Link syntax: https://github.com/gollum/gollum/wiki#link-tag
+
+## Assets
+
+- Non-page files in the wiki repo are served under the wiki URL. Copy every referenced file into the docs repo.
+- Images hosted on `user-images.githubusercontent.com`, `github.com/user-attachments/...` or the main repo's `blob/` URLs: download them.
+
+## URLs and redirects
+
+- Old URLs are `https://github.com/<owner>/<repo>/wiki` (Home) and `https://github.com/<owner>/<repo>/wiki/<Page-Name>`. They stay on github.com and cannot redirect. Add no `redirects` for them, and do not tell the user they will redirect.
+- Produce a route table instead (outside the docs content), one row per wiki page: `wiki_url`, `page_name`, `new_path`, `status` (`migrated`, `merged into <path>`, `dropped`).
+- Offer, but do not do without approval: replace each wiki page with a "Moved to <new URL>" line, point `Home` and `_Sidebar.md` at the new site, then disable the wiki.
+
+## Known gaps
+
+- Old wiki URLs cannot redirect.
+- Wiki revision history (kept only if the wiki is merged with `git subtree add`).
+- Formatting lost when converting non-Markdown pages.
+- `[[...]]` image options other than `alt`.
+- Sidebar prose, images and heading links.
+- Links that were already broken on the wiki, and links to `_pages`, `_history` or revision URLs.
+- Heading anchors (`mint migrate --topic conversion`, Heading IDs).

package/migrate/sources/jekyll.md

@@ -0,0 +1,104 @@
+# Jekyll
+
+Covers Jekyll and Just the Docs (JTD)-style themes.
+
+## Detect
+
+- `_config.yml` at the root or in `docs/`.
+- JTD: `theme: just-the-docs` or `remote_theme: just-the-docs/just-the-docs` (or `pmarsceill/just-the-docs`), or the gem in `Gemfile`. Pages carry `nav_order` / `parent`.
+- Confirming tells: `_layouts/`, `_includes/`, `_data/`, `_posts/`, a `Gemfile` with `jekyll` or `github-pages`.
+- Not Jekyll: `_config.yml` with `_toc.yml` (Jupyter Book) or with `hexo` in `package.json`.
+- `gem "github-pages"`, or a `remote_theme` with no `Gemfile`, means GitHub Pages' build, which force-enables plugins such as `jekyll-optional-front-matter`, `jekyll-titles-from-headings`, `jekyll-relative-links` and `jekyll-readme-index`.
+
+## Get the source
+
+### From the repo
+
+- Pages: `.md`, `.markdown` and `.html` files with front matter outside `_` folders and outside `exclude`. Collections: `_<name>/` folders declared under `collections:` (inside `collections_dir` if set). Posts: `_posts/`.
+- Build: `JEKYLL_ENV=production bundle exec jekyll build -d <dir>` (`mint migrate --topic discovery`, From the repo).
+
+### From an export
+
+None; the site is built from the repo.
+
+### From the live site
+
+`sitemap.xml` comes from jekyll-sitemap. Sources come from the repo named in `repository` or `gh_edit_repository`.
+
+## Config → docs.json
+
+| \_config.yml                                                                                                              | docs.json                                                                                                    |
+| ------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| `title` / `description`                                                                                                   | `name` / `description`                                                                                       |
+| `logo` / `favicon_ico` (JTD)                                                                                              | `logo` / `favicon`                                                                                           |
+| `color_scheme: dark` (JTD)                                                                                                | `appearance.default: "dark"`                                                                                 |
+| custom JTD color scheme (`_sass/color_schemes/<name>.scss`)                                                               | `colors.primary` from its link color                                                                         |
+| `aux_links` (JTD)                                                                                                         | `navbar.links`                                                                                               |
+| `nav_external_links` (JTD)                                                                                                | `navigation.global.anchors`                                                                                  |
+| `footer_content`, `_includes/footer_custom.html`                                                                          | `footer.links` / `footer.socials`; report other text                                                         |
+| `repository`, `gh_edit_repository`                                                                                        | `navbar.links` (`type: github`)                                                                              |
+| `ga_tracking` (JTD), `google_analytics`                                                                                   | `integrations.ga4.measurementId`                                                                             |
+| `twitter`, `github_username`, `social`                                                                                    | `footer.socials`                                                                                             |
+| keys read as `{{ site.x }}`                                                                                               | `variables` (`mint migrate --topic conversion`, Template tags)                                               |
+| `url`, `baseurl`                                                                                                          | none; their host and path are part of every old URL                                                          |
+| `callouts` (JTD)                                                                                                          | none; names the callouts used in Content conversion                                                          |
+| `permalink`, `defaults`, `collections`                                                                                    | none; drive URLs and Navigation                                                                              |
+| `plugins`                                                                                                                 | `jekyll-redirect-from` → URLs below; `jekyll-seo-tag`, `jekyll-sitemap`, `jekyll-feed` → drop; others report |
+| `search_*`, `heading_anchors`, `nav_sort`, `mermaid`, `markdown`, `kramdown`, `highlighter`, `sass`, `exclude`, `include` | drop                                                                                                         |
+
+References: https://jekyllrb.com/docs/configuration/ and https://just-the-docs.com/docs/configuration/
+
+## Navigation
+
+- JTD (https://just-the-docs.com/docs/navigation/): every page with a `title` and without `nav_exclude: true` is in the sidebar. Top level has no `parent`; children set `parent: <parent title>`, with `grand_parent` or `ancestor` to disambiguate. Order within a level: `nav_order` (numbers before strings), else title. A page with children → group with that page as `root`. Excluded parents exclude their children.
+- JTD collections: `just_the_docs.collections.<name>.name` → one group per collection after the normal pages; `nav_fold: true` → `expanded: false`; `nav_exclude` drops the collection.
+- Other themes: a `_data/*.yml` nav file (shape defined by the `_includes/` template that loops over it; usually `title`/`url`/`children`). Resolve each `url` to its source file.
+- JTD shows front matter `title` in the sidebar and the body H1 on the page.
+
+## Content conversion
+
+| Jekyll / Kramdown / JTD                                                                                                               | Mintlify                                                                                |
+| ------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
+| `{{ site.x }}`, `{{ page.x }}`, `{% if %}`, `{% for %}`, `{% assign %}`, `{% capture %}`, `{% raw %}`                                 | (`mint migrate --topic conversion`, Template tags)                                      |
+| `{{ site.baseurl }}`, `relative_url`, `absolute_url`                                                                                  | root-relative path                                                                      |
+| `{% link path/file.md %}`, `{% post_url slug %}`                                                                                      | that page's new path                                                                    |
+| `{% include x.md k="v" %}` (from `_includes/`), `{% include_relative x.md %}`; `{{ include.k }}` reads params                         | (`mint migrate --topic conversion`, Reusable content)                                   |
+| HTML includes (note, figure, video, details)                                                                                          | the matching component; report others                                                   |
+| `{% highlight lang linenos mark_lines="1 2" %}`                                                                                       | fence with `lines` and `highlight={1,2}`                                                |
+| JTD callout IAL `{: .name }` before a paragraph or blockquote; `{: .name-title }` with a `> Title` first line                         | callout chosen by the meaning of `name` in `callouts:`; undeclared names rendered plain |
+| `{: .label }` / `{: .label .label-green }`                                                                                            | `<Badge>`                                                                               |
+| `{: .btn }` links                                                                                                                     | link or `<Card>`                                                                        |
+| `{: #id }` under a heading, `## Heading {#id}`                                                                                        | (`mint migrate --topic conversion`, Heading IDs)                                        |
+| `{: .no_toc }`, `{: .text-delta }`, in-page TOC (`{:toc}`), `{::options}`, ALDs                                                       | delete                                                                                  |
+| `{::comment}`                                                                                                                         | MDX comment                                                                             |
+| `nav_exclude: true`                                                                                                                   | leave out of navigation                                                                 |
+| `search_exclude: true`                                                                                                                | `searchable: false`                                                                     |
+| `last_modified_date`                                                                                                                  | `lastUpdatedDate`                                                                       |
+| `redirect_from` / `redirect_to`                                                                                                       | URLs below                                                                              |
+| `layout`, `nav_order`, `parent`, `grand_parent`, `ancestor`, `has_children`, `has_toc`, `nav_fold`, `published`, `categories`, `tags` | drop                                                                                    |
+
+References: https://jekyllrb.com/docs/liquid/tags/ and https://just-the-docs.com/docs/ui-components/callouts/
+
+## Assets
+
+- Copy `assets/`, `images/` and other referenced files outside `_` folders at the same paths.
+- Skip `_sass/`, `_layouts/`, theme CSS and `vendor/`. Report `_sass/custom` rules that hide or inject content.
+
+## URLs and redirects
+
+- Global `permalink` sets page URLs (https://jekyllrb.com/docs/permalinks/): unset (`date`), `none` or `ordinal` → `dir/name.md` serves `/dir/name.html` (`mint migrate --topic navigation`, Redirects); `pretty` → `/dir/name/`; custom patterns end in `/` or `:output_ext`. `dir/index.md` → `/dir/`.
+- Front matter `permalink` overrides per page; collections use `collections.<name>.permalink`, default `/:collection/:path` plus the global style's suffix.
+- `redirect_from` values → one redirect each to this page. `redirect_to` → a redirect from this page's path; the page itself goes.
+- Posts default to `/:categories/:year/:month/:day/:title.html`.
+- `jekyll-readme-index` (on GitHub Pages builds) serves `README.md` as its folder (`mint migrate --topic conversion`, Files).
+- A `CNAME` file means the site served at that domain's root, whatever `baseurl` says.
+
+## Known gaps
+
+- Liquid logic replaced with static output (`mint migrate --topic conversion`, Template tags).
+- Posts index, pagination, categories, tags, RSS.
+- Custom `_layouts/` and `_includes/` chrome with no docs.json field.
+- JTD callout colors, label colors, `nav_fold`, auto child-page lists on parent pages, edit-time format.
+- Kramdown abbreviations, definition lists, math engine options.
+- GitHub Pages-only plugins (`jekyll-gist`, `jemoji`, `jekyll-mentions`).
+- Heading anchors (`mint migrate --topic conversion`, Heading IDs).

package/migrate/sources/mdbook.md

@@ -0,0 +1,98 @@
+# mdBook
+
+## Detect
+
+- `book.toml` with a `[book]` table. Only mdBook uses it, so it wins over every other signal.
+- `SUMMARY.md` in the source dir (`[book] src`, default `src/`). GitBook and HonKit also use `SUMMARY.md`, but with `book.json` or `.gitbook.yaml` and no `book.toml`.
+- `mdbook build`, `mdbook test` or `cargo install mdbook-<plugin>` in CI.
+
+## Get the source
+
+### From the repo
+
+- Chapters live under `[book] src`, which can point outside the book root. Only chapters listed in `SUMMARY.md` publish; every non-Markdown file under `src` is copied to the site.
+- Build: `mdbook build -d <dir>` (`mint migrate --topic discovery`, From the repo).
+
+### From an export
+
+None; the book is built from the repo.
+
+### From the live site
+
+The rendered sidebar gives chapters, order and part titles; `print.html` holds every chapter. Sources come from `git-repository-url` or `edit-url-template`.
+
+## Config → docs.json
+
+| book.toml                                                                                                                                                                                                                                                           | docs.json                                                                              |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
+| `[book] title` / `description`                                                                                                                                                                                                                                      | `name` / `description`                                                                 |
+| `[book] logo` (relative to `src`)                                                                                                                                                                                                                                   | `logo`                                                                                 |
+| `[output.html] git-repository-url`                                                                                                                                                                                                                                  | `navbar.links` (`type: github` for GitHub)                                             |
+| `default-theme` and `preferred-dark-theme` both dark (`coal`, `navy`, `ayu`)                                                                                                                                                                                        | `appearance.default: "dark"`                                                           |
+| `additional-css` / `additional-js`                                                                                                                                                                                                                                  | (`mint migrate --topic navigation`, Chrome); also delete admonish assets               |
+| `google-analytics`                                                                                                                                                                                                                                                  | `integrations.ga4.measurementId`                                                       |
+| `[output.html.redirect]`                                                                                                                                                                                                                                            | `redirects` (URLs below)                                                               |
+| `[output.html.fold] enable = false`                                                                                                                                                                                                                                 | nested groups `expanded: true`                                                         |
+| `site-url`, `cname`                                                                                                                                                                                                                                                 | none; their host and path are part of every old URL                                    |
+| `theme/` folder                                                                                                                                                                                                                                                     | report custom templates; a custom favicon → `favicon` (the stock one is mdBook's logo) |
+| `authors`, `language`, `edit-url-template`, `mathjax-support`, `input-404`, `no-section-label`, `smart-punctuation`, `[output.html.playground]`, `[output.html.code.hidelines]`, `[output.html.search]`, `[output.html.print]`, `[rust]`, `[build]`, other backends | drop and report                                                                        |
+
+Reference: https://rust-lang.github.io/mdBook/format/configuration/
+
+## Navigation
+
+`SUMMARY.md` is the whole navigation (https://rust-lang.github.io/mdBook/format/summary.html):
+
+- `# Summary` on the first line is ignored.
+- Prefix chapters (bare links before the first list) and suffix chapters (bare links after the last list) are unnested pages before and after the numbered chapters.
+- Part titles (`# Part`, h1 only) → one group per part.
+- Numbered chapters (`-` or `*` items, nested by indentation) → pages; a chapter with children → group with that chapter as `root`.
+- Draft chapters `[Title]()` have no file: report as planned chapters.
+- Separators (`---`): drop.
+- The sidebar label is the `SUMMARY.md` link text; the page heading is the chapter's H1.
+- mdBook numbers chapters (`1.`, `2.3.`) unless `no-section-label`. Report prose that cites chapter numbers.
+
+## Content conversion
+
+| mdBook                                                                                                                                                                                                   | Mintlify                                                                                                              |
+| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| `{{#include file}}` and `file:2`, `file::10`, `file:2:`, `file:2:10`, `file:anchor` (`ANCHOR:` / `ANCHOR_END:` markers). Paths are relative to the chapter; expanded as text, so they work inside fences | code: (`mint migrate --topic conversion`, Code imports); prose: (`mint migrate --topic conversion`, Reusable content) |
+| `{{#rustdoc_include file:sel}}`                                                                                                                                                                          | the selected lines only; report the lost expand toggle                                                                |
+| `{{#playground file}}`                                                                                                                                                                                   | a static `rust` fence; report the lost Run button                                                                     |
+| `{{#title X}}`                                                                                                                                                                                           | `title`                                                                                                               |
+| `\{{#...}}` (escaped, in docs about mdBook)                                                                                                                                                              | literal text in inline code or a fence                                                                                |
+| Rust fence attributes (`rust,ignore`, `no_run`, `should_panic`, `compile_fail`, `editable`, `noplayground`, `mdbook-runnable`, `edition20xx`)                                                            | `rust`                                                                                                                |
+| hidden lines in Rust fences: first non-space characters `# ` or a lone `#`; `##` is an escaped `#`; `#[` and `#!` are code                                                                               | delete hidden lines                                                                                                   |
+| custom hide prefixes (`[output.html.code.hidelines]`, fence `hidelines=<prefix>`)                                                                                                                        | delete those lines too                                                                                                |
+| `> [!NOTE]` style alerts                                                                                                                                                                                 | (`mint migrate --topic conversion`, GitHub alerts)                                                                    |
+| mdbook-admonish ` ```admonish type ` (`title="..."`, `collapsible=true`); aliases per https://tommilligan.github.io/mdbook-admonish/reference.html                                                       | (`mint migrate --topic conversion`, Admonitions); collapsible → `<Accordion>`                                         |
+| mdbook-tabs `{{#tabs}}` / `{{#tab name="X"}}`                                                                                                                                                            | `<Tabs>` / `<Tab>`                                                                                                    |
+| MathJax `\\( \\)`, `\\[ \\]`                                                                                                                                                                             | `$ $`, `$$ $$`, with Markdown escapes inside the math undone                                                          |
+| mdbook-toc `<!-- toc -->`                                                                                                                                                                                | delete                                                                                                                |
+| `## Heading { #id .class }`                                                                                                                                                                              | (`mint migrate --topic conversion`, Heading IDs); drop classes                                                        |
+| definition lists (`term` then `: definition`)                                                                                                                                                            | a list or table                                                                                                       |
+| `<i class="fa fa-x">`                                                                                                                                                                                    | `<Icon>`                                                                                                              |
+| elements with `class="hidden"`                                                                                                                                                                           | delete                                                                                                                |
+
+Reference: https://rust-lang.github.io/mdBook/format/mdbook.html
+
+## Assets
+
+- Non-Markdown files under `src` that chapters reference keep their paths.
+- Files included from outside `src` are code, not assets.
+
+## URLs and redirects
+
+- `src/a/b.md` → `/a/b.html` (`mint migrate --topic navigation`, Redirects).
+- The built-in `index` preprocessor turns `README.md` chapters into `index.html` (`mint migrate --topic conversion`, Files).
+- The first chapter is also written as the book's `/index.html`.
+- `[output.html.redirect]` keys are absolute old paths; values are relative or absolute targets. Fragment keys (`/page.html#frag`) cannot be redirect sources: report them.
+
+## Known gaps
+
+- Rust playground, `editable` code, `mdbook test` doctests.
+- The hidden-line toggle and `rustdoc_include` expansion.
+- Chapter numbering, draft chapters, separators.
+- Print page, EPUB and PDF backends.
+- Custom preprocessors, cmdrun, i18n-helpers (`po/`), graphviz/plantuml/svgbob diagrams.
+- Fragment redirects; heading anchors (`mint migrate --topic conversion`, Heading IDs).

package/migrate/sources/mkdocs.md

@@ -0,0 +1,113 @@
+# MkDocs
+
+Covers MkDocs, Material for MkDocs, Zensical and ProperDocs.
+
+## Detect
+
+- `mkdocs.yml` / `mkdocs.yaml`: MkDocs. `theme.name: material` means Material for MkDocs.
+- `zensical.toml`: Zensical (MkDocs keys in TOML under `[project]`). `properdocs.yml`: ProperDocs. Both also read `mkdocs.yml`.
+- Python dependencies (`mkdocs`, `mkdocs-material`, `zensical`, `properdocs`) or `mkdocs build` in CI confirm it.
+- The config file wins. If there are several, migrate the one CI builds and report the others.
+- Resolve `INHERIT:` (deep-merges a parent config) and `!ENV [VAR, default]` (use the default, report the variable) before mapping. Read `!!python/...` tags as text.
+
+## Get the source
+
+### From the repo
+
+- Pages are the `.md` files under `docs_dir` (default `docs/`), minus `exclude_docs`.
+- Build: `mkdocs build -d <dir>` or `zensical build` (`mint migrate --topic discovery`, From the repo).
+
+### From an export
+
+None; the site is built from the repo.
+
+### From the live site
+
+Page sources through `repo_url` + `edit_uri`.
+
+## Config → docs.json
+
+| mkdocs.yml                                                                                                           | docs.json                                                                                      |
+| -------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| `site_name` / `site_description`                                                                                     | `name` / `description`                                                                         |
+| `repo_url`                                                                                                           | `navbar.links` (`type: github` for GitHub)                                                     |
+| `theme.logo` / `theme.favicon`                                                                                       | `logo` / `favicon`                                                                             |
+| `theme.palette.primary`                                                                                              | `colors.primary`, from the rendered link color's hex (Material color names are not CSS colors) |
+| `theme.palette` with only `scheme: slate`                                                                            | `appearance.default: "dark"`                                                                   |
+| `theme.font.text`                                                                                                    | `fonts.family`                                                                                 |
+| `extra.social`                                                                                                       | `footer.socials`                                                                               |
+| `extra.analytics` (`provider: google`)                                                                               | `integrations.ga4.measurementId`                                                               |
+| `extra.*` read by the macros plugin                                                                                  | `variables` (`mint migrate --topic conversion`, Template tags)                                 |
+| `extra_css` / `extra_javascript`                                                                                     | (`mint migrate --topic navigation`, Chrome)                                                    |
+| `nav`                                                                                                                | Navigation below                                                                               |
+| `site_url`                                                                                                           | none; its host and path prefix are part of every old URL                                       |
+| `copyright`, `edit_uri`, `theme.features`, `markdown_extensions`, `hooks`, `theme.custom_dir`, build and server keys | drop and report                                                                                |
+
+Plugins: `redirects` → URLs below; `git-revision-date*` → `metadata.timestamp`; `awesome-pages`, `awesome-nav`, `literate-nav` → Navigation; `search`, `social`, `minify`, `privacy`, `offline` → drop; `macros`, `mkdocstrings`, `gen-files`, `mkdocs-jupyter`, `blog`, `i18n`, `mike` → Known gaps.
+
+Reference: https://www.mkdocs.org/user-guide/configuration/
+
+## Navigation
+
+- `nav` entries: `- Label: page.md`, `- page.md` (label from the page), `- Label: https://...` (external), `- Section: [ ... ]` (nested).
+- Material `theme.features: navigation.tabs`: each top-level section is a tab. Without it, top-level sections are groups.
+- Material `navigation.indexes`: a section's leading `index.md` is the section's own page → group `root`.
+- External `nav` entries → `navigation.global.anchors`, or a tab `href` if they sat in the tab row.
+- No `nav`: MkDocs lists each folder's files alphabetically, `index` first, subfolders after files.
+- `.pages` (awesome-pages) and `.nav.yml` (awesome-nav) set per-folder title and order. A literate-nav `SUMMARY.md` is a nested link list read like `nav`; it is not a page.
+- `not_in_nav` pages are hidden pages.
+
+Reference: https://squidfunk.github.io/mkdocs-material/setup/setting-up-navigation/
+
+## Content conversion
+
+| MkDocs / Material / pymdownx                                                                               | Mintlify                                                                                                              |
+| ---------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| `!!! type "Title"` (body indented 4)                                                                       | (`mint migrate --topic conversion`, Admonitions)                                                                      |
+| `??? type "Title"` / `???+`                                                                                | `<Accordion>` / `<Accordion defaultOpen>`                                                                             |
+| `=== "Label"` runs (`===+` selects a tab, `===!` starts a new set)                                         | `<Tabs>` / `<Tab>`; `<CodeGroup>` when every tab is one code block                                                    |
+| `/// admonition`, `/// details`, `/// tab` blocks                                                          | same targets as `!!!`, `???`, `===`                                                                                   |
+| fence `title="x"`, `hl_lines="2 4-5"`, `linenums="1"`                                                      | fence title, `highlight={2,4-5}`, `lines`                                                                             |
+| inline `` `#!python code` ``                                                                               | plain inline code                                                                                                     |
+| code annotations (`# (1)!` + a numbered list)                                                              | the list as prose below the block; report                                                                             |
+| `--8<--` snippets (paths resolve from `base_path`, not the page; `file:3:10` ranges, `file:name` sections) | code: (`mint migrate --topic conversion`, Code imports); prose: (`mint migrate --topic conversion`, Reusable content) |
+| include-markdown `{% include "x.md" %}`                                                                    | (`mint migrate --topic conversion`, Reusable content)                                                                 |
+| `{ #id }` on a heading                                                                                     | (`mint migrate --topic conversion`, Heading IDs)                                                                      |
+| other attribute lists (`{ .md-button }`, `{ width=... }`)                                                  | delete; buttons become links or `<Card>`                                                                              |
+| `<div class="grid cards" markdown>`                                                                        | `<Columns>` of `<Card>`                                                                                               |
+| `++ctrl+c++`, `==x==`, `^^x^^`                                                                             | `<kbd>`, `<mark>`, `<ins>`                                                                                            |
+| `:material-x:`, `:octicons-x:`, `:fontawesome-x:`                                                          | `<Icon>`, or delete                                                                                                   |
+| arithmatex `\( \)`, `\[ \]`                                                                                | `$ $`, `$$ $$`                                                                                                        |
+| abbreviations `*[TERM]: ...`, `[TOC]`                                                                      | delete                                                                                                                |
+| `![](x.png#only-light)` / `#only-dark`                                                                     | light/dark image pair                                                                                                 |
+| macros `{{ }}` / `{% %}`                                                                                   | (`mint migrate --topic conversion`, Template tags)                                                                    |
+| `hide: [toc]` / `hide: [navigation]` / `hide: [footer]`                                                    | `mode: "wide"` / `mode: "center"` / `hideFooterPagination`                                                            |
+| `status: deprecated` / `status: new`                                                                       | `deprecated` / `tag`                                                                                                  |
+| `tags`, `search.exclude`                                                                                   | `keywords`, `searchable: false`                                                                                       |
+
+Folder `.meta.yml` files (meta plugin) set frontmatter for every page in the folder.
+
+References: https://squidfunk.github.io/mkdocs-material/reference/ and https://facelessuser.github.io/pymdown-extensions/
+
+## Assets
+
+- Referenced non-Markdown files under `docs_dir` keep their paths.
+- Files at the `docs_dir` root served by URL (`CNAME`, verification files): report.
+
+## URLs and redirects
+
+- `use_directory_urls: true` (default): `a/b.md` → `/a/b/`, `a/index.md` → `/a/`.
+- `use_directory_urls: false`: `a/b.md` → `/a/b.html` (`mint migrate --topic navigation`, Redirects).
+- `README.md` serves its folder when there is no `index.md` (`mint migrate --topic conversion`, Files).
+- `redirects` plugin `redirect_maps` (`old.md: new.md`): one redirect per entry, both sides as URLs.
+- mike serves versions at `/<version>/` and aliases such as `/latest/`. Redirect `/<alias>/:slug*` to the migrated version.
+
+## Known gaps
+
+- mkdocstrings, mkdocs-click, gen-files and Jupyter output.
+- macros logic (`mint migrate --topic conversion`, Template tags).
+- Blog plugin, tag index pages, RSS.
+- i18n plugins; mike versions other than the migrated one.
+- Code annotations, admonition colors, inline admonitions, cross-page linked tabs.
+- `hooks`, `theme.custom_dir` overrides, plugins without a mapping.
+- Heading anchors (`mint migrate --topic conversion`, Heading IDs).