/Docs
Search docs or ask a question⌘K
DocsAgent
Changelog
Guides Migrations Migrate from Docusaurus

Migrate from Docusaurus

Move your docs from Docusaurus to Syntext and stop maintaining a doc site build.

2 min read

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 # copy pages, first-pass conversion

The converter copies your pages into docs/, turns :::note admonitions into blockquotes (> NOTE: …), removes @theme and @docusaurus imports, turns <Tabs>/<TabItem> into MDX comments, and writes a syntext.json with your site title. It does not convert sidebars.js — add navigation by hand (step 2), and replace the generated theme object with a preset. See stx migrate --from. Review anything it flags, then continue with the manual steps below.

What Maps Directly

DocusaurusSyntext
docs/*.md(x)docs/*.mdx — unchanged
sidebars.jsnavigation in syntext.json
docusaurus.config.jssyntext.json
:::note / :::tip / :::warning admonitions<Note> / <Tip> / <Warning> (by hand — see step 3)
```js title="file.js" code titlesSame syntax — supported
<Tabs> / <TabItem><Tabs> / <Tab> (by hand)
Front matter sidebar_positionOrder in syntext.json navigation
Versioned docsVersioning — one version per branch or tag (Pro)
Algolia DocSearchBuilt-in full-text search — zero config

Migration Steps

  1. 01Step 1 of 51 ›Step 11.
    Initialize Syntext

    In a new, empty folder:

    bash
    stx init my-docs --preset workbench

    Then copy your docs/ pages in. stx init writes docs/index.mdx, so keep the one you want.

  2. 02Step 2 of 52 ›Step 22.
    Translate sidebars.js
    sidebars.js (before)syntext.json (after)
    module.exports = {
    docs: [
    {
    type: 'category',
    label: 'Getting Started',
    items: ['intro', 'installation'],
    },
    ],
    }

    type: 'autogenerated' sidebars: leave navigation out and the folder structure becomes the sidebar (see Navigation), or list pages explicitly.

  3. 03Step 3 of 53 ›Step 33.
    Convert admonitions

    Replace Docusaurus admonition syntax with MDX components:

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

    A find-and-replace or codemod handles this. If you ran stx migrate --from docusaurus, look for the > NOTE:-style blockquotes it wrote.

  4. 04Step 4 of 54 ›Step 44.
    Replace Docusaurus-specific imports
    •
    @theme/* component imports → remove; use built-in components
    •
    useBaseUrl / @docusaurus/Link → plain relative links
    •
    <BrowserWindow> and other swizzled components → Cards or plain MDX
  5. 05Step 5 of 55 ›Step 55.
    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.

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

Was this page helpful? Yes No
Product
Resources
Company
© 2026 SyntextBuilt with Syntext