# Navigation

> Organize your sidebar with tabs, groups, and pages, and decide which pages get published.

The `navigation` key in `typemark.json` decides which pages your site publishes and in what order they appear. A page that isn't listed in navigation isn't published.

## Structure

Navigation has three levels: tabs, groups, and pages.

```json
"navigation": {
  "tabs": [
    {
      "tab": "Documentation",
      "groups": [
        { "group": "Getting started", "pages": ["introduction", "quickstart"] },
        { "group": "Guides", "pages": ["guides/authentication", "guides/deployment"] }
      ]
    }
  ]
}
```

- **Tabs** split your site into sections. With more than one tab, they appear in the site header and the sidebar shows the active tab's groups.
- **Groups** are headed sections in the sidebar. A group with no published pages is left out.
- **Pages** are references to files, listed in the order they appear.

## Page references

Each entry in `pages` is a file path without the extension. Typemark looks for `.mdx` first, then `.md`.

| Reference | File |
|-----------|------|
| `"introduction"` | `introduction.mdx` or `introduction.md` |
| `"guides/authentication"` | `guides/authentication.mdx` or `guides/authentication.md` |

The reference is also the page's URL path: `guides/authentication` is served at `/guides/authentication`.

If your pages live in a subfolder, set [`docs_root`](https://docs.typemark.dev/configuration/typemark-json#docs_root) and references resolve inside it.

<Callout type="warning">
  A reference to a file that doesn't exist is skipped, and the rest of the site builds normally. The editor won't let you save navigation that points to a missing file.
</Callout>

## What gets published

- **Listed pages** are published, appear in the sidebar, and get previous and next links in navigation order.
- **Files not in navigation** aren't published. Add them to a group to put them on your site.
- **The first page** of the first group in the first tab is your landing page.
- **Translations** aren't listed. A page's translations, such as `fr/quickstart.mdx`, are published with it, in the same place in navigation. See [Languages](https://docs.typemark.dev/configuration/languages).

To unlist a page, add `hidden: true` to its frontmatter. It still opens at its URL, but it's left out of the sidebar, previous and next links, search, the sitemap, `llms.txt`, `llms-full.txt`, and the [MCP server](https://docs.typemark.dev/ai/agent-ready), and it gets a `noindex` tag. If your first page is hidden, the landing page is the first listed one.

## Multiple tabs

```json
"navigation": {
  "tabs": [
    {
      "tab": "Documentation",
      "groups": [
        { "group": "Getting started", "pages": ["introduction", "quickstart"] }
      ]
    },
    {
      "tab": "Changelog",
      "groups": [
        { "group": "Releases", "pages": ["changelog/v2", "changelog/v1"] }
      ]
    }
  ]
}
```

## API reference from an OpenAPI spec

Use a `source` object instead of a page reference to generate API pages from an OpenAPI spec (JSON or YAML):

```json
{
  "group": "Endpoints",
  "pages": [
    "api-reference/overview",
    { "source": "api-reference/openapi.json" }
  ]
}
```

Typemark generates an overview page in that group, plus one page per endpoint, grouped in the sidebar by the endpoint's first tag. The `source` path is relative to the repository root. You can also upload a spec in **Settings** > **API reference**, which adds the entry for you.

## Editing navigation

<Tabs>
  <Tab title="In the editor">
    Open the **Navigation** tab in the editor's sidebar. Drag pages to reorder them or move them between groups, and add, rename, or delete groups. Changes save straight to `typemark.json`.

    Deleting a group unlinks its pages from navigation, which takes them off your site. The files stay in your repo.
  </Tab>
  <Tab title="In typemark.json">
    Edit the `pages` arrays. The order in the array is the order in the sidebar.

    ```json
    "pages": ["quickstart", "introduction"]
    ```
  </Tab>
</Tabs>

New pages you create in the editor are added to navigation automatically.
