TockDocs LogoTockDocs
AI coding agents: see /llms.txt for the full documentation index. Markdown version: /docs/manual/zh/concepts/edition.md.
核心概念

内容编辑

学习如何编写您的文档。

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

内容模式

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

传统模式

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

单语言示例：

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

本地化示例：

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 文件时，知识库模式即被启用。

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 页面替换首页：

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

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

Markdown 中的 MDC

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

组件

::note
来自 MDC 的问候
::

插槽

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

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

属性

内联属性：

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

组件块内的 YAML frontmatter：

::card
---
title: 文档
icon: i-lucide-book-open
---
从 Markdown 渲染的卡片。
::
请参阅 Nuxt Content 文档获取完整的 MDC 语法参考。

Frontmatter

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

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

页面内容在这里。

TockDocs 页面常用的键：

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

有序文件名和路由 slug

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

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

变为：

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

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

TockDocs 自动生成的内容

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

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