Movk Nuxt Docs - Documentation Writing Guide

Follow this guide when creating documentation sites with Movk Nuxt Docs to ensure standardized content structure and correct component usage.

Project Overview

Movk Nuxt Docs is a documentation theme based on Nuxt 4, adopting a Layer architecture. Core tech stack:

Nuxt 4 + Nuxt Content - Framework and content management
Nuxt UI - Component library (Prose components for Markdown)
Tailwind CSS 4 - Styling system
MDC Syntax - Use Vue components in Markdown

Reference Documents

Load on demand according to current tasks, do not load all at once:

File	Content	When to Load
`references/mdc-components.md`	MDC component usage and templates	When writing Markdown content
`references/configuration.md`	nuxt.config.ts and app.config.ts configuration	When configuring the project
`references/writing-guide.md`	Content structure and writing standards	When creating new pages or organizing content

Workflow

Step 1: Analyze the Project

Check the existing project structure:

bash

# Check if Movk Nuxt Docs is installed
cat package.json | grep "@movk/nuxt-docs"

# Check content directories
ls content/
ls content/docs/

If it's a new project, create it using templates:

bash

# Full template (recommended)
npx nuxi init -t gh:mhaibaraai/movk-nuxt-docs/templates/default my-docs

# Module documentation template (streamlined)
npx nuxi init -t gh:mhaibaraai/movk-nuxt-docs/templates/module my-module-docs

Step 2: Understand Directory Structure

Standard project structure:

my-docs/
├── app/
│   ├── app.config.ts            # App configuration (theme, Header, Footer, etc.)
│   ├── components/              # Custom components (override Layer default components)
│   └── composables/             # Custom Composables
├── content/
│   ├── index.md                 # Homepage
│   ├── releases.yml             # Release notes (optional, auto-detected)
│   └── docs/                    # Documentation pages
│       ├── 1.getting-started/
│       │   ├── 1.index.md
│       │   └── 2.installation.md
│       ├── 2.guide/
│       │   └── 1.usage.md
│       └── 3.api/
│           └── 1.reference.md
├── public/                      # Static resources
├── nuxt.config.ts               # Nuxt configuration
└── package.json

File Naming Rules:

Use numeric prefixes to control sorting:
```
1.index.md
```
,
```
2.installation.md
```
Name files directly if no sorting is needed:
```
troubleshooting.md
```
,
```
ai-chat.md
```
Same for directories: use
```
1.getting-started/
```
for sorted directories, name directly otherwise
Numeric prefixes will not appear in URLs

Step 3: Write Content

Load

references/mdc-components.md

to learn about available components.

Each Markdown file requires Front-Matter:

---
title: Page Title
description: Page description, used for SEO and search.
---

## First Section

Body content...

Optional Front-Matter Fields:

Field	Description
`title`	Page title
`description`	Page description
`navigation.title`	Title displayed in navigation (can be different from title)
`navigation.icon`	Navigation icon (e.g., `i-lucide-book` )
`category`	Page category
`seo.title`	SEO title (overrides title)
`seo.description`	SEO description (overrides description)

Step 4: Configure the Project

Load

references/configuration.md

to learn about detailed configuration options.

Basic

nuxt.config.ts

export default defineNuxtConfig({
  extends: ['@movk/nuxt-docs'],

  // AI Chat (optional)
  aiChat: {
    model: 'openai/gpt-5-nano',
    models: ['openai/gpt-5-nano'],
  },

  // MCP Server (optional)
  mcp: {
    name: 'My Docs'
  }
})

Step 5: Verify and Preview

bash

# Start development server
pnpm dev

# Build check
pnpm build

Core Features

AI Chat Assistant

Built-in AI chat, supports multiple models. Configure the

aiChat

option in

nuxt.config.ts

MCP Server

Automatically exposes documentation as an MCP tool for AI assistants to access:

```
list-pages
```
- List all pages
```
get-page
```
- Get page content
```
list-examples
```
- List component examples
```
get-example
```
- Get component examples

LLM Optimization

Automatically generates

llms.txt

and

llms-full.txt

to optimize AI understanding of documentation.

Component Documentation Auto-Generation

Uses

nuxt-component-meta

to automatically extract Vue component Props, Slots, and Emits information.

GitHub Integration

Automatically detects Git repository information, providing:

"Edit on GitHub" link for pages
Commit history display
Last updated time

Checklist

When creating documentation pages, confirm:

Front-Matter includes
```
title
```
and
```
description
```
Title hierarchy starts with
```
##
```
(
```
#
```
is rendered by the system for the title)
MDC component syntax is correct (number of colons matches nesting level)
Code blocks are labeled with language identifiers and file names
There is a space between Chinese and English text
Use Chinese full-width punctuation
Images are placed in the
```
public/
```
directory

When configuring the project, confirm:

nuxt.config.ts

includes

extends: ['@movk/nuxt-docs']

Dependencies include

@movk/nuxt-docs

better-sqlite3

tailwindcss

Numeric prefixes are used for content files and directories that need sorting, name directly otherwise

create-docs

NPX Install

Tags

SKILL.md Content (Chinese)

Movk Nuxt Docs - Documentation Writing Guide

Project Overview

Reference Documents

Workflow

Step 1: Analyze the Project

Step 2: Understand Directory Structure

Step 3: Write Content

Step 4: Configure the Project

Step 5: Verify and Preview

Core Features

AI Chat Assistant

MCP Server

LLM Optimization

Component Documentation Auto-Generation

GitHub Integration

Checklist