# From ReadMe

> Sync your ReadMe project to GitHub, or export it, and import the repository. Category folders become your navigation, page order comes from _order.yaml, and your MDX keeps its syntax.

ReadMe can write a project to a GitHub repository with its bi-directional sync, as Markdown files in folders. Typemark imports that repository: each category folder becomes a navigation group, `_order.yaml` sets the page order, and your API reference pages show their endpoints from your OpenAPI files.

ReadMe's pages are MDX, so Typemark reads them as they are: `excerpt` works as the page description and `<Callout>`, `<Image>`, `<Cards>` and `<Embed>` render without changes. The import moves files so your URLs stay the same, and converts what only renders on ReadMe, such as emoji callouts and `doc:` links, in one commit you can review.

## Before you start

- Your ReadMe plan includes the GitHub sync, or you can export the project. Check your plan in ReadMe.
- ReadMe's sync needs a new, empty repository: no commits and no README.
- The repository is 100 MB or smaller.

## Import your project

<Steps>
  <Step title="Sync the project to GitHub">
    In ReadMe, connect the project to a new, empty GitHub repository. ReadMe writes `docs/`, `reference/` and the other folders to it. Each ReadMe version is a branch; Typemark imports the one you pick when connecting, the default branch unless you choose another.
  </Step>
  <Step title="Create a Typemark project">
    Click **New project**, name it, and under **Start from** choose **Import from GitHub**. Click **Create and connect GitHub**, and give the Typemark GitHub App access to the repository.
  </Step>
  <Step title="Pick the repository">
    Typemark shows **ReadMe project detected**. Click **Import** and confirm.
  </Step>
  <Step title="Review the import">
    Typemark writes `typemark.json`, converts legacy syntax in one commit, pushes it and builds your site. The project overview shows the [import summary](https://docs.typemark.dev/migrating/overview#the-import-summary).
  </Step>
  <Step title="Bring your images over">
    Images you uploaded to ReadMe are hosted on `files.readme.io`. They keep working for now, but they live on ReadMe. The summary lists every page that uses them: download them into `images/` and update the links before you cancel ReadMe. Your [coding agent](https://docs.typemark.dev/migrating/other) can do this for you.
  </Step>
  <Step title="Turn off the sync and go live">
    Disconnect the GitHub sync in ReadMe, work through the [go-live checklist](https://docs.typemark.dev/migrating/overview#go-live-checklist), then click **Go live** in **Settings** > **Publishing**.
  </Step>
</Steps>

## What gets converted

| ReadMe | Typemark |
|--------|----------|
| Category folders in `docs/` | Navigation groups named after the folder, in a **Guides** tab |
| Page files | Moved to match ReadMe's URLs, so `/docs/my-page` stays `/docs/my-page`. Redirects cover the older flat URLs of nested pages |
| `_order.yaml` | Page order within the group. The files themselves are removed |
| A folder with `index.md` and subpages | The index page, then its subpages, in the same group |
| API reference pages (`api:` with an `operationId`) | [Endpoint pages](https://docs.typemark.dev/api-reference/openapi#write-an-endpoints-page) at the same URL and in the same place, in an **API Reference** tab. Each shows the endpoint from your spec around the page's own text. Typemark adds `openapi: "<spec> METHOD /path"` to the frontmatter |
| OpenAPI files in `reference/` without reference pages | Generated API pages in the **API Reference** tab |
| `title` | `title` |
| `excerpt` | The page description, read as it is |
| `hidden: true` | Hidden from the sidebar, still reachable by URL |
| `<Callout icon="📘" theme="info">` | Renders as a callout and opens in the visual editor. Saved as written |
| `<Image>`, `<Cards>`, `<Columns>`, `<Embed>`, `<Table>`, `<Anchor>` | Render as written. An `<Embed>` of a YouTube, Vimeo, Loom, or Wistia video plays it |
| `> 📘 Title` emoji callouts | `<Callout>` with the matching theme |
| `doc:`, `ref:` and `recipe:` links | Links to the Typemark page |
| Glossary terms | Plain text |
| HTML comments | Removed, since they don't build in MDX |
| Recipes and custom pages | Regular pages, in **Recipes** and **Pages** groups |

## Not carried over

- **Images on `files.readme.io`** stay remote until you move them. See step 5.
- **More than one version.** A project imports one branch, the one you pick when connecting.
- **API "Try it" settings** and saved keys. Typemark's API pages show the reference from your spec.
- **Variables** such as `<<company>>` stay as text and are listed in the summary.
- **Changelog posts** in `changelogs/` aren't imported. Recreate the ones you need with [changelog entries](https://docs.typemark.dev/components/changelog).
- **`<HTMLBlock>` and `<TutorialTile>`** aren't supported and are listed in the summary.
- **Custom CSS** and other settings that live in ReadMe rather than the repository.

## From your terminal

To convert an export or a synced repository on your computer:

```bash
cd my-readme-project
typemark migrate             # detects the ReadMe project and converts it, then offers to create the project and push it
```

Answer yes twice and your site is on Typemark, offline until you publish it. In CI or with a coding agent, use `typemark migrate --create "My Docs" --push` instead.

`typemark migrate` writes the same changes as the GitHub import. Commit or stash your work first, so you can review the result with `git diff`.

## With your coding agent

Your coding agent can download the `files.readme.io` images, merge recipes into guides and fix anything the summary lists:

```bash
typemark migrate --from readme --agent claude
```

See [With your coding agent](https://docs.typemark.dev/migrating/other).
