快速入门
迁移
如何将现有 Markdown 文档迁移到 TockDocs
从旧版 TockDocs 迁移
现代 TockDocs 基于 Nuxt 层 + ********create-tockdocs** 起步模板工作流**。
与旧版本相比，主要的迁移变更在于项目引导和命令流程：
| 旧版工作流 | 当前工作流 |
|---|---|
npx tockdocs init my-docs | npx create-tockdocs my-docs |
tockdocs dev | npm run dev |
tockdocs build | npm run build |
内联 --extends tockdocs | 生成的 nuxt.config.ts 扩展该层 |
您的 Markdown 内容和大多数 MDC 语法通常可以在不进行大幅重写的情况下迁移。最大的变化是项目结构和路由规范。
从任何 Markdown 文档设置迁移
无论您是从旧版 TockDocs、Nuxt UI 文档模板还是其他 Markdown 站点迁移，迁移路径通常如下：
创建一个全新的 TockDocs 项目
Terminal
npx create-tockdocs my-docs
选择：
default— 如果您需要单语言文档树i18n— 如果您需要在传统模式下使用本地化文档
将您的内容移入 content/
对于大多数项目，您可以直接将 Markdown 文件复制到新的 content/ 目录中，然后逐步优化结构、导航元数据和 MDC。
选择合适的架构
使用与您的站点匹配的内容结构：
- 传统模式 — 用于单一文档树
- 知识库模式 — 用于需要多个知识库的场景，如
/docs/manual/zh/...和/docs/parser/en/...
更新路由和链接
如果您的旧文档使用了不同的路由，请检查：
- 内部 Markdown 链接
- 图片路径
- 任何硬编码的
/docs/...URL - 知识库 ID 和语言前缀
审查配置和 AI 功能
传统模式 vs 知识库模式
传统模式
当您的项目只有一个文档树时使用此模式。
单语言示例：
content/
├── index.md
└── guide/
└── introduction.md
本地化示例：
content/
├── en/
│ └── guide/
└── zh/
└── guide/
知识库模式
当您希望在一个站点中管理多个文档集合时使用此模式：
content/
├── site/
│ └── index.md
├── manual/
│ ├── kb.yml
│ └── en/
└── parser/
├── kb.yml
└── en/
在知识库模式下，路由生成为 /docs/<kb>/<locale>/...，每个知识库拥有独立的集合、元数据、语言集和入口页面。
内容兼容性
- 标准 Markdown 可以原样复制并逐步改进
- Nuxt Content + MDC 内容如果引用的组件仍然存在，通常可以顺利迁移
- 自定义组件 可能需要在
app/components/中重新创建 - 传统路由假设 在迁移到知识库模式时可能需要更新
实操清单
在确认迁移完成之前，请验证：
- 内容渲染无原始 MDC 标记泄露
- 内部链接指向新的路由
- 导航标题和图标正确
- 语言过滤如预期
- 使用
kb.yml时知识库首页正确解析 - 助手和 MCP 功能指向预期内容范围