Migration
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 |
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:
Create a fresh TockDocs project
npx create-tockdocs my-docs
Choose:
defaultif you want a single-locale docs treei18nif 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/parser/en/...
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, Assistant, and 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:
content/
├── index.md
└── guide/
└── introduction.md
Localized example:
content/
├── en/
│ └── guide/
└── zh/
└── guide/
Knowledge-base mode
Use this when you want multiple docs sets in one site:
content/
├── site/
│ └── index.md
├── manual/
│ ├── kb.yml
│ └── en/
└── parser/
├── kb.yml
└── en/
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