项目结构

概述

TockDocs 是一个 Nuxt 层。您的项目是一个普通的 Nuxt 应用，它扩展了该层，并添加内容、配置和可选的自定义 Vue 代码。

目前，TockDocs 支持两种内容架构：

• 传统模式 — 单一文档树，可选择使用 @nuxtjs/i18n 进行本地化
• 知识库模式 — 在 /docs/<kb>/<locale>/... 下组织多个文档集合

生成的起步模板默认使用 传统模式。TockDocs 官方站点使用 知识库模式。

起步模板结构

Default 模板

default 模板是一个单语言传统模式应用：

my-docs/
├── content/
│   ├── index.md
│   └── 1.getting-started/
├── nuxt.config.ts
├── package.json
└── public/

典型路由：

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

i18n 模板

i18n 模板仍然是传统模式，但内容按语言分组：

my-docs/
├── content/
│   ├── en/
│   │   ├── index.md
│   │   └── 1.getting-started/
│   └── zh/
│       ├── index.md
│       └── 1.getting-started/
├── nuxt.config.ts
├── package.json
└── public/

典型路由：

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

知识库模式

知识库模式适用于多产品或多领域的文档集合。官方文档站点采用此结构：

content/
├── site/
│   └── index.md
├── manual/
│   ├── kb.yml
│   ├── en/
│   │   └── 1.getting-started/
│   └── zh/
│       └── 1.getting-started/
└── parser/
    ├── kb.yml
    └── en/
        └── parser/

典型路由：

• content/site/index.md → /
• content/manual/en/1.getting-started/3.installation.md → /docs/manual/en/getting-started/installation
• content/parser/en/parser/best-document-parsing-apis-2026.md → /docs/parser/en/parser/best-document-parsing-apis-2026

每个知识库由一个 kb.yml 文件定义。该文件控制知识库的 ID、标题、语言、默认语言、入口页面和 UI 元数据。

package.json

起步应用刻意保持简洁。生成的 package.json 如下所示：

{
  "name": "my-docs",
  "scripts": {
    "dev": "nuxt dev",
    "build": "nuxt build"
  },
  "dependencies": {
    "@takumi-rs/core": "^1.0.15",
    "better-sqlite3": "^12.6.2",
    "nuxt": "^4.3.1",
    "tockdocs": "latest"
  }
}

说明：

• tockdocs 提供 Nuxt 层
• nuxt 是您的应用运行时
• better-sqlite3 由 Nuxt Content 使用
• @takumi-rs/core 用于本地开发中的 Takumi OG 图像渲染

nuxt.config.ts

起步模板已包含扩展层的 Nuxt 配置：

export default defineNuxtConfig({
  extends: ['tockdocs'],
})

您可以在此处添加额外的 Nuxt 模块、站点元数据、i18n 配置或高级助手设置。

app/app.config.ts

app.config.ts 是可选的，但它是自定义 TockDocs UI 层的主要位置。

export default defineAppConfig({
  seo: {
    title: 'My Docs',
    description: 'My awesome documentation',
  },
  header: {
    title: 'My Docs',
  },
})

用它来配置品牌、导航、社交媒体、目录、GitHub 链接、颜色模式和助手 UI 选项。

标准 Nuxt 目录仍然可用

因为 TockDocs 只是一个 Nuxt 层，您可以在内容旁边使用标准的 Nuxt 应用结构：

my-docs/
├── app/
│   ├── app.config.ts
│   ├── components/
│   ├── layouts/
│   ├── pages/
│   └── composables/
├── content/
├── public/
├── server/
├── nuxt.config.ts
└── package.json

当您想要以下操作时使用这些目录：

• 添加自定义 Vue 组件
• 覆盖内置的层组件
• 在文档内容之外创建额外页面
• 添加 API 路由或服务端工具
• 安装和配置额外的 Nuxt 模块