文档撰写规范

本站文档基于 Nuxt Content 构建，使用 Markdown（MDC 语法）编写。本页面汇总了撰写文档时需要遵循的规范和常用语法。

文件结构

文档源文件位于 content/ 目录下，通过数字前缀控制排序和路由：

content/
  1.docs/
    1.getting-started/
      1.index.md          → /docs/getting-started
      3.usage.md          → /docs/getting-started/usage
      4.writing-guide.md  → /docs/getting-started/writing-guide
    3.developer/
      1.index.md          → /docs/developer

命名规则：

• 使用 数字.文件名.md 格式，数字决定侧边栏排序
• 文件名使用小写英文和连字符（kebab-case）
• 每个目录可放置 .navigation.yml 自定义导航标题和图标

Front Matter

每个 .md 文件顶部必须包含 YAML Front Matter：

---
title: 页面标题
description: 页面描述，用于 SEO 和摘要展示
navigation:
  icon: i-lucide-house # 侧边栏图标（Lucide 图标集）
---

必填字段：title、description

图标可从 Lucide Icons 中选择，使用 i-lucide- 前缀。

Markdown 基础语法

标准 Markdown 语法均可使用，包括标题、列表、链接、图片、代码块、表格等。

完整语法参考：Nuxt Content - Markdown

标题层级

文档内容从 ## 二级标题开始（一级标题由 title 字段自动生成），最深使用到 ####：

## 二级标题

### 三级标题

#### 四级标题

内部链接

站内链接使用相对路径，不要写完整 URL：

[会员页面](/pricing)
[开发者文档](/docs/developer)

代码块

行内代码使用反引号，代码块指定语言以启用高亮：

行内：`nuxt.config.ts`

代码块：

```ts
export default defineNuxtConfig({
  modules: ['@nuxt/content']
})
```

更多代码块特性（行高亮、文件名、diff 等）参考：Nuxt Content - Code Highlighting

MDC 组件语法

MDC（Markdown Components）是 Nuxt Content 的扩展语法，允许在 Markdown 中使用 Vue 组件。

完整 MDC 语法参考：MDC Syntax

Callout（提示框）

用于高亮提示、警告等重要信息：

::callout{icon="i-lucide-info" color="info"}
这是一条提示信息。
::

::callout{icon="i-lucide-triangle-alert" color="warning"}
这是一条警告信息。
::

可用颜色：info、success、warning、error、neutral

组件属性

MDC 组件属性使用花括号语法：

::component-name{prop1="value1" prop2="value2"}
内容区域
::

注意事项：

• 属性紧跟组件名，中间不能有空格或换行
• 属性值用双引号包裹
• :: 开头的是块级组件，: 开头的是行内组件

撰写规范

语言与风格

• 使用简体中文撰写，技术术语保留英文原文（如 API、SDK、CI/CD）
• 语气保持简洁直接，面向用户而非开发者内部
• 避免过长段落，每段控制在 3-5 句话以内

格式约定

图片

• 图片放在 public/ 目录下，使用绝对路径引用
• 提供有意义的 alt 文本
• 大图建议压缩后上传

![应用市场截图](/images/app-store.png)

参考链接

以下是编写文档时常用的 Nuxt 官方文档参考：

• Nuxt Content 文档 — 内容管理框架总览
• Markdown 语法 — 支持的 Markdown 语法与扩展
• MDC 语法 — 在 Markdown 中使用 Vue 组件
• 代码高亮 — 代码块高亮与行标注
• Nuxt UI 组件 — UI 组件库文档