---
title: "Navigation"
description: "How the sidebar, header tabs, prev/next links, and breadcrumbs are generated from your content directory."
canonical_url: "https://docs-template.comark.dev/writing/navigation"
---
# Navigation

> How the sidebar, header tabs, prev/next links, and breadcrumbs are generated from your content directory.

Navigation is generated from the `content/` directory — there's no separate sidebar config to maintain. The file tree *is* the navigation tree, and everything else (header tabs, prev/next links, breadcrumbs, search, `llms.txt`) derives from it.

## The navigation tree

Each directory becomes a section, each Markdown file a page. Numeric prefixes control ordering and are stripped from URLs and titles:

```
content/
├── 1.getting-started/          → section "Getting Started"
│   ├── .navigation.yml
│   ├── 1.introduction.md       → first page in the section
│   └── 2.installation.md       → second page
└── 2.writing/                  → section "Writing"
```

Section titles come from the `.navigation.yml` file in each directory:

```yaml [content/1.getting-started/.navigation.yml]
title: Getting Started
```

Page titles come from frontmatter — `navigation.title` when set, `title` otherwise. Pages with `navigation: false` are excluded from the tree entirely (and therefore from prev/next links, search, and `llms.txt`).

## Section layouts

Pages use the `docs` layout by default, which includes the navigation sidebar. Set `layout: page` in a directory's `.navigation.yml` to render every page in that directory without the sidebar:

```yaml [content/3.examples/.navigation.yml]
title: Examples
layout: page
```

The layout applies to nested directories too. A nested `.navigation.yml` can set `layout: docs` to restore the sidebar. The `page` layout keeps the header, footer and page table of contents.

## Header tabs

The header renders one tab per group in `header.nav` from `app.config.ts`. Each group maps top-level content sections to a tab:

```ts [app.config.ts]
export default defineAppConfig({
  header: {
    nav: [
      { label: 'Documentation', sections: ['getting-started', 'writing'] },
      { label: 'API Reference', sections: ['reference'] },
    ],
  },
})
```

When a tab is active, the sidebar shows only its sections: a single-section tab shows that section's pages as a flat list, and a multi-section tab shows the sections as collapsible groups.

When `header.nav` is empty (the default), the layer derives one tab per top-level section.

### Group options

| Key          | Purpose                                                                                                                       |
| ------------ | ----------------------------------------------------------------------------------------------------------------------------- |
| `label`      | Tab text.                                                                                                                     |
| `sections`   | Top-level content directories (without numeric prefix) grouped under this tab.                                                |
| `link`       | Where the tab links: `'first-leaf'` (default, the first page of the first section) or `'section'` (the section's index page). |
| `to`         | Makes a manual tab pointing at an app route instead of content sections.                                                      |
| `activePath` | Path prefix that marks a manual tab active; defaults to `to`.                                                                 |
| `children`   | Dropdown items for a manual tab: `{ label, to, activePath? }`.                                                                |

A GitHub tab is appended automatically when the repository is known.

## Derived from the tree

- **Prev/next links** — each page's neighbors in the flattened tree of its tab.
- **Headline** — the small label above a page title is the parent section's title.
- **Breadcrumbs** — emitted as [BreadcrumbList JSON-LD](https://developers.google.com/search/docs/appearance/structured-data/breadcrumb) for search engines.
- **Search** — `⌘K` indexes every page section; results are grouped by the navigation hierarchy.
- **Sitemap and `llms.txt`** — both list the pages of the navigation tree.

## Version previews

On a [branch or commit preview](https://docs-template.comark.dev/concepts/versioned-previews), the whole navigation is rebuilt from *that version's* content and every link is prefixed with the version base (`/tree/my-branch/...`), so you always browse a coherent snapshot.


## Sitemap

See the full [sitemap](https://docs-template.comark.dev/sitemap.md) for all pages.