文档编写

446 字约 1 分钟

本文说明如何为 MaaKEDR 文档站（VuePress Theme Plume）编写与修改文档。

目录约定

docs/
├── README.md           # 语言选择首页
├── zh/                 # 简体中文
│   ├── README.md
│   ├── manual/         # 用户手册
│   ├── develop/        # 开发文档
│   └── protocol/       # 任务/资源协议
└── en/                 # English（结构与 zh 对齐）

路径与站内链接使用正斜杠
侧边栏在 docs/.vuepress/config/navigation.ts 的 collections.sidebar 中维护
新增页面后请同步修改 中英文 sidebar（若有英文对照）

Frontmatter

常用字段：

---
order: 1
icon: ri:tools-fill
title: 可选标题
---

目录索引页可用：

---
title: 开发文档
icon: ph:code-bold
dir:
    order: 1
---

提示容器

Plume 支持容器语法：

注

注释

提示

注意

警告

危险

详情

折叠详情

也可用 GitHub 风格（渲染取决于主题配置）：

> [!NOTE]
> 说明文字

MarkdownLint 规范

文档需符合 MarkdownLint 规范，配置见 docs/.markdownlint.yaml（规则覆盖、关闭项及原因均在其中注明）。

规则说明请参考 MarkdownLint 规则
可使用 VSCode 插件实时提示（自动读取 .markdownlint.yaml）
与 Prettier 的分工：Prettier 负责格式（缩进、换行、表格对齐），MarkdownLint 负责规范（标题层级、列表正确性、链接有效性等）。两者不冲突：.markdownlint.yaml 中已关闭与 Prettier 无关的噪音规则（如 MD013 行长）

写作要求

用户手册：步骤可操作，选项与 tasks/*.json 一致
开发文档：路径、命令与仓库现状一致；避免写已废弃的 CLI/工具
协议文档：描述约定与节点关系，细节以 JSON 为准并给文件路径
发版相关：interface.json 的 version / title 需手动改（见 AGENTS.md Release Guidelines）

本地预览

pnpm docs:dev
pnpm docs:build

构建产物在 docs/.vuepress/dist（已 gitignore）。