Migrate from Docusaurus
Move your docs from Docusaurus to Syntext and stop maintaining a doc site build.
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
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
| 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> (by hand — see step 3) |
```js title="file.js" code titles | Same syntax — supported |
<Tabs> / <TabItem> | <Tabs> / <Tab> (by hand) |
Front matter sidebar_position | Order in syntext.json navigation |
| Versioned docs | Versioning — one version per branch or tag (Pro) |
| Algolia DocSearch | Built-in full-text search — zero config |
Migration Steps
- 01Step 1 of 51 ›Step 11.Initialize Syntext
In a new, empty folder:
bashstx init my-docs --preset workbenchThen copy your
docs/pages in.stx initwritesdocs/index.mdx, so keep the one you want. - 02Step 2 of 52 ›Step 22.Translate sidebars.jssidebars.js (before)syntext.json (after)module.exports = {docs: [{type: 'category',label: 'Getting Started',items: ['intro', 'installation'],},],}{"navigation": [{"group": "Getting Started","pages": ["intro", "installation"]}]}
type: 'autogenerated'sidebars: leavenavigationout and the folder structure becomes the sidebar (see Navigation), or list pages explicitly. - 03Step 3 of 53 ›Step 33.Convert admonitions
Replace Docusaurus admonition syntax with MDX components:
BeforeAfter:::warning Heads upThis action is irreversible.:::<Warning>**Heads up** — this action is irreversible.</Warning>A find-and-replace or codemod handles this. If you ran
stx migrate --from docusaurus, look for the> NOTE:-style blockquotes it wrote. - 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 - 05Step 5 of 55 ›Step 55.Deploy and delete your build pipelinebashstx 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
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.