# Docusaurus

React static site generator. Content is MD/MDX under the docs plugin's `path`; navigation is executable JS/TS (`sidebars.js`) plus `_category_.json`/`.yml` files and doc front matter.

## Detect

- `docusaurus.config.{js,mjs,ts}` at the site root, `@docusaurus/core` in `package.json`.
- `sidebars.{js,ts}`, `_category_.json`/`_category_.yml` in content folders, `static/`, `versioned_docs/`, `versions.json`, `i18n/`.
- Live site: `<meta name="generator" content="Docusaurus ...">`, `__docusaurus` in the HTML, `/assets/js/runtime~main.*.js`.
- Config file wins over everything else. Read the `@docusaurus/core` major from `package.json`: v2 (MDX 1) and v3 (MDX 3) need different content fixes (below).

## Get the source

Mintlify's guide for this platform: https://www.mintlify.com/docs/migration/docusaurus.md

### From the repo

- Read `docusaurus.config.*` first: every `@docusaurus/plugin-content-docs` instance (preset `docs` or `plugins` with an `id`) has its own `path` (default `docs`), `routeBasePath`, `sidebarPath`, `include`/`exclude`. Each instance is a separate docs tree.
- Also inventory `src/pages/**/*.md(x)` (standalone pages) and `blog/` if the user wants them; `src/pages/*.tsx` React pages have no source to convert: report them.
- Versions: `versioned_docs/version-<name>/` with `versioned_sidebars/version-<name>-sidebars.json`; order in `versions.json` (newest first). `docs/` is the `current` version.
- Locales: `i18n/<locale>/docusaurus-plugin-content-docs/current/` (and `.../version-<name>/` for versions), sidebar/category label translations in `i18n/<locale>/docusaurus-plugin-content-docs/current.json`.
- Files prefixed with `_` are partials (not pages). `draft: true` docs are not published: exclude them.

### From an export

None; the site is built from the repo.

### From the live site

Scrape with `npx -p @mintlify/scraping@latest -p puppeteer mintlify-scrape section <url>` (add `--filter=/docs` for a `routeBasePath`), then fix port artifacts E (`prism-code` fences) and F (admonition leaked into `description`) (`mint migrate --topic conversion`, Port artifacts).

## Config → docs.json

| Docusaurus                                                                  | docs.json                                                                        |
| --------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| `title`                                                                     | `name`                                                                           |
| `tagline`                                                                   | `description`                                                                    |
| `favicon` (path in `static/`)                                               | `favicon`                                                                        |
| `themeConfig.navbar.logo` `src` / `srcDark` / `href`                        | `logo.light` / `logo.dark` / `logo.href`                                         |
| `themeConfig.navbar.items` of type `doc`, `docSidebar`                      | `navigation.tabs` (one per sidebar)                                              |
| `themeConfig.navbar.items` with `href` (external)                           | `navbar.links` (GitHub link: `type: "github"`)                                   |
| `themeConfig.navbar.items` `docsVersionDropdown`, `localeDropdown`          | drop: replaced by `navigation.versions` / `navigation.languages` switchers       |
| `themeConfig.navbar.items` `search`, `html`, custom types                   | drop and report                                                                  |
| `themeConfig.footer.links` (columns)                                        | `footer.links` (`title` → `header`, `items[].to`/`href` → `href`)                |
| `themeConfig.footer.copyright`, `footer.logo`, `footer.style`               | drop and report                                                                  |
| `themeConfig.colorMode.defaultMode` / `disableSwitch`                       | `appearance.default` / `appearance.strict`                                       |
| `themeConfig.prism.theme` / `darkTheme`                                     | `styling.codeblocks` only if a matching Shiki theme exists; else drop and report |
| `themeConfig.announcementBar` `content` / `isCloseable`                     | `banner.content` (HTML → Markdown links) / `banner.dismissible`; colors drop     |
| `themeConfig.metadata`, `themeConfig.image`                                 | `seo.metatags` (`image` → `"og:image"`)                                          |
| `themeConfig.algolia`                                                       | drop and report                                                                  |
| `i18n.locales` / `defaultLocale`                                            | `navigation.languages` (use a supported code)                                    |
| preset `gtag.trackingID`                                                    | `integrations.ga4.measurementId`                                                 |
| preset `googleTagManager.containerId`                                       | `integrations.gtm.tagId`                                                         |
| `@docusaurus/plugin-client-redirects` `redirects`                           | `redirects` (see URLs)                                                           |
| `@docusaurus/theme-mermaid`, `remark-math` + `rehype-katex`                 | drop (native in Mintlify); keep the fences and `$` math                          |
| `url`, `baseUrl`, `trailingSlash`                                           | drop; use them to compute old URLs                                               |
| `docs.editUrl`, `showLastUpdateTime`, `showLastUpdateAuthor`, `breadcrumbs` | drop and report                                                                  |
| `theme.customCss`, swizzled `src/theme/*`                                   | drop and report                                                                  |
| OpenAPI plugins (`docusaurus-plugin-openapi-docs`, `redocusaurus`)          | spec file; see `mint migrate --topic api`                                        |

