typemark.json
Every key the published site reads from typemark.json, with defaults and examples.
Aktualisiert am 19. Nov. 20266 Min. Lesezeit
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.
navigation
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" }
]
| Key | What it does |
|---|---|
code | A real language code such as fr, pt-BR or zh-Hans, used in addresses and folder names |
name | The name in the language picker, up to 50 characters |
default | true 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, for the languages AI translates into. See AI translations. "manual", the default, leaves translations to you. |
review | true to hold AI's translations in this language until someone approves them in the editor. See Review before readers see it. |
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. glossary tells AI how to translate terms, per language: up to 200 terms of up to 100 characters each. See AI translations.
"translations": {
"do_not_translate": ["Acme Pay", "acme.config.json"],
"labels": { "fr": { "Get started": "Premiers pas" } },
"glossary": { "fr": { "workspace": "espace de travail" } }
}
logo
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.
footer
Links, link groups, social profiles, and a copyright line at the bottom of every page. See Site footer for the full format.
seo
| Key | What it does |
|---|---|
og_image | Image for link previews (og:image and twitter:image). Use a full https:// URL. |
title_suffix | Text 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_description | The 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.
| Key | What it does | Plan |
|---|---|---|
search | Search across all pages, with Cmd+K | All |
ai_search | Ask 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 headings | All |
copy_code_button | A copy button on code blocks | All |
page_actions | Copy 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_branding | Removes the "Powered by Typemark" line | Pro, 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
| Key | What it does |
|---|---|
instructions | How 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" }
]
fromis a page path on your site. The leading/is optional.tois a path on your site or a fullhttp(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.mdgoes 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.
New projects include a $schema line at the top of the file. The published site doesn't read it.