Skip to main content

​
Migration Guide

Learn how to migrate to Docus from other documentation frameworks, or upgrade from Docus v3 to the new v4 architecture.

​
Migrating from Docus v3 to v4

Docus v4 introduces a new layer-based approach that leverages the official Nuxt CLI instead of the custom Docus CLI. While your existing content and configuration remain compatible, you’ll need to update your commands and project setup.

​
Breaking Changes

The main breaking changes are related to CLI commands:
Docus v3Docus v4
npx docus init my-docsnpx create-docus my-docs
docus devnuxt dev --extends docus
docus buildnuxt build --extends docus
Your existing Markdown content and MDC syntax will work without changes. The migration primarily involves updating your development and build workflow.

​
Migration Steps

1

Update package.json

Update your dependencies and scripts in package.json:
package.json
{
  "scripts": {
    "dev": "nuxt dev --extends docus",
    "build": "nuxt build --extends docus"
  },
  "dependencies": {
    "docus": "latest",
    "better-sqlite3": "^12.6.2",
    "nuxt": "^4.3.1"
  }
}
Remove the old docus CLI from devDependencies if present. The new version uses Nuxt CLI directly.
2

Add better-sqlite3 dependency

Docus v4 requires better-sqlite3 for Nuxt Content’s native SQLite connector:
npm install better-sqlite3
3

Update configuration (if needed)

If you have a custom nuxt.config.ts, ensure it extends the Docus layer:
nuxt.config.ts
export default defineNuxtConfig({
  extends: ['docus'],
  // Your custom configuration
})
4

Update environment variables

Review your environment variables. Some Studio and AI assistant configurations may have changed:
.env
# v4 uses new env variable names for AI features
AI_GATEWAY_API_KEY=your_api_key
5

Test your site

Install dependencies and test your site:
npm install
npm run dev
6

Update deployment configuration

Update your deployment scripts and CI/CD pipelines to use the new commands:
.github/workflows/deploy.yml
- name: Build
  run: npm run build

​
What Stays the Same

Content Files

All your Markdown content works without changes. MDC syntax remains identical.

Components

Custom Vue components work the same way. No changes needed.

Frontmatter

Page frontmatter structure is backward compatible.

App Config

app.config.ts structure remains the same with new features added.

​
New Features in v4

Nuxt 4 Support

Built on the latest Nuxt framework with improved performance and DX.

Tailwind CSS 4

Updated to Tailwind CSS 4 for modern styling capabilities.

AI Integration

Native LLM support with llms.txt generation and MCP server.

Studio Module

New self-hosted Studio module for visual content editing.

​
Migrating from Other Documentation Frameworks

Already using a Markdown-based documentation solution? Whether it’s Docus v1, VuePress, VitePress, Docusaurus, MkDocs, or another framework, migrating to Docus is straightforward.

​
Why Migrate to Docus?

Docus offers a clean and maintainable solution with a single dependency: the Docus library itself. No need to manage multiple plugins or configurations. Everything is built-in and maintained together, making updates simple.

Minimal Dependencies

Single docus dependency includes everything you need.

Vue Ecosystem

Full access to Nuxt and Vue’s powerful features.

MDC Syntax

Embed components in Markdown without complex configuration.

Built-in Features

Search, navigation, dark mode, and i18n work out of the box.

​
General Migration Steps

1

Create a Docus project

Start with a fresh Docus project:
npx create-docus my-docs
cd my-docs
2

Copy your content

Move your existing Markdown files into the content/ directory:
# For single-language docs
cp -r /path/to/old-docs/docs/* content/

# For i18n docs
cp -r /path/to/old-docs/en/* content/en/
cp -r /path/to/old-docs/fr/* content/fr/
3

Update frontmatter (if needed)

Convert your existing frontmatter to Docus format:Before (VitePress/VuePress):
---
sidebar: auto
next: /guide/advanced
---
After (Docus):
---
title: Getting Started
description: Learn the basics
navigation:
  icon: i-lucide-book
---
4

Convert custom components

If you already use Nuxt Content and MDC syntax:Most components should work directly. Check if equivalent components exist in Nuxt UI. If not, create your own custom components in app/components/.If you use standard Markdown:Your files work as-is. Progressively enhance your docs by adding MDC components where useful.
5

Migrate assets

Copy static assets to the public/ directory:
cp -r /path/to/old-docs/public/* public/
Update image paths in your Markdown if needed.
6

Configure branding

Create an app.config.ts file to customize your site:
app.config.ts
export default defineAppConfig({
  seo: {
    title: 'My Documentation',
    description: 'Documentation for my project'
  },
  header: {
    title: 'My Docs',
    logo: {
      light: '/logo-light.png',
      dark: '/logo-dark.png',
      alt: 'Logo'
    }
  },
  socials: {
    github: 'username/repo'
  }
})
7

Test and refine

Start the development server and test your migration:
npm run dev
Visit http://localhost:3000 and check:
  • All pages load correctly
  • Navigation works as expected
  • Images and assets display properly
  • Custom components render correctly

​
Framework-Specific Migration Notes

​
From VitePress

​
From VuePress

​
From Docusaurus

​
From MkDocs

​
Content Enhancement

After migrating, enhance your documentation with Docus features:

​
Add Components

::note
Important information for users.
::

::tip
Helpful suggestion or best practice.
::

::warning
Be careful with this action.
::

​
Add Icons

Docus includes Lucide and Simple Icons out of the box: 
:icon{name="i-lucide-rocket"}
:icon{name="i-simple-icons-github"}

​
Configure SEO

Add frontmatter for better SEO: 
---
title: Getting Started
description: Learn how to get started with our platform
seo:
  title: Getting Started - My Docs
  description: Complete guide to getting started with detailed examples
  ogImage: /images/og-getting-started.png
---

​
Troubleshooting

Content Not Displaying

Ensure files are in the content/ directory and have .md or .mdx extensions.

Components Not Working

Check that custom components are in app/components/ and use kebab-case names.

Navigation Issues

Verify file structure and use numbered prefixes for custom ordering.

Build Errors

Ensure better-sqlite3 is installed and compatible with your Node.js version.
For more troubleshooting help, see the Troubleshooting guide.

​
Getting Help

Need assistance with your migration?

Documentation

Browse the complete Docus documentation

GitHub Issues

Report issues or ask questions

GitHub Discussions

Join community discussions

Discord

Chat with the Nuxt community

​
Next Steps

Project Structure

Learn about Docus project organization

Studio Module

Edit your documentation visually in production

Build docs developers (and LLMs) love

Get started for freeTalk to us