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.
Updated Nov 19, 20263 min read
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
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.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.
Pick the repository
Typemark shows ReadMe project detected. Click Import and confirm.
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.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 intoimages/and update the links before you cancel ReadMe. Your coding agent can do this for you.Turn off the sync and go live
Disconnect the GitHub sync in ReadMe, work through the go-live checklist, then click Go live in Settings > Publishing.
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 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.iostay 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. <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:
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:
typemark migrate --from readme --agent claude