Typemark Documentation

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

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

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

  3. Pick the repository

    Typemark shows ReadMe project detected. Click Import and confirm.

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

  5. 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 can do this for you.

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

ReadMeTypemark
Category folders in docs/Navigation groups named after the folder, in a Guides tab
Page filesMoved to match ReadMe's URLs, so /docs/my-page stays /docs/my-page. Redirects cover the older flat URLs of nested pages
_order.yamlPage order within the group. The files themselves are removed
A folder with index.md and subpagesThe 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 pagesGenerated API pages in the API Reference tab
titletitle
excerptThe page description, read as it is
hidden: trueHidden 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: linksLinks to the Typemark page
Glossary termsPlain text
HTML commentsRemoved, since they don't build in MDX
Recipes and custom pagesRegular 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.
  • <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

See With your coding agent.