## Navigation

- Resolve the sidebar, do not parse it as text: run `node -e "console.log(JSON.stringify(require('./sidebars.js'),null,2))"` (for TS or ESM, import it with `npx tsx`). If `sidebarPath` is unset, the whole sidebar is autogenerated from the docs folder.
- One sidebar object key = one tab (or one group if there is only one sidebar). Keep item order, labels and nesting.
- Item mapping:
  - doc id string or `{type: 'doc', id, label}` → page path (`label` differing from the H1 → `sidebarTitle`).
  - `{type: 'category', label, items}` → nested group with `group: label`.
  - category `link: {type: 'doc', id}` → that doc is the group `root`.
  - category `link: {type: 'generated-index', title, description, slug}` → create an index page from those fields (cards for the children) and make it the `root`; its old URL is `/<routeBasePath>/category/<category name>` (slugified) unless `slug` is set.
  - `{type: 'link', href, label}` → a page whose frontmatter is `title: label` + `url: href`, listed at that position; `{type: 'html'}` → drop and report; `{type: 'ref'}` → page path.
  - `collapsed: false` on a nested category → `expanded: true`.
- Doc ids: default id is the file path without extension and number prefixes; front matter `id` replaces only the last segment. Map ids to files before mapping the sidebar.
- `{type: 'autogenerated', dirName}`: expand it the way Docusaurus does. Order within a folder: `sidebar_position` (docs) and `_category_` `position` (folders) ascending, then alphabetical by file/folder name. Number prefixes (`01-intro.md`) order items and are stripped from ids, labels and URLs. Folder label: `_category_` `label`, else folder name. A folder's `index.md`, `README.md` or `<folder>/<folder>.md` is the category's linked doc (group `root`), unless `_category_` sets `link` (`mint migrate --topic conversion`, Files).
- Labels: `sidebar_label` → `sidebarTitle`. `_category_` `className`, `customProps`, `collapsible` → drop.
- Cross-check the result against the rendered sidebar on the live site; custom `sidebarItemsGenerator` functions change all of the above.
- Versions: one `navigation.versions` entry per kept version, built from `versioned_sidebars/`; make the `lastVersion` (default: first in `versions.json`) the default. Keep version content in per-version folders.
- Doc front matter `displayed_sidebar`, `pagination_*` → drop.

## Content conversion

Admonitions: (`mint migrate --topic conversion`, Admonitions). Docusaurus-specific mapping:

| Docusaurus                                                          | Mintlify                                                                                              |
| ------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| `:::warning`                                                        | `<Warning>` (v2: rendered red, use `<Danger>` if the text warns of damage)                            |
| Admonition title (v3 `:::note[Title]`, v2 `:::note Title`)          | (`mint migrate --topic conversion`, Components)                                                       |
| `<Admonition type="...">` from `@theme/Admonition`                  | same mapping as the directive                                                                         |
| `<Tabs>` + `<TabItem value label default>`                          | `<Tabs>` + `<Tab title={label}>` (no `label` → `value`); `default`/`defaultValue` → `defaultTabIndex` |
| `groupId`, `queryString`, `lazy`, `values={[...]}`                  | drop (titles in `values` become `Tab` titles)                                                         |
| Tabs whose every item is one code block                             | `<CodeGroup>` with the label as the fence title                                                       |
| ` ```js title="a.js" `                                              | ` ```js a.js ` or keep `title="a.js"`                                                                 |
| ` ```js {1,4-6} `                                                   | `highlight={1,4-6}`                                                                                   |
| `// highlight-next-line`, `// highlight-start` / `// highlight-end` | remove the comment lines; put the resulting line numbers in `highlight={...}`                         |
| `showLineNumbers` (`=N` start offset)                               | `lines` (offset drops)                                                                                |
| ` ```bash npm2yarn `                                                | (`mint migrate --topic conversion`, Package-manager tabs)                                             |
| ` ```jsx live ` (theme-live-codeblock)                              | static code block; report                                                                             |
| `<CodeBlock language title>` from `@theme/CodeBlock`                | fenced block                                                                                          |
| `import X from './_x.mdx'` + `<X />` (partial)                      | (`mint migrate --topic conversion`, Reusable content)                                                 |
| `import Code from './file.js' with {type: 'text'}`                  | (`mint migrate --topic conversion`, Code imports)                                                     |
| `<details><summary>T</summary>`                                     | `<Accordion title="T">`                                                                               |
| `<DocCardList />`                                                   | `<Card>` per child page in a `<Columns cols={2}>`                                                     |
| `<TOCInline toc={toc} />`                                           | drop and report                                                                                       |
| `@site/src/components/*`                                            | (`mint migrate --topic conversion`, Components)                                                       |
| `useBaseUrl(...)`, `useDocusaurusContext`, `@docusaurus/*` imports  | resolve to a literal value; drop the import                                                           |
| `@theme/*` imports                                                  | delete after converting the component                                                                 |
| `<!-- truncate -->` / `{/* truncate */}` (blog)                     | delete                                                                                                |

