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.

Before: the repository ReadMe synced
docs/  getting-started/    _order.yaml    index.md    authentication.md    errors.md  guides/    _order.yaml    webhooks.mdreference/  openapi.json
After: your sidebar on Typemark
Getting started  Overview            index.md  Authentication  ErrorsGuides  WebhooksAPI reference  A page per endpoint in openapi.json

Steps

  1. Step 1: Create an empty GitHub repository

    No README, no first commit: ReadMe’s sync only connects to an empty repository.

  2. 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).

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

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

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

Terminal
npm install -g @gettypemark/clicd my-readme-repotypemark logintypemark migrate  # detects ReadMe, then offers to create and push

With your coding agent

Let Claude Code, Codex or Cursor finish the job.

Downloading your images from files.readme.io, reworking recipes and anything else the summary flags are good jobs for your coding agent. It runs on your computer under your own account, follows our ReadMe guide and keeps checking its work until the site builds cleanly.
npm install -g @gettypemark/clitypemark migrate --from readme --agent claude  # or codex, cursor, gemini

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