Project Structure
Overview
Using the default template as an example:
my-docs/
├── app/
│ ├── app.config.ts # Runtime UI config (optional)
│ ├── components/ # Same-name components override the layer (optional)
│ └── composables/ # Same-name composables override the layer (optional)
├── content/
│ ├── index.md # Landing page
│ ├── releases.yml # Releases page (optional)
│ ├── templates.yml # Showcase page (optional)
│ └── docs/ # Docs pages, required
├── public/ # Static assets served from the root path
├── skills/ # Agent Skills (optional)
├── nuxt.config.ts # Module-level config
├── .env.example # Environment variable example
└── package.json
Content directory content/
Docs content/docs/
Docs always live in content/docs/, and the route prefix is always /docs. Numeric prefixes on directories and files only control ordering and never appear in routes:
content/docs/
├── 1.getting-started/
│ ├── .navigation.yml # Section title and icon
│ ├── 1.index.md # /docs/getting-started
│ └── 2.installation.md # /docs/getting-started/installation
└── 2.guide/
├── .navigation.yml
└── 1.configuration.md # /docs/guide/configuration
- Each top-level directory is a section; the section bar below the header and the sidebar switch per section
.navigation.ymlsets the section'stitleandiconin navigation- Pages within a section can be grouped further with
category, see Navigation and Categories
With internationalization enabled, default-locale content stays in content/docs/ and other locales go in content/{locale}/docs/, see Internationalization.
Landing page content/index.md
The root path / is rendered from content/index.md, which can use any MDC component. If you prefer to write the landing page in Vue, create app/pages/index.vue and the layer stops registering its built-in landing page.
Releases and showcase
The layer checks for these files at build time and registers the routes when they exist:
| File | Route | Purpose |
|---|---|---|
content/releases.yml or releases.md | /releases | Release timeline generated from GitHub Releases |
content/templates.yml or templates.md | /templates | Showcase cards |
See Pages and Layouts for the field formats.
Static assets public/
Files are served from the root path, so public/logo.svg becomes /logo.svg. Showcase screenshots go in public/assets/templates/ by convention.
nuxt.config.ts and app.config.ts
Each config file covers one layer:
nuxt.config.ts | app/app.config.ts | |
|---|---|---|
| Applies | At build time | At runtime |
| Typical content | Feature flags movkNuxtDocs.*, aiChat.model, mcp, llms, i18n, site.url | Header navigation, sidebar categories, footer, theme, SEO defaults, GitHub repository |
| Reference | nuxt.config Options | app.config Reference |
A typical combination:
export default defineNuxtConfig({
extends: ['@movk/nuxt-docs'],
site: {
url: 'https://docs.example.com',
name: 'My Docs'
},
movkNuxtDocs: {
mermaid: true
}
})
export default defineAppConfig({
header: {
title: 'My Docs',
nav: [
{ label: 'Docs', to: '/docs/getting-started', activeMatch: '/docs' }
]
},
github: {
owner: 'my-org',
name: 'my-docs'
}
})
app.config.ts is optional; every field has a default. See Configuration for how the two split responsibilities and common patterns.
Overriding components and composables
Create a component with the same name as a layer component in app/components/ to replace the default, for example app/components/HeaderLogo.vue. The overridable components and where they mount are listed in the override contract table on the Customization page.
Installation
Create a documentation site from an official template, or add @movk/nuxt-docs as a layer to an existing Nuxt project. This page compares the default, i18n and module templates and lists the runtime requirements and required dependencies.
Migrating from v2
Every breaking change when upgrading @movk/nuxt-docs from v2 to v3, each with a v2 and v3 comparison. Work through dependencies and feature flags, content paths, config fields, visual defaults and component overrides in order to finish the upgrade.