Migrate from ReadMe
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 | Git branches + preview deployments |
| Suggested edits | Reviews & approvals |
| Try It playground | Built-in API playground (from your OpenAPI spec) |
Migration Steps
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.
mkdir acme-docs && cd acme-docs
stx init
Copy your exported Markdown into docs/, organized into folders by category.
ReadMe's excerpt becomes description:
---
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.
ReadMe uses magic blocks and callout syntax that convert to MDX components:
| ReadMe | Syntext |
|---|---|
> 👍 callout |
<Tip> |
> 📘 callout |
<Note> |
> 🚧 callout |
<Warning> |
> ❗️ callout |
<Warning> |
[block:code] multi-language |
<CodeGroup> |
[block:parameters] tables |
Markdown tables |
[block:image] |
Standard Markdown images |
A quick regex pass handles most of these; stx dev will flag anything that doesn't compile.
Your ReadMe API Reference was generated from an OpenAPI spec — upload the same spec to Syntext:
curl -X POST https://api.syntext.dev/v1/projects/$PROJECT_ID/openapi \
-H "Authorization: Bearer $STX_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "url": "https://api.acme.com/openapi.json" }'
Endpoint pages, request/response schemas, and an interactive playground are generated automatically.
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