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

Migrate from ReadMe

Move your docs from ReadMe.com to Syntext — export, convert, and deploy.

3 min read

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.

Note

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

ReadMeSyntext
GuidesMDX pages in docs/
API Reference (from OpenAPI)OpenAPI import — auto-generated endpoint pages + playground
RecipesRegular MDX pages (use Steps)
ChangelogA changelog.mdx page or dedicated section
Custom pagesMDX pages
VersionsVersioning — one version per branch or tag (Pro)
Suggested editsWorkflow reviews & approvals
Try It playgroundBuilt-in API playground (from your OpenAPI spec)

Migration Steps

  1. 01Step 1 of 61 ›Step 11.
    Export from ReadMe

    Use ReadMe's export (Project Settings → Export) or the rdme CLI to download your docs as Markdown files. Each file comes with YAML frontmatter containing title, excerpt, and category.

  2. 02Step 2 of 62 ›Step 22.
    Initialize a Syntext project
    bash
    stx init acme-docs --preset workbench
    cd acme-docs

    Copy your exported Markdown into docs/, organized into folders by category.

  3. 03Step 3 of 63 ›Step 33.
    Convert frontmatter

    ReadMe's excerpt becomes description:

    ReadMe (before)Syntext (after)
    ---
    title: "Authentication"
    excerpt: "How to authenticate API requests"
    category: "api-basics"
    ---

    Categories become navigation groups in syntext.json instead of per-page frontmatter.

  4. 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 > ❗ Important blockquotes 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):

    ReadMeSyntext 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:

    ReadMeSyntext
    [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 dev shows anything that doesn't compile.

  5. 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 openapi in syntext.json:

    json
    {
    "openapi": "./openapi.json"
    }

    Endpoint pages, request/response schemas, and an interactive playground are generated automatically.

  6. 06Step 6 of 66 ›Step 66.
    Preview and deploy
    bash
    stx dev # verify locally
    stx deploy # ship it

    Then configure your custom domain.

What You Gain

•
Docs-as-code — content lives in git, reviewed in PRs, built in CI
•
Code annotations — reference docs generated from source, kept honest by drift detection
•
AI assistant with documentation gap tracking
•
No per-seat editor pricing — everyone with repo access can contribute
Was this page helpful? Yes No
Product
Resources
Company
© 2026 SyntextBuilt with Syntext