> AI coding agents: see [/llms.txt](/llms.txt) for the full documentation index. Markdown version: [/docs/manual/en/concepts/edition.md](/docs/manual/en/concepts/edition.md).

---
title: Edition
description: Learn how to write your documentation.
navigation:
  icon: i-lucide-pencil
seo:
  description: Learn how to write your documentation with TockDocs and Nuxt Content.
  title: Edition
---

TockDocs is built on **Nuxt Content**. You write docs in Markdown, add richer UI with **MDC syntax**, and let the layer derive routing, navigation, search, and page metadata from your content structure.

## Content modes

TockDocs supports two routing/content architectures.

### Legacy mode

Legacy mode is the default shape used by the generated starters.

Single-locale example:

```bash
content/
├── index.md
└── 1.getting-started/
    └── 3.installation.md
```

Localized example:

```bash
content/
├── en/
│   ├── index.md
│   └── 1.getting-started/
└── zh/
    ├── index.md
    └── 1.getting-started/
```

Routes are derived from the file tree:

- `content/index.md` → `/`
- `content/1.getting-started/3.installation.md` → `/getting-started/installation`
- `content/en/1.getting-started/3.installation.md` → `/en/getting-started/installation`

Legacy mode also supports an optional `content/docs/` subfolder for apps that want docs under `/docs`.

### Knowledge-base mode

KB mode is enabled when TockDocs detects one or more `content/<kb>/kb.yml` files.

```bash
content/
├── site/
│   └── index.md
└── manual/
    ├── kb.yml
    └── en/
        └── 1.getting-started/
            └── 3.installation.md
```

Routes become KB-aware:

- `content/site/index.md` → `/`
- `content/manual/en/1.getting-started/3.installation.md` → `/docs/manual/en/getting-started/installation`

The `kb.yml` file defines the KB id, title, locales, default locale, entry page, and other UI metadata.

## Landing page behavior

### Legacy mode

If no custom Vue landing page exists, TockDocs uses Markdown landing content:

- `content/index.md` in single-locale apps
- localized `content/<locale>/index.md` in i18n apps

### KB mode

In KB mode, the root landing page behaves differently:

- if `content/site/index.md` exists, it is rendered at `/`
- otherwise TockDocs falls back to a knowledge-base directory page

### Custom Vue landing page

Since TockDocs is a Nuxt layer, you can always replace the landing page with your own Vue page:

```vue [app/pages/index.vue]
<template>
  <main>
    <h1>Custom landing page</h1>
  </main>
</template>
```

When you provide `app/pages/index.vue`, Nuxt handles `/` with your page instead of the default landing template.

## MDC in Markdown

MDC lets you use Vue components directly inside Markdown.

### Components

```mdc
::note
Hello from MDC
::
```

### Slots

```mdc
:::u-page-feature
  #title
  Nuxt 4

  #description
  Powered by Nuxt and Nuxt Content.
:::
```

### Props

Inline props:

```mdc
::card{title="Docs" icon="i-lucide-book-open"}
A card rendered from Markdown.
::
```

YAML frontmatter inside a component block:

```mdc
::card
---
title: Docs
icon: i-lucide-book-open
---
A card rendered from Markdown.
::
```

::tip{to="https://content.nuxt.com/docs/files/markdown"}
See the Nuxt Content docs for the full MDC syntax reference.
::

## Frontmatter

Each content page can define metadata at the top of the file:

```md [content/getting-started/edition.md]
---
title: Edition
description: Learn how to write your documentation.
---

Page content here.
```

Common keys used by TockDocs pages:

| Key           | Type                                                         | Description                                                            |
| ------------- | ------------------------------------------------------------ | ---------------------------------------------------------------------- |
| `title`       | `string`                                                     | Page title shown in the page header and used as an SEO fallback.       |
| `description` | `string`                                                     | Page description shown in the page header and used as an SEO fallback. |
| `navigation`  | `boolean | object`                                           | Controls how the page appears in navigation.                           |
| `layout`      | `string`                                                     | Overrides the Nuxt layout if needed.                                   |
| `seo`         | `{ title?: string, description?: string, ogImage?: string }` | Per-page SEO overrides.                                                |
| `sitemap`     | `boolean`                                                    | Excludes the page from the sitemap when set to `false`.                |

## Ordered filenames and route slugs

TockDocs ignores numeric ordering prefixes when generating public URLs. For example:

```bash
content/
└── 1.getting-started/
    └── 3.installation.md
```

becomes:

- `/getting-started/installation` in legacy mode
- `/docs/manual/en/getting-started/installation` in KB mode

Use numeric prefixes to control ordering in navigation without affecting the public slug.

## What TockDocs derives automatically

From your content tree, TockDocs automatically derives:

- routed page URLs
- left navigation structure
- table of contents headings
- search indexing
- assistant grounding data
- sitemap entries
- per-KB locale-aware collections in KB mode