Typemark Documentation

typemark.json

Every key the published site reads from typemark.json, with defaults and examples.

2026年11月19日更新6分で読めます

typemark.json sits at the root of your repository and controls how your site looks and behaves: navigation, languages, branding, header links, footer, features, SEO, redirects, custom code, and instructions for AI. Most of it is also editable in Settings, which writes the file for you.

Edit it in Settings

To edit the whole file without your repository or the CLI, the project owner opens Settings > typemark.json. It shows the file as written, even if it isn't valid JSON, so you can fix it there.

Click Save typemark.json (or press Cmd+S) to commit it and rebuild your site. Typemark doesn't save it while something in it would be ignored, such as invalid JSON or a value of the wrong type, and lists what to fix. If the file changed since you opened it, from a push, the CLI or another tab, Typemark doesn't overwrite it: copy your changes, click Load the latest, and make them again.

Plan features in the file, such as hide_branding or custom_code, work only on plans that include them, however the file was written.

When a value has the wrong type

A value of the wrong type, such as "redirects": 5 or a logo that's a string, is ignored as if it were missing, and the publish lists it as a warning on your project's overview. The rest of your site publishes as usual.

A navigation that isn't an object, or tabs that aren't a list, stops the publish instead, so a typo can't unpublish your pages. Your site keeps what it has until you fix it.

Full example

{
  "name": "Acme Docs",
  "logo": {
    "light": "/images/logo-light.svg",
    "dark": "/images/logo-dark.svg"
  },
  "favicon": "/images/favicon.png",
  "colors": {
    "primary": "#3b82f6"
  },
  "navigation": {
    "tabs": [
      {
        "tab": "Documentation",
        "groups": [
          { "group": "Getting started", "pages": ["introduction", "quickstart"] },
          { "group": "Guides", "pages": ["guides/authentication", "guides/deployment"] }
        ]
      },
      {
        "tab": "API reference",
        "groups": [
          { "group": "Endpoints", "pages": [{ "source": "api-reference/openapi.json" }] }
        ]
      }
    ]
  },
  "top_navigation": [
    { "label": "Blog", "url": "https://acme.com/blog" },
    { "label": "GitHub", "url": "https://github.com/acme" }
  ],
  "footer": {
    "links": [
      { "label": "Status", "url": "https://status.acme.com" },
      { "group": "Company", "links": [{ "label": "About", "url": "https://acme.com/about" }] }
    ],
    "socials": { "github": "https://github.com/acme", "x": "https://x.com/acme" },
    "copyright": "© 2026 Acme Inc."
  },
  "seo": {
    "title_suffix": " | Acme Docs",
    "default_description": "Guides and API reference for the Acme platform.",
    "og_image": "https://acme.com/og-image.png"
  },
  "features": {
    "search": true,
    "ai_search": true,
    "table_of_contents": true,
    "copy_code_button": true
  },
  "redirects": [
    { "from": "/old-page", "to": "/new-page" }
  ],
  "custom_code": {
    "css": "custom/styles.css",
    "head": "custom/head.html"
  },
  "integrations": {
    "ga4": { "measurement_id": "G-XXXXXXXXXX" }
  }
}

Keys

name

Your site's name. Renaming the project in Settings > General updates this key too. The site header, page titles, and the MCP server all use the project name from Settings, so rename the site there.

docs_root

The folder your pages live in, relative to the repository root. Leave it out when pages sit at the root.

"docs_root": "docs"

With "docs_root": "docs", the page reference guides/setup resolves to docs/guides/setup.mdx, and pages you create in the editor land in docs/. Asset paths in typemark.json (logo, favicon, and OpenAPI source) stay relative to the repository root. The import from GitHub sets docs_root for you when your docs live in a subfolder. In a repository connected to GitHub, files outside docs_root that typemark.json doesn't point to aren't used; see Files Typemark doesn't use.

Tabs, groups, and pages for the sidebar. A page that isn't listed here isn't published. See Navigation.

languages

The languages your site is published in. The default language comes first, or is marked "default": true; its pages are the ones in navigation. Each other language's translations are files in a folder named after its code, such as fr/quickstart.mdx, served at /fr/quickstart. Leave it out for a site in English only. On every plan. Also editable in Settings > Languages. See Languages.

"languages": [
  { "code": "en", "name": "English" },
  { "code": "fr", "name": "Français", "translate": "ai" }
]
KeyWhat it does
codeA real language code such as fr, pt-BR or zh-Hans, used in addresses and folder names
nameThe name in the language picker, up to 50 characters
defaulttrue on the language your pages are written in. Without it, the first language is the default.
translate"ai" to have AI translate every page into this language, Pro and Enterprise. See AI translations. "manual", the default, leaves translations to you.

translations

