---
title: Migrate from Docusaurus
description: "Move your docs from Docusaurus to Syntext and stop maintaining a doc site build."
---

# 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

```bash
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](/configuration/navigation) |
| `docusaurus.config.js` | [syntext.json](/configuration/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

<Steps>
<Step title="Initialize Syntext">
In your existing repo:

```bash
stx init
```
Point it at your existing `docs/` folder when prompted.
</Step>

<Step title="Translate sidebars.js">
<CodeGroup>
```js sidebars.js (before)
module.exports = {
  docs: [
    {
      type: 'category',
      label: 'Getting Started',
      items: ['intro', 'installation'],
    },
  ],
}
```

```json syntext.json (after)
{
  "navigation": [
    {
      "group": "Getting Started",
      "pages": ["intro", "installation"]
    }
  ]
}
```
</CodeGroup>

`type: 'autogenerated'` sidebars have no direct equivalent — list pages explicitly (ordering becomes deterministic).
</Step>

<Step title="Convert admonitions">
Replace Docusaurus admonition syntax with MDX components:

<CodeGroup>
```md Before
:::warning Heads up
This action is irreversible.
:::
```

```mdx After
<Warning>
**Heads up** — this action is irreversible.
</Warning>
```
</CodeGroup>

A find-and-replace or codemod handles this; `stx check` flags any leftovers as compile errors.
</Step>

<Step title="Replace Docusaurus-specific imports">
- `@theme/*` component imports → remove; use built-in [components](/components/overview)
- `useBaseUrl` / `@docusaurus/Link` → plain relative links
- `<BrowserWindow>` and other swizzled components → [Cards](/components/cards) or plain MDX
</Step>

<Step title="Deploy and delete your build pipeline">
```bash
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](/deployment/github-actions).
</Step>
</Steps>

## 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](/concepts/annotations), not hand-maintained MDX

<Note>
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.
</Note>