Heading ids: v3 `## Title {/* #id */}` and v2/`mdx1Compat` `## Title {#id}` (`mint migrate --topic conversion`, Heading IDs).

Front matter: `id` → drop (used for URLs, see below); `slug` → drop (used for URLs); `title`, `keywords` keep; `sidebar_label` → `sidebarTitle`; `unlisted: true` → `hidden: true`; `image` → `"og:image"`; `hide_title`, `hide_table_of_contents`, `toc_*_heading_level`, `sidebar_position`, `sidebar_class_name`, `sidebar_custom_props`, `sidebar_key`, `custom_edit_url`, `last_update`, `parse_number_prefixes`, `tags` → drop. `description` is meta-only and defaults to the first line of content (`mint migrate --topic conversion`, Frontmatter).

MDX version: v2 sources are MDX 1 and often contain `<!-- -->` comments, unescaped `{`/`<`, string `style` attributes (`mint migrate --topic conversion`, MDX safety). v3 with `markdown.format: 'detect'` treats `.md` as CommonMark.

## Assets

- `static/` and every `staticDirectories` entry are served at the site root: `static/img/a.png` → `/img/a.png` (`mint migrate --topic conversion`, Images and files).
- `@site/static/img/a.png` in imports or `require()` → `/img/a.png`.
- Co-located images (`./assets/a.png`, `require('./a.png')`, `import img from './a.png'`) → move under a root folder and rewrite to root-relative paths.
- `pathname:///img/a.png` → `/img/a.png`.
- GitHub-style themed images (`#gh-light-mode-only` / `#gh-dark-mode-only`) and `@theme/ThemedImage` → two `<img>` tags with `className="block dark:hidden"` / `"hidden dark:block"`.
- `@docusaurus/plugin-ideal-image` `<Image img={require(...)}/>` → `<img>`.

## URLs and redirects

- Doc URL = `baseUrl` + `routeBasePath` (default `docs`; `/` means docs-only) + version path + slug. Locale prefix `/<locale>/` comes before everything for non-default locales.
- Slug: front matter `slug` (absolute `/x` from `routeBasePath`, relative `x` from the doc's folder); else the doc id path with number prefixes removed; `index`, `README` and `<folder>/<folder>` files resolve to the folder URL.
- Versions: `lastVersion` serves at `/<routeBasePath>/`, `current` at `/<routeBasePath>/next/` (unless `lastVersion: 'current'`), others at `/<routeBasePath>/<version>/`; `versions.<name>.path` overrides.
- `trailingSlash: true` → URLs end in `/`; `false` → files emitted as `/docs/page.html`, so hosts may also serve the `.html` form.
- Emit redirects (`mint migrate --topic navigation`, Redirects) for: the `routeBasePath` prefix if you move docs to root, every slug/id-based URL that differs from the new file path, `/category/<slug>` generated-index pages, version and locale prefixes, and every existing `plugin-client-redirects` entry (`from` array → one entry each, `to` → `destination`). `createRedirects` functions and `fromExtensions`/`toExtensions`: expand to exact entries from the sitemap.
- Tags pages (`/<routeBasePath>/tags/...`) have no target: redirect to the closest page or report.

## Known gaps

Report each that the site uses:

- Swizzled theme components, `src/theme/*`, custom CSS (Infima classes do not exist in Mintlify).
- React pages in `src/pages/*.tsx`, interactive components without a static equivalent, `react-live` blocks.
- Doc tags and tag index pages, `<TOCInline>`, per-page TOC heading levels.
- Edit URLs, last-updated author/time, breadcrumbs toggle, pagination overrides.
- Tab `groupId` persistence and `queryString` deep links.
- Docusaurus blog (author pages, tag/archive pages, RSS): see `mint migrate --topic changelog` if it is a changelog.
- Algolia DocSearch config and any search plugin.
- Docs plugin instances beyond what tabs/products can hold, `onlyIncludeVersions` subsets.
