Configuration Overview
Two configuration files
| File | Takes effect | Controls | Full reference |
|---|---|---|---|
nuxt.config.ts | Build time | Extending the layer, feature flags, AI models, MCP, llms.txt, i18n, site URL | nuxt.config Options |
app/app.config.ts | Runtime | Header, footer, navigation, sidebar categories, TOC, theme, GitHub integration, AI Chat UI text | app.config Reference |
The rule of thumb: anything that changes which code is bundled or which routes and files are generated goes in nuxt.config.ts; anything that only changes what is shown on the page goes in app.config.ts.
Minimal setup
After extending the layer, most sites only need a site name and navigation:
export default defineNuxtConfig({
extends: ['@movk/nuxt-docs'],
site: {
name: 'My Docs',
url: 'https://docs.example.com'
}
})
export default defineAppConfig({
header: {
nav: [
{ label: 'Docs', to: '/docs/getting-started', activeMatch: '/docs' },
{ label: 'Releases', to: '/releases' }
]
},
footer: {
credits: 'Copyright © 2026 My Team'
}
})
Unset fields fall back to the layer defaults. The following are inferred at build time:
| Field | Source |
|---|---|
site.name | name in package.json, then the Git repository name |
site.url | NUXT_PUBLIC_SITE_URL, NUXT_SITE_URL, or the deployment URL injected by Vercel, Netlify, Cloudflare Pages or GitLab Pages |
header.title | site.name in start case |
seo.title / seo.titleTemplate | site.name, with the template %s - {site.name} |
seo.description | description in package.json |
github.owner / name / url / branch | Local Git info or CI environment variables |
Common tasks
| Goal | Where | See |
|---|---|---|
| Change header links, the mobile menu or sidebar groups | header.nav, header.mobileNav, docs.categories in app.config | Navigation & Categories |
| Change the primary color, neutral color or heading font | ui.colors and theme.* in app.config | Theme & Fonts |
| Enable component docs, Mermaid or AI Chat | movkNuxtDocs.* and aiChat.* in nuxt.config | Feature Flags |
| Replace the header logo, footer or other UI regions | Create a component with the same name in app/components/ | Customization |
| Add a releases page, a showcase page or custom pages | content/releases.yml, content/templates.yml, app/pages/ | Pages & Layouts |
| Serve multiple languages | i18n in nuxt.config | Internationalization |
SEO
Site-wide defaults go in app.config.ts; per-page overrides go in the Markdown frontmatter:
export default defineAppConfig({
seo: {
titleTemplate: '%s - My Docs',
title: 'My Docs',
description: 'One sentence about your project'
}
})
---
title: Introduction
description: The page lead, also used as the default meta description.
seo:
title: Introduction
description: The description used by search engines and social cards.
---
Docs pages use seo.title for <title> and the OG image, falling back to title; descriptions work the same way.
GitHub integration
The layer infers the repository from local Git info. It powers the header GitHub icon, the "View source / Edit this page" links, PageLastCommit and CommitChangelog. Set rootDir when the docs are not at the repository root:
export default defineAppConfig({
github: {
rootDir: 'docs',
branch: 'main'
}
})
Set github: false to turn the integration off entirely. In production, configure NUXT_GITHUB_TOKEN to avoid the rate limits of anonymous GitHub API requests.
github.since, github.perPage and github.dateFormat.Table of contents and footer
export default defineAppConfig({
toc: {
title: 'On this page',
bottom: {
title: 'Community',
links: [
{ icon: 'i-lucide-book-open', label: 'Nuxt UI', to: 'https://ui.nuxt.com', target: '_blank' }
]
}
},
footer: {
credits: 'Copyright © 2026 My Team · <span class="text-highlighted">MIT License</span>',
socials: [
{ 'icon': 'i-simple-icons-github', 'to': 'https://github.com/my/repo', 'target': '_blank', 'aria-label': 'GitHub' }
]
}
})
footer.credits is rendered as MDC, so it can contain links and inline HTML. The GitHub "Edit this page" link is appended below the TOC automatically.
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.
Troubleshooting
Fix common build and runtime errors involving optional dependencies, AI Chat and MCP, docs 404s, i18n configuration, pnpm build approvals and commit history.