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

---
title: Migration
description: " How to migrate your documentation from an existing Markdown solution to TockDocs"
navigation:
  icon: i-lucide-replace
---

## Migrating from older TockDocs versions

Modern TockDocs is based on a **Nuxt layer + ****`create-tockdocs` starter workflow**.

The main migration changes from older releases are the project bootstrap and command flow:

| Older workflow              | Current workflow                             |
| --------------------------- | -------------------------------------------- |
| `npx tockdocs init my-docs` | `npx create-tockdocs my-docs`                |
| `tockdocs dev`              | `npm run dev`                                |
| `tockdocs build`            | `npm run build`                              |
| inline `--extends tockdocs` | generated `nuxt.config.ts` extends the layer |

::tip
Your Markdown content and most MDC syntax can usually be migrated without major rewrites. The biggest changes are project structure and routing conventions.
::

## Migrating from any Markdown docs setup

Whether you are coming from older TockDocs, the Nuxt UI docs template, or another Markdown site, the migration path is usually:

::steps
### Create a fresh TockDocs project

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

Choose:

- `default` if you want a single-locale docs tree
- `i18n` if you want localized docs in legacy mode

### Move your content into `content/`

For most projects, you can copy your Markdown files directly into the new `content/` directory and then refine structure, navigation metadata, and MDC over time.

### Pick the right architecture

Use the content shape that matches your site:

- **legacy mode** for one documentation tree
- **knowledge-base mode** when you want multiple KBs like `/docs/manual/en/...` and `/docs/chemistry/zh/...`

### Update routes and links

If your old docs used different routes, review:

- internal Markdown links
- image paths
- any hardcoded `/docs/...` URLs
- knowledge-base ids and locale prefixes

### Review configuration and AI features

Once content is moved, review the [Configuration](/docs/manual/en/concepts/configuration), [Assistant](/docs/manual/en/ai/assistant), and [MCP](/docs/manual/en/ai/mcp) guides to align your app with current TockDocs conventions.
::

## Legacy mode vs knowledge-base mode

### Legacy mode

Use this when your project has a single documentation tree.

Single-locale example:

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

Localized example:

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

### Knowledge-base mode

Use this when you want multiple docs sets in one site:

```bash
content/
├── site/
│   └── index.md
├── manual/
│   ├── kb.yml
│   └── en/
└── chemistry/
    ├── kb.yml
    └── zh/
```

In KB mode, routes are generated as `/docs/<kb>/<locale>/...` and each KB gets its own collections, metadata, locale set, and entry page.

## Content compatibility

- **Standard Markdown** can be copied as-is and improved gradually
- **Nuxt Content + MDC** content often migrates cleanly if the referenced components still exist
- **Custom components** may need to be recreated in `app/components/`
- **Legacy route assumptions** may need updating when moving to KB mode

## Practical checklist

Before calling the migration complete, verify:

- content renders without raw MDC markers leaking
- internal links point to the new routes
- navigation titles and icons are correct
- locales are filtered as expected
- KB home pages resolve correctly when using `kb.yml`
- assistant and MCP features point to the intended content scope