Typemark Documentation

From Mintlify

Import a Mintlify docs repo from GitHub or convert it in your terminal. Typemark converts docs.json and publishes your MDX pages without touching them.

Uuendatud 19. nov 20265 min lugemist

Your Mintlify pages work on Typemark as they are. On import, Typemark reads your docs.json (or older mint.json), writes a typemark.json next to it, and publishes your existing MDX pages. Your pages and your Mintlify config aren't changed.

Before you start

  • Your docs are in a GitHub repository you can install the Typemark GitHub App on.
  • The repository is 100 MB or smaller and has no Git submodules.
  • The Mintlify config is at the repository root or up to two folders down, such as docs/docs.json.

Import your site

  1. Create a project

    Click New project, name it, and under Start from choose Import from GitHub. Click Create and connect GitHub.

  2. Install the GitHub App

    GitHub asks where to install the Typemark app. Give it access to your docs repository.

  3. Pick the repository

    Back in Typemark, select the repository. Typemark shows Mintlify site detected with the config it found, and selects Import from GitHub.

  4. Import

    Click Import and confirm. Typemark clones the repository, converts the config, commits typemark.json to the root with the message "Add typemark.json (converted from docs.json)", pushes it to GitHub, and builds your site.

  5. Review the import summary

    You land on the project overview, which shows what was imported. See below.

  6. Go live

    New projects start offline. When the site looks right, click Go live in Settings > Publishing. See Publishing.

Already have a project? Go to Settings > GitHub > Connect to GitHub and pick the repository. The import replaces that project's current docs.

The import summary

The project overview shows a summary until you dismiss it:

SectionWhat it tells you
Pages found, In navigation, Missing pagesHow many pages are in the repo, how many your navigation lists, and how many it lists that don't exist
Referenced in navigation but not foundNavigation entries with no matching file. Fix the path or remove the entry.
Pages not in navigation (not published)Files your navigation doesn't list. Add them to a group to publish them.
ComponentsWhich components your pages use, and which ones Typemark doesn't render
Settings not importedEach setting Typemark dropped, and why

What gets converted

MintlifyTypemark
namename
colors.primarycolors.primary (other colors are dropped; Typemark derives its shades from the primary)
logo, faviconlogo, favicon
Tabs, anchors, dropdowns, and productsTabs
Nested groupsGroups placed right after their parent, since Typemark groups don't nest
Languages (navigation.languages)languages, the default language first. Every language uses the default language's navigation, and Typemark finds each translation at <code>/<page>, such as fr/quickstart. The summary names any translated pages that aren't there; rename them to match. Languages inside tabs or versions: only the default one is imported.
VersionsOnly the default one is imported
OpenAPI endpoint entries, such as GET /usersOne { "source": "openapi.json" } entry that generates a page per endpoint. Remote specs are skipped; add the spec file to the repo instead.
Navbar links, top bar links, and global anchors with a URLtop_navigation
Footer socials and link columnsfooter
redirectsredirects (wildcard redirects are skipped)
seo.metatags["og:image"]seo.og_image
integrations (analytics in mint.json) for Google Analytics 4, Google Tag Manager, Plausible, Fathom, Hotjar, and Intercomintegrations. Other tools are listed under Settings not imported; paste their snippet under Settings > Custom code.
.css and .js files in your docs foldercustom_code: CSS files under css, JavaScript files under body. JavaScript runs on your verified custom domain only. Custom code needs Pro or Enterprise.

Anything else, such as theme, fonts, icons in navigation, API playground settings, and other SEO tags, is dropped and listed under Settings not imported. The import never fails because of a setting it doesn't understand.

If your docs live in a subfolder, typemark.json gets a docs_root so page paths keep working. Typemark also turns on search, table of contents, and code copy buttons.

Components

These Mintlify components render on your Typemark site:

Note, Info, Tip, Check, Warning, Danger, Callout, Tabs, Tab, CodeGroup, Accordion, AccordionGroup, Card, CardGroup, Columns, Steps, Step, Frame, Expandable, ParamField, ResponseField, Tooltip, Icon, Badge, Update, Panel, RequestExample, ResponseExample

Videos embedded with <iframe> (YouTube, Vimeo, Loom, Wistia) or <video>, and ```mermaid diagrams, work as they are. See Videos and Diagrams.

Any other component still renders its content, in a plain container, instead of breaking the page.

In the visual editor, <Note>, <Info>, <Tip>, <Check>, <Warning>, and <Danger> open as callouts, and <Columns> opens as a card group. They save back under their original names, so your files keep Mintlify's syntax. Components the editor doesn't know stay as raw blocks and are saved exactly as written.

Known limits

  • Snippets don't render. Typemark strips import and export statements for security, and doesn't support <Snippet>. Paste snippet content into the page instead. The summary lists the pages that use them.
  • openapi: frontmatter pages show their endpoint when Typemark can find the spec: named in the frontmatter (openapi: "openapi.json GET /users") or listed in navigation. The default spec from docs.json isn't applied, so the summary lists pages whose endpoint isn't found; they show only their MDX body until you name the spec.
  • A page's styles stay inside the page. Typemark removes <style> and <script> tags from pages, and inline style and class keep sizes, spacing, layout and colours but not positioning (position, z-index, transform, fixed, z-50 and the like). Put site-wide CSS in custom code instead (Pro and Enterprise).
  • The Mintlify config isn't synced. After the import, typemark.json is what Typemark reads. Later changes to docs.json have no effect.
  • Protected branches. If GitHub rejects the push of typemark.json, for example because of branch protection, the import still finishes. The commit goes out with your next save.

From your terminal

To migrate a Mintlify site that isn't on GitHub, or to publish it to a project Typemark hosts, use the Typemark CLI:

typemark migrate             # writes typemark.json next to docs.json, 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.

It uses the same conversion as the GitHub import, so the tables above apply.

With your coding agent

For what the import leaves to you, such as snippets or openapi: pages without a spec, hand the folder to your coding agent:

typemark migrate --from mintlify --agent claude

The agent runs on your computer and follows the agent guide. See With your coding agent.

After the import

Your project stays connected to the repository. Edit in Typemark or keep pushing from your editor, and both update your site. See Sync. Before you switch your domain over, run through the go-live checklist.