Translation settings. do_not_translate lists terms AI translations keep exactly as written, such as product names: up to 200 terms of up to 100 characters each, also editable in Settings > Languages. labels translates your tab, group, top navigation and footer link names per language, keyed by the name as written: up to 500 a language, each up to 200 characters. See Languages.

"translations": {
  "do_not_translate": ["Acme Pay", "acme.config.json"],
  "labels": { "fr": { "Get started": "Premiers pas" } }
}

Logo files for light and dark mode. Paths are relative to the repository root; full https:// URLs work too. If you set only one, it's used in both themes. Without a logo, the header shows your project name. See Branding.

"logo": {
  "light": "/images/logo-light.svg",
  "dark": "/images/logo-dark.svg"
}

favicon

The browser tab icon: a path relative to the repository root, or a { "light": ..., "dark": ... } object (the light file is used).

"favicon": "/images/favicon.png"

colors

primary is your accent color, used for links, the active sidebar item, and highlights. Sites without one use #4f46e5.

"colors": {
  "primary": "#3b82f6"
}

top_navigation

Links on the right of the site header. They open in a new tab.

"top_navigation": [
  { "label": "Blog", "url": "https://acme.com/blog" },
  { "label": "Support", "url": "mailto:[email protected]" }
]

URLs must be https:// or http://, mailto:, a path on your site starting with /, or an #anchor. Anything else is dropped.

Links, link groups, social profiles, and a copyright line at the bottom of every page. See Site footer for the full format.

seo

KeyWhat it does
og_imageImage for link previews (og:image and twitter:image). Use a full https:// URL.
title_suffixText after each page's title in the browser tab and search results, like " | Acme Docs". Include any leading space or separator. Set it to "" for the page title alone. Without it, titles read {page title} — {project name}.
default_descriptionThe meta description for pages without a description in their frontmatter, and the summary line at the top of your llms.txt. Without it, a page's description is {page title} documentation, and llms.txt uses "Documentation for" followed by your site's name.

features

Switches for site features. A feature is off unless it's set to true, except page_actions, which is on unless it's set to false. New projects start with search, table_of_contents, and copy_code_button on.

KeyWhat it doesPlan
searchSearch across all pages, with Cmd+KAll
ai_searchAsk AI: answers to readers' questions from your docs. Needs search on too. See AI search.Pro, Enterprise
table_of_contents"On this page" links to the page's headingsAll
copy_code_buttonA copy button on code blocksAll
page_actionsCopy page, Open in ChatGPT or Claude, and MCP setup. See Agent-ready docs.All
feedback_widget"Was this page helpful?" at the end of each page, with results in Analytics. See Reader feedback.Pro, Enterprise
hide_brandingRemoves the "Powered by Typemark" linePro, Enterprise

Plan-gated features follow the project owner's plan. On a plan without them, the key has no effect.

The light and dark theme toggle is always shown. Older configs may still contain theme_toggle; the site ignores it.

ai

KeyWhat it does
instructionsHow AI should write for this project, up to 2,000 characters. Every AI request in the editor follows it, and AI translations take their tone from it. Also editable in Settings > AI writing. See AI writing. Pro and Enterprise.

redirects

Send an old path to a new one with a permanent (301) redirect.

"redirects": [
  { "from": "/old-page", "to": "/new-page" },
  { "from": "/guides/legacy", "to": "https://acme.com/blog/legacy" }
]
  • from is a page path on your site. The leading / is optional.
  • to is a path on your site or a full http(s):// URL.
  • Redirects are checked before pages, so they work for paths that no longer exist.
  • Wildcards aren't supported. List each path.
  • The Markdown version of a page follows the same redirects: /old-page.md goes to /new-page.md.

custom_code

Your own CSS and HTML snippets, as paths to files in your repository: css (.css files), head and body (.html snippets or .js files). Each is a path or a list of paths, relative to the repository root. Pro and Enterprise. Scripts run on your verified custom domain only. See Custom code.

"custom_code": {
  "css": "custom/styles.css",
  "head": "custom/head.html",
  "body": ["custom/body.html"]
}

integrations

Analytics and support tools by ID: ga4, plausible, fathom, gtm, hotjar, and intercom. Pro and Enterprise. Google Analytics 4, Plausible, and Fathom also run on your typemark.dev address; the others need a verified custom domain. See Custom code.

"integrations": {
  "ga4": { "measurement_id": "G-XXXXXXXXXX" },
  "plausible": { "domain": "docs.example.com" }
}

Editing the config

Settings covers the name, branding, footer, features, the OpenAPI spec, and custom code. Changes save automatically (custom code has its own Save button), commit typemark.json to your repo, and rebuild the site.

Edit typemark.json directly for anything Settings doesn't cover, such as top_navigation, favicon, seo, redirects, docs_root, and languages. On a connected repo, push to your deployment branch and Typemark rebuilds the site.

New projects include a $schema line at the top of the file. The published site doesn't read it.