Migrate from Docusaurus

Docusaurus content is already Markdown/MDX in git, so migration is mostly configuration translation — moving sidebars.js into syntext.json and swapping a few components.

Automatic Migration

cd your-docusaurus-site
stx migrate --from docusaurus --dry-run   # preview
stx migrate --from docusaurus             # convert admonitions, sidebar, config

The converter handles admonitions, sidebars.js, and frontmatter. Review anything it flags, then continue with the manual steps below.

What Maps Directly

Docusaurus	Syntext
`docs/*.md(x)`	`docs/*.mdx` — unchanged
`sidebars.js`	`navigation` in syntext.json
`docusaurus.config.js`	syntext.json
`:::note` / `:::tip` / `:::warning` admonitions	`<Note>` / `<Tip>` / `<Warning>`
```js title="file.js" code titles	Same syntax — supported
`<Tabs>` / `<TabItem>`	`<Tabs>` / `<Tab>`
Front matter `sidebar_position`	Order in `syntext.json` navigation
Versioned docs	Git branches + preview builds
Algolia DocSearch	Built-in full-text search — zero config

Migration Steps

In your existing repo:

stx init

Point it at your existing docs/ folder when prompted.

module.exports = {
docs: [
{
type: 'category',
label: 'Getting Started',
items: ['intro', 'installation'],
},
],
}

{
"navigation": [
{
"group": "Getting Started",
"pages": ["intro", "installation"]
}
]
}

type: 'autogenerated' sidebars have no direct equivalent — list pages explicitly (ordering becomes deterministic).

Replace Docusaurus admonition syntax with MDX components:

:::warning Heads up
This action is irreversible.
:::

<Warning>
**Heads up** — this action is irreversible.
</Warning>

A find-and-replace or codemod handles this; stx check flags any leftovers as compile errors.

@theme/* component imports → remove; use built-in components
useBaseUrl / @docusaurus/Link → plain relative links
<BrowserWindow> and other swizzled components → Cards or plain MDX

stx deploy

You can now delete docusaurus.config.js, the webpack customizations, and the hosting setup — Syntext builds and hosts the site. For CI-driven deploys see GitHub Actions.

What You Gain

No site infrastructure — no React version bumps, no build config, no hosting
Search included — no Algolia application process
AI assistant + analytics out of the box
API reference from code via annotations, not hand-maintained MDX

Keeping some custom React pages? Docusaurus src/pages/ custom pages don't migrate — recreate them as MDX, or keep a separate app for highly custom pages and link to it.