Migrate from ReadMe to Typemark
Connect ReadMe’s sync to a new, empty GitHub repository, then import it. Your category folders, page order, callouts and OpenAPI files come with you.
Facts about ReadMe checked against ReadMe's docs (bi-directional sync, documentation structure, exporting data), November 2026.
Before and after
The folders ReadMe writes to GitHub, and the navigation Typemark builds from them.
docs/ getting-started/ _order.yaml index.md authentication.md errors.md guides/ _order.yaml webhooks.mdreference/ openapi.jsonGetting started Overview index.md Authentication ErrorsGuides WebhooksAPI reference A page per endpoint in openapi.jsonSteps
Step 1: Create an empty GitHub repository
No README, no first commit: ReadMe’s sync only connects to an empty repository.
Step 2: Connect ReadMe’s bi-directional sync
In ReadMe, connect your project to that repository, and ReadMe writes your docs into it. No sync? Export your project’s files from ReadMe’s Branch menu and push them to the repository yourself (that export leaves out images).
Step 3: Import the repository
In Typemark, create a project and choose Import from GitHub. (Already have a project? Use Settings → GitHub → Connect.) Pick the repository and you’ll see “ReadMe project detected”. Typemark builds the site and shows you a summary of the import.
Step 4: Disconnect ReadMe’s sync
Once you’re happy with the result, disconnect the repository in ReadMe so only Typemark and your team write to it.
Step 5: Move your images, then go live
Images uploaded to ReadMe keep loading from files.readme.io. Download them into the repository before you cancel ReadMe. Then add your domain and click Go live in Settings → Publishing.
What converts
- docs/ category folders → navigation groups
- _order.yaml → page order
- index.md → the category’s parent page
- excerpt → page description, read as it is
- hidden pages, kept out of the sidebar and reachable by URL
- <Callout theme icon>, working as written
- Emoji blockquote callouts (> 📘 Title) → callouts
- OpenAPI files in reference/ → generated API pages
- Recipes and custom pages → regular pages (partly)
- Glossary terms → plain text; variables listed (partly)
What doesn’t carry over
None of these will stop the import, but plan for them before you cancel ReadMe.
- Images on files.readme.io
- They keep loading from ReadMe. Download them into your repository before you cancel.
- API “Try it”
- Typemark generates reference pages from your OpenAPI files, without an interactive playground or saved API keys.
- Recipes’ walkthroughs
- Each recipe becomes a regular page, without the step-by-step code walkthrough.
- Variables
- Left as text and listed in the import summary. Glossary terms become plain text.
- Changelog
- Posts in changelogs/ aren’t imported. Recreate them with Update blocks.
- Other versions
- ReadMe syncs each version to its own branch. Typemark imports the main branch.
From your terminal
Would you rather not connect GitHub? Run the same conversion on a copy of the synced repository and publish from your terminal.
npm install -g @gettypemark/clicd my-readme-repotypemark logintypemark migrate # detects ReadMe, then offers to create and pushWith your coding agent
Let Claude Code, Codex or Cursor finish the job.
npm install -g @gettypemark/clitypemark migrate --from readme --agent claude # or codex, cursor, geminiUsing another agent? typemark migrate --guide prints the guide so you can paste it in.
Questions
- Do I need a paid ReadMe plan to sync?
- No. ReadMe lists bi-directional sync with GitHub, GitLab and Bitbucket on its free Starter plan. Typemark imports from GitHub, so connect a GitHub repository for the move.
- Why does the repository have to be empty?
- ReadMe requires it: the repository you sync to must have no commits or files, not even a README, before you connect it.
- Are my Markdown files rewritten?
- Barely. Typemark reads your frontmatter as it is, so excerpt works as the page description and <Callout> renders unchanged. The import moves files to match ReadMe’s URLs and converts what only renders on ReadMe: emoji callouts, glossary terms and doc: links. It’s all one Git commit you can review.
- What happens to my API reference?
- OpenAPI files in reference/ become generated API pages, one per endpoint. Typemark has no interactive “Try it” playground yet. If your readers rely on it, keep that in mind before you switch.
- I have several versions. What happens?
- ReadMe syncs each version to a branch named after it. Typemark imports the main branch, so other versions don’t come across.
Still deciding? Compare Typemark and ReadMe side by side.
Bring your ReadMe docs over.
Import the synced repository and read the summary. Nothing goes public until you click Go live.
14-day Pro trial, no card. Your content stays in Git.