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

---
title: 迁移
description: 如何将现有 Markdown 文档迁移到 TockDocs
navigation:
  icon: i-lucide-replace
---

## 从旧版 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` 扩展该层     |

::tip
您的 Markdown 内容和大多数 MDC 语法通常可以在不进行大幅重写的情况下迁移。最大的变化是项目结构和路由规范。
::

## 从任何 Markdown 文档设置迁移

无论您是从旧版 TockDocs、Nuxt UI 文档模板还是其他 Markdown 站点迁移，迁移路径通常如下：

::steps
### 创建一个全新的 TockDocs 项目

```bash [Terminal]
npx create-tockdocs my-docs
```

选择：

- `default` — 如果您需要单语言文档树
- `i18n` — 如果您需要在传统模式下使用本地化文档

### 将您的内容移入 `content/`

对于大多数项目，您可以直接将 Markdown 文件复制到新的 `content/` 目录中，然后逐步优化结构、导航元数据和 MDC。

### 选择合适的架构

使用与您的站点匹配的内容结构：

- **传统模式** — 用于单一文档树
- **知识库模式** — 用于需要多个知识库的场景，如 `/docs/manual/zh/...` 和 `/docs/parser/en/...`

### 更新路由和链接

如果您的旧文档使用了不同的路由，请检查：

- 内部 Markdown 链接
- 图片路径
- 任何硬编码的 `/docs/...` URL
- 知识库 ID 和语言前缀

### 审查配置和 AI 功能

内容迁移完成后，请查阅[配置](/docs/manual/zh/concepts/configuration)、[助手](/docs/manual/zh/ai/assistant) 和 [MCP](/docs/manual/zh/ai/mcp) 指南，使您的应用与当前的 TockDocs 规范保持一致。
::

## 传统模式 vs 知识库模式

### 传统模式

当您的项目只有一个文档树时使用此模式。

单语言示例：

```bash
content/
├── index.md
└── guide/
    └── introduction.md
```

本地化示例：

```bash
content/
├── en/
│   └── guide/
└── zh/
    └── guide/
```

### 知识库模式

当您希望在一个站点中管理多个文档集合时使用此模式：

```bash
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 功能指向预期内容范围