---
title: Migrate from ReadMe
description: "Move your docs from ReadMe.com to Syntext — export, convert, and deploy."
---

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

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

## 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](/components/steps)) |
| Changelog | A `changelog.mdx` page or dedicated section |
| Custom pages | MDX pages |
| Versions | Git branches + preview deployments |
| Suggested edits | [Reviews & approvals](/platform/collaboration) |
| Try It playground | Built-in API playground (from your OpenAPI spec) |

## Migration Steps

<Steps>
<Step title="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`.
</Step>

<Step title="Initialize a Syntext project">
```bash
mkdir acme-docs && cd acme-docs
stx init
```
Copy your exported Markdown into `docs/`, organized into folders by category.
</Step>

<Step title="Convert frontmatter">
ReadMe's `excerpt` becomes `description`:

<CodeGroup>
```yaml ReadMe (before)
---
title: "Authentication"
excerpt: "How to authenticate API requests"
category: "api-basics"
---
```

```yaml Syntext (after)
---
title: "Authentication"
description: "How to authenticate API requests"
---
```
</CodeGroup>

Categories become navigation groups in [syntext.json](/configuration/navigation) instead of per-page frontmatter.
</Step>

<Step title="Convert ReadMe-specific blocks">
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.
</Step>

<Step title="Import your OpenAPI spec">
Your ReadMe API Reference was generated from an OpenAPI spec — upload the same spec to Syntext:

```bash
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.
</Step>

<Step title="Preview and deploy">
```bash
stx dev      # verify locally
stx deploy   # ship it
```
Then configure your [custom domain](/guides/custom-domains).
</Step>
</Steps>

## 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](/concepts/annotations)
- **AI assistant** with documentation gap tracking
- **No per-seat editor pricing** — everyone with repo access can contribute