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

---
title: 内容编辑
description: 学习如何编写您的文档。
navigation:
  icon: i-lucide-pencil
seo:
  description: 学习如何使用 TockDocs 和 Nuxt Content 编写文档。
  title: 内容编辑
---

TockDocs 基于 **Nuxt Content** 构建。您使用 Markdown 编写文档，通过 **MDC 语法** 添加更丰富的 UI，由层根据您的内容结构自动生成路由、导航、搜索和页面元数据。

## 内容模式

TockDocs 支持两种路由/内容架构。

### 传统模式

传统模式是生成起步模板使用的默认结构。

单语言示例：

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

本地化示例：

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

路由从文件树派生：

- `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`

传统模式还支持可选的 `content/docs/` 子文件夹，用于希望在 `/docs` 下组织文档的应用。

### 知识库模式

当 TockDocs 检测到一个或多个 `content/<kb>/kb.yml` 文件时，知识库模式即被启用。

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

路由变为知识库感知：

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

`kb.yml` 文件定义了知识库的 ID、标题、语言、默认语言、入口页面和其他 UI 元数据。

## 首页行为

### 传统模式

如果没有自定义 Vue 首页，TockDocs 使用 Markdown 首页内容：

- 单语言应用中的 `content/index.md`
- i18n 应用中的本地化 `content/<locale>/index.md`

### 知识库模式

在知识库模式下，根首页的行为有所不同：

- 如果 `content/site/index.md` 存在，则在 `/` 渲染
- 否则 TockDocs 回退到知识库目录页面

### 自定义 Vue 首页

由于 TockDocs 是一个 Nuxt 层，您始终可以用自己的 Vue 页面替换首页：

```vue [app/pages/index.vue]
<template>
  <main>
    <h1>自定义首页</h1>
  </main>
</template>
```

当您提供 `app/pages/index.vue` 时，Nuxt 将使用您的页面处理 `/` 而不是默认的首页模板。

## Markdown 中的 MDC

MDC 让您可以直接在 Markdown 中使用 Vue 组件。

### 组件

```mdc
::note
来自 MDC 的问候
::
```

### 插槽

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

  #description
  由 Nuxt 和 Nuxt Content 驱动。
:::
```

### 属性

内联属性：

```mdc
::card{title="文档" icon="i-lucide-book-open"}
从 Markdown 渲染的卡片。
::
```

组件块内的 YAML frontmatter：

```mdc
::card
---
title: 文档
icon: i-lucide-book-open
---
从 Markdown 渲染的卡片。
::
```

::tip{to="https://content.nuxt.com/docs/files/markdown"}
请参阅 Nuxt Content 文档获取完整的 MDC 语法参考。
::

## Frontmatter

每个内容页面可以在文件顶部定义元数据：

```md [content/getting-started/edition.md]
---
title: 内容编辑
description: 学习如何编写您的文档。
---

页面内容在这里。
```

TockDocs 页面常用的键：

| 键             | 类型                                                           | 描述                       |
| ------------- | ------------------------------------------------------------ | ------------------------ |
| `title`       | `string`                                                     | 页面标题，显示在页面头部并作为 SEO 回退。  |
| `description` | `string`                                                     | 页面描述，显示在页面头部并作为 SEO 回退。  |
| `navigation`  | \`boolean                                                    | object\`                 |
| `layout`      | `string`                                                     | 如需要，覆盖 Nuxt 布局。          |
| `seo`         | `{ title?: string, description?: string, ogImage?: string }` | 每页 SEO 覆盖。               |
| `sitemap`     | `boolean`                                                    | 设为 `false` 时从站点地图中排除该页面。 |

## 有序文件名和路由 slug

TockDocs 在生成公共 URL 时会忽略数字排序前缀。例如：

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

变为：

- 传统模式下的 `/getting-started/installation`
- 知识库模式下的 `/docs/manual/en/getting-started/installation`

使用数字前缀控制导航顺序，而不影响公共 slug。

## TockDocs 自动生成的内容

从您的内容树中，TockDocs 自动生成：

- 路由页面 URL
- 左侧导航结构
- 目录标题
- 搜索索引
- 助手接地数据
- 站点地图条目
- 知识库模式下的每个知识库语言感知集合