# typemark.json

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

`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 <kbd>Cmd</kbd>+<kbd>S</kbd>) 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

```json title="typemark.json"
{
  "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.

```json
"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](https://docs.typemark.dev/github/sync#files-typemark-doesnt-use).

### navigation

Tabs, groups, and pages for the sidebar. A page that isn't listed here isn't published. See [Navigation](https://docs.typemark.dev/configuration/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](https://docs.typemark.dev/configuration/languages).

```json
"languages": [
  { "code": "en", "name": "English" },
  { "code": "fr", "name": "Français", "translate": "ai" }
]
```

| Key | What it does |
|-----|--------------|
| `code` | A real [language code](https://docs.typemark.dev/configuration/languages#language-codes) 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](https://docs.typemark.dev/ai/ai-translations#languages-ai-translates-into). See [AI translations](https://docs.typemark.dev/ai/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](https://docs.typemark.dev/ai/ai-translations#review-before-readers-see-it). |

### translations

Translation settings. `do_not_translate` lists terms [AI translations](https://docs.typemark.dev/ai/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](https://docs.typemark.dev/configuration/languages#translate-tab-group-and-link-names). `glossary` tells AI how to translate terms, per language: up to 200 terms of up to 100 characters each. See [AI translations](https://docs.typemark.dev/ai/ai-translations#translate-terms-the-same-way-everywhere).

```json
"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](https://docs.typemark.dev/configuration/branding).

```json
"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).

```json
"favicon": "/images/favicon.png"
```

### colors

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

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

### top_navigation

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

```json
"top_navigation": [
  { "label": "Blog", "url": "https://acme.com/blog" },
  { "label": "Support", "url": "mailto:support@acme.com" }
]
```

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](https://docs.typemark.dev/configuration/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 <kbd>Cmd</kbd>+<kbd>K</kbd> | All |
| `ai_search` | Ask AI: answers to readers' questions from your docs. Needs `search` on too. See [AI search](https://docs.typemark.dev/ai/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](https://docs.typemark.dev/ai/agent-ready). | All |
| `feedback_widget` | "Was this page helpful?" at the end of each page, with results in Analytics. See [Reader feedback](https://docs.typemark.dev/configuration/analytics#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](https://docs.typemark.dev/ai/ai-translations#set-the-tone) take their tone from it. Also editable in **Settings** > **AI writing**. See [AI writing](https://docs.typemark.dev/editor/ai-writing#tell-ai-how-you-write). Pro and Enterprise. |

### redirects

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

```json
"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](https://docs.typemark.dev/configuration/custom-code).

```json
"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](https://docs.typemark.dev/configuration/custom-code#integrations).

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

## Editing the config

<Tabs>
  <Tab title="In Settings">
    **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.
  </Tab>
  <Tab title="In your repository">
    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](https://docs.typemark.dev/github/connecting), push to your deployment branch and Typemark rebuilds the site.
  </Tab>
</Tabs>

<Callout type="warning">
  If `typemark.json` isn't valid JSON, the build fails and your live site keeps serving the last version that built. The error shows on your project's overview page.
</Callout>

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