Migrate from ReadMe
Move your docs from ReadMe.com to Syntext — export, convert, and deploy.
ReadMe stores content in its own hosted editor, so migration is a three-step process: export your content, convert it to MDX, and recreate your API reference from your OpenAPI spec.
After exporting from ReadMe, the CLI can do the conversion automatically: stx migrate --from readme --dir ./exported-docs. Use --dry-run to preview first.
Concept Mapping
| ReadMe | Syntext |
|---|---|
| Guides | MDX pages in docs/ |
| API Reference (from OpenAPI) | OpenAPI import — auto-generated endpoint pages + playground |
| Recipes | Regular MDX pages (use Steps) |
| Changelog | A changelog.mdx page or dedicated section |
| Custom pages | MDX pages |
| Versions | Versioning — one version per branch or tag (Pro) |
| Suggested edits | Workflow reviews & approvals |
| Try It playground | Built-in API playground (from your OpenAPI spec) |
Migration Steps
- 01Step 1 of 61 ›Step 11.Export from ReadMe
Use ReadMe's export (Project Settings → Export) or the
rdmeCLI to download your docs as Markdown files. Each file comes with YAML frontmatter containingtitle,excerpt, andcategory. - 02Step 2 of 62 ›Step 22.Initialize a Syntext projectbashstx init acme-docs --preset workbenchcd acme-docs
Copy your exported Markdown into
docs/, organized into folders by category. - 03Step 3 of 63 ›Step 33.Convert frontmatter
ReadMe's
excerptbecomesdescription:ReadMe (before)Syntext (after)---title: "Authentication"excerpt: "How to authenticate API requests"category: "api-basics"------title: "Authentication"description: "How to authenticate API requests"---Categories become navigation groups in syntext.json instead of per-page frontmatter.
- 04Step 4 of 64 ›Step 44.Convert ReadMe-specific blocks
On doc engine v1 sites, ReadMe's emoji callouts work as-is —
> 📘 Note,> 🚧 Careful,> 👍 Success, and> ❗ Importantblockquotes are styled as callouts: the emoji is replaced with an icon, and the first line becomes the callout title. Doc engine v2 doesn't read the emoji forms — there they stay plain quotes, so convert them to MDX components (or to a bold-label blockquote such as> **Note:** …, see Callouts):ReadMe Syntext v1 (automatic) Syntext (MDX — needed on v2) > 👍calloutSuccess callout <Tip>> 📘calloutNote callout <Note>> 🚧calloutWarning callout <Warning>> ❗️calloutImportant callout <Danger>ReadMe magic blocks still need converting:
ReadMe Syntext [block:code]multi-language<CodeGroup>[block:parameters]tablesMarkdown tables [block:image]Standard Markdown images A quick regex pass handles most of these; a preview build from
stx devshows anything that doesn't compile. - 05Step 5 of 65 ›Step 55.Import your OpenAPI spec
Your ReadMe API Reference was generated from an OpenAPI spec — list the same spec under
openapiinsyntext.json:json{"openapi": "./openapi.json"}Endpoint pages, request/response schemas, and an interactive playground are generated automatically.
- 06Step 6 of 66 ›Step 66.Preview and deploybashstx dev # verify locallystx deploy # ship it
Then configure your custom domain.