create-docs

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Movk Nuxt Docs - 文档编写指南

Movk Nuxt Docs - Documentation Writing Guide

使用 Movk Nuxt Docs 创建文档站点时，遵循本指南以确保内容结构规范、组件使用正确。

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 是基于 Nuxt 4 的文档主题，采用 Layer 架构。核心技术栈：

Nuxt 4 + Nuxt Content - 框架和内容管理
Nuxt UI - 组件库（Prose 组件用于 Markdown）
Tailwind CSS 4 - 样式系统
MDC 语法 - Markdown 中使用 Vue 组件

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

根据当前任务按需加载，不要一次全部加载：

文件	内容	何时加载
`references/mdc-components.md`	MDC 组件用法和模板	编写 Markdown 内容时
`references/configuration.md`	nuxt.config.ts 和 app.config.ts 配置	配置项目时
`references/writing-guide.md`	内容结构和写作规范	创建新页面或组织内容时

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

第 1 步：分析项目

Step 1: Analyze the Project

检查现有项目结构：

bash

undefined

Check the existing project structure:

bash

undefined

检查是否已安装 Movk Nuxt Docs

Check if Movk Nuxt Docs is installed

cat package.json | grep "@movk/nuxt-docs"

检查内容目录

Check content directories

ls content/ ls content/docs/


如果是新项目，使用模板创建：

```bash

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

undefined

npx nuxi init -t gh:mhaibaraai/movk-nuxt-docs/templates/module my-module-docs

undefined

第 2 步：理解目录结构

Step 2: Understand Directory Structure

标准项目结构：

my-docs/
├── app/
│   ├── app.config.ts            # 应用配置（主题、Header、Footer 等）
│   ├── components/              # 自定义组件（覆盖 Layer 默认组件）
│   └── composables/             # 自定义 Composables
├── content/
│   ├── index.md                 # 首页
│   ├── releases.yml             # 发布日志（可选，自动检测）
│   └── docs/                    # 文档页面
│       ├── 1.getting-started/
│       │   ├── 1.index.md
│       │   └── 2.installation.md
│       ├── 2.guide/
│       │   └── 1.usage.md
│       └── 3.api/
│           └── 1.reference.md
├── public/                      # 静态资源
├── nuxt.config.ts               # Nuxt 配置
└── package.json

文件命名规则：

需要控制排序时使用数字前缀：
```
1.index.md
```
、
```
2.installation.md
```
无需排序的文件直接命名：
```
troubleshooting.md
```
、
```
ai-chat.md
```
目录同理：需要排序用
```
1.getting-started/
```
，否则直接命名
数字前缀不会出现在 URL 中

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

第 3 步：编写内容

Step 3: Write Content

加载

references/mdc-components.md

了解可用组件。

每个 Markdown 文件需要 Front-Matter：

---
title: 页面标题
description: 页面描述，用于 SEO 和搜索。
---

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

正文内容...


**可选 Front-Matter 字段：**

| 字段 | 说明 |
|------|------|
| `title` | 页面标题 |
| `description` | 页面描述 |
| `navigation.title` | 导航中显示的标题（可与 title 不同） |
| `navigation.icon` | 导航图标（如 `i-lucide-book`） |
| `category` | 页面分类 |
| `seo.title` | SEO 标题（覆盖 title） |
| `seo.description` | SEO 描述（覆盖 description） |

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) |

第 4 步：配置项目

Step 4: Configure the Project

加载

references/configuration.md

了解详细配置选项。

基础

nuxt.config.ts

：

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

  // AI 聊天（可选）
  aiChat: {
    model: 'openai/gpt-5-nano',
    models: ['openai/gpt-5-nano'],
  },

  // MCP Server（可选）
  mcp: {
    name: 'My Docs'
  }
})

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'
  }
})

第 5 步：验证和预览

Step 5: Verify and Preview

bash

undefined

bash

undefined

启动开发服务器

Start development server

pnpm dev

构建检查

Build check

pnpm build

undefined

pnpm build

undefined

核心功能

Core Features

AI 聊天助手

AI Chat Assistant

内置 AI 聊天，支持多模型。在

nuxt.config.ts

配置

aiChat

选项。

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

aiChat

option in

nuxt.config.ts

MCP Server

自动暴露文档为 MCP 工具，供 AI 助手查阅：

```
list-pages
```
- 列出所有页面
```
get-page
```
- 获取页面内容
```
list-examples
```
- 列出组件示例
```
get-example
```
- 获取组件示例

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 优化

LLM Optimization

自动生成

llms.txt

和

llms-full.txt

，优化 AI 对文档的理解。

Automatically generates

llms.txt

and

llms-full.txt

to optimize AI understanding of documentation.

组件文档自动生成

Component Documentation Auto-Generation

使用

nuxt-component-meta

自动提取 Vue 组件的 Props、Slots、Emits 信息。

Uses

nuxt-component-meta

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

GitHub 集成

GitHub Integration

自动检测 Git 仓库信息，提供：

页面「在 GitHub 上编辑」链接
提交历史展示
最后更新时间

Automatically detects Git repository information, providing:

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

检查清单

Checklist

创建文档页面时确认：

Front-Matter 包含
```
title
```
和
```
description
```
标题层级从
```
##
```
开始（
```
#
```
由系统渲染 title）
MDC 组件语法正确（冒号数量匹配嵌套层级）
代码块标注了语言标识符和文件名
中英文之间有空格
使用中文全角标点
图片放在
```
public/
```
目录

配置项目时确认：

nuxt.config.ts

包含

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

依赖包含

@movk/nuxt-docs

、

better-sqlite3

、

tailwindcss

需要排序的内容文件和目录使用数字前缀，无需排序的直接命名

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