Migrate from Docusaurus | NookDocs

Docusaurus → NookDocs runs from the same CLI. The migrator reads your docusaurus.config.js and sidebars.js, walks every .md/.mdx under docs/, converts Docusaurus admonitions to NookDocs callout components, copies static/ to public/, and writes a flat NookDocs repo.

npx nookdocs migrate ./my-docusaurus-site -o ./nookdocs-output

The migrator writes the flat layout — content .mdx lands at the output root (no docs/ subfolder), nookdocs.config.json sits alongside it with contentRoot: "/", and navigation page refs carry no docs/ prefix. See Content root.

TypeScript configs can't be executed by the CLI. If your project uses docusaurus.config.ts or sidebars.ts, the migrator reads what it can heuristically (the site title) and flags the rest — you'll finish the config and navigation by hand. A JavaScript docusaurus.config.js / sidebars.js converts fully. This is because the CLI is plain Node with no transpiler.

What converts automatically

Config (`docusaurus.config.js` → `nookdocs.config.json`)

Docusaurus	NookDocs	Notes
`title`	`name`	Direct copy
`--ifm-color-primary` (in `src/css/custom.css`)	`colors.primary`	Read from your theme CSS
`themeConfig.navbar.logo` (`src` / `srcDark`)	`colors.logo.light` / `.dark`	`href` set to `/`
`themeConfig.navbar.items` (external / `to` links)	`navbar.links`	`{label, href}`
(spec present) `openapi.json`	`api.openapi` + `api.playground`	Copied to `api-reference/openapi.json`
always emitted	`contentRoot: "/"`, `theme: "larch"`, `$schema`	Canonical layout

Docusaurus footer.links columns and plugins don't map 1:1 — they're listed under Manual review needed so you can re-add the equivalent NookDocs features (search, analytics, OpenAPI) in nookdocs.config.json.

Sidebar (`sidebars.js` → `navigation`)

Each sidebar becomes a tab; each category becomes a group; each doc id becomes a page ref (with any docs/ prefix stripped to match the flat layout). Nested categories are kept as nested groups.

Autogenerated sidebars ({ type: 'autogenerated' }) have no explicit structure for the migrator to read. It builds groups from your manual entries only and flags the rest — you'll list the remaining pages in the navigation array, or organize them by folder. NookDocs navigation is always explicit.

Admonitions (`:::` blocks → components)

Docusaurus admonitions convert to the matching NookDocs callout component. Optional titles (:::note[Title]) become the component's title prop.

Docusaurus	NookDocs
`:::note`	`<Note>`
`:::tip`	`<Tip>`
`:::info`	`<Info>`
`:::warning`	`<Warning>`
`:::caution`	`<Warning>` — no NookDocs Caution; flagged
`:::danger`	`<Warning>` — no NookDocs Danger; flagged

Components & frontmatter

<Tabs> passes through; <TabItem label="…"> becomes <Tab title="…">.
import … from '@theme/…' / '@site/…' / '@docusaurus/…' lines are stripped (they don't resolve in NookDocs) and flagged — verify the affected components use the NookDocs equivalents.
Frontmatter: sidebar_label → sidebarTitle; id and sidebar_position are dropped (NookDocs keys pages by file path, and order lives in the navigation array).

Assets

The whole static/ tree copies to public/, so a Docusaurus reference like /img/logo.svg (served from static/img/logo.svg) keeps resolving at public/img/logo.svg.

After migrating

Read the report. The Transforms applied section lists what was rewritten; Manual review needed lists everything to eyeball (autogenerated sidebars, TS configs, caution/danger tone, stripped imports, dropped plugins/footer).
Finish the navigation if your sidebar was autogenerated or TypeScript.
Commit the output to a repo and connect it — see the quickstart.

Known limitations

TypeScript configs (.ts) are read heuristically only — finish config + navigation by hand.
Plugins don't migrate — NookDocs ships search, OpenAPI, and analytics as first-class config, so re-enable the equivalents in nookdocs.config.json.
Custom React components / swizzled theme — anything importing @theme/@site is stripped; refactor to the NookDocs component library.

Overview — what the CLI does
Migrate command — flags, detection, report output
Migrating from Mintlify — the other fully-supported platform

What converts automatically

Config (docusaurus.config.js → nookdocs.config.json)

Sidebar (sidebars.js → navigation)

Admonitions (::: blocks → components)