Markdown for mdsvr 技能
生成一套完整、有效的多文件 Markdown 文档集，用于 mdsvr — 同时支持服务器模式和静态导出。
触发此技能时，输出多个** .md 文件**，形成一个风格统一的文档站点，严格遵守 mdsvr 的所有约定。
第一步 — 理解请求
在生成文件之前，从用户请求中提取以下信息：
- 主题/产品名称 — 要记录什么？
- 目标受众 — 开发者、最终用户、运维团队等。
- 范围 — 需要多少页面/章节？
- 语言 — 越南语、英语或双语？
- 是否需要图表？ — 如果是，请阅读
references/rules/mermaid.md了解语法规则。
如果以上任何信息不明确，请在继续之前提出一个聚焦的问题。
第二步 — 规划文件结构
在编写内容之前，设计一个逻辑层次结构。典型的 mdsvr 文档站点：
docs/
├── README.md ← 主页（必需）
├── 01-getting-started/
│ ├── README.md ← 章节索引
│ ├── 01-installation.md
│ ├── 02-quickstart.md
│ └── 03-configuration.md
├── 02-guides/
│ ├── README.md
│ ├── 01-basic-usage.md
│ └── 02-advanced.md
├── 03-api-reference/
│ ├── README.md
│ └── 01-endpoints.md
└── 04-troubleshooting.md
根据用户主题调整结构。可按需扩展或缩小。
第三步 — 应用 mdsvr 文件和链接规则（强制）
3.1 文件命名规则
| 规则 | ❌ 错误 | ✅ 正确 |
|---|---|---|
| 文件名中间不能有句点 | 0.1.quickstart.md | 01-quickstart.md |
| 文件名中间不能有句点 | config.v2.md | config-v2.md |
| 使用短横线命名（kebab-case） | GettingStarted.md | getting-started.md |
| 使用数字前缀排序 | guide.md (在侧边栏) | 01-guide.md |
| 文件名要描述性 | page1.md | installation.md |
| 目录索引文件必须为 | index.md | README.md |
3.2 链接结构规则
| 规则 | ❌ 错误 | ✅ 正确 |
|---|---|---|
| 仅使用相对路径 | [Guide](/docs/guide) | [Guide](./guide) |
链接中不能有 .md 扩展名 | [Setup](./setup.md) | [Setup](./setup) |
| 链接到目录，而不是 README | [Start](./01-getting-started/README) | [Start](./01-getting-started) |
| 锚点链接必须与标题匹配 | [See](#install-steps) (如果标题不存在) | 精确匹配 |
3.3 标题结构规则
| 规则 | ❌ 错误 | ✅ 正确 |
|---|---|---|
| 每个页面都需要 H1 | (页面以 H2 开头) | # 页面标题 作为第一个标题 |
| 不要跳过标题层级 | H1 → H3 | H1 → H2 → H3 |
| 标题必须具有描述性 | ## 第1节 | ## 安装要求 |
第四步 — 为每个文件添加前置元数据 (Frontmatter)
每个 .md 文件必须包含 YAML 前置元数据，用于 SEO 和 mdsvr 元数据：
---
title: "页面标题"
description: "对该页面内容的一句话描述。"
---
第五步 — 内容指南
README.md (主页) — 必需
- 必须存在于文档文件夹的根目录。
- 包含：项目概述、所有章节的快速导航链接。
- 如果合适，使用欢迎提示框。
章节 README.md (目录索引)
- 总结该章节涵盖的内容。
- 列出该章节中的所有页面，并使用相对链接。
内容页面
- 每个页面聚焦一个主题。
- 以简短介绍段落开头。
- 在适当的地方使用 MDX 组件：
:::note，:::warning，:::tip，:::danger用于提示框。- 使用编号列表进行分步操作步骤。
- 使用相对路径广泛链接到相关页面。
- 在有用时以“下一步”或“相关”部分结尾。
第六步 — Mermaid 图表 (需要时)
如果文档受益于图表（架构图、流程图、序列图、ERD、状态机等），请在相关的 .md 文件中内联嵌入 Mermaid 图表。
在生成任何图表之前，请阅读
references/rules/mermaid.md了解完整的语法参考和生成规则。该文件中的所有规则都是强制的。
快速检查清单 (来自 mermaid.md):
- 选择最合适的图表类型 — 不要默认使用
flowchart。 - 在流程图中始终声明方向：
flowchart TD或flowchart LR。 - 节点 ID：仅使用字母、数字、下划线。不能包含
-、.、(、)。 - 包含空格的节点标签必须使用双引号：
A["我的标签"]。 - 子图必须有明确 ID：
subgraph myid["标签"]。 - 序列图：在消息之前声明所有
participant行。 - 除非用户明确要求，否则不要使用硬编码的颜色或样式。
- 使用表情符号代替颜色来传达语义含义。
- 每个代码块一个图表；在输出之前验证语法。
第七步 — 创建文件并交付
使用 create_file 将每个 .md 文件写入文件系统。然后将其全部打包成 zip 文件，并调用 present_files，以便用户可以下载结果。
7.1 写入每个文件
对于规划结构中的每个文件，使用 create_file 在 /mnt/user-data/outputs/<项目名称>/ 下创建完整路径：
/mnt/user-data/outputs/我的项目/README.md
/mnt/user-data/outputs/我的项目/01-getting-started/README.md
/mnt/user-data/outputs/我的项目/01-getting-started/01-installation.md
...
在每次调用中写入完整、最终的内容 — 不要写入占位符。
7.2 打包并呈现
在所有文件写入完成后，将输出文件夹打包成 zip 文件并调用 present_files：
cd /mnt/user-data/outputs
zip -r 我的项目-docs.zip 我的项目/
然后使用 .zip 文件的路径调用 present_files。
7.3 在对话中总结
在 present_files 之后，在对话中写一条简短消息，包含：
- 文件树 — 显示生成的所有目录结构。
- 如何启动 — 一行命令：
npx mdsvr ./我的项目或mdsvr ./我的项目。 - 页面数量 — 例如：“生成了 3 个章节共 8 个页面。”
快速参考 — 要避免的常见错误
❌ 链接中使用绝对路径： [Page](/docs/page)
✅ 相对路径： [Page](./page)
❌ 链接中包含 .md 扩展名： [Page](./page.md)
✅ 无扩展名： [Page](./page)
❌ 链接到 README 文件： [Section](./01-section/README)
✅ 链接到目录： [Section](./01-section)
❌ 文件名中包含句点： 01.quickstart.md
✅ 使用连字符分隔： 01-quickstart.md
❌ 缺少 H1： ## 简介 (第一个标题是 H2)
✅ 以 H1 开头： # 简介
❌ 跳过的标题层级： # 标题 → ### 子标题 (跳过 H2)
✅ 正确的层级结构： # 标题 → ## 章节 → ### 子章节
❌ 没有前置元数据： (文件直接以 # 开头)
✅ 有前置元数据： --- title: "..." description: "..." ---
参考文件
references/rules/mermaid.md— 所有 19 种图表类型的完整 Mermaid v11 语法参考。任何时候在文档中需要任何图表时，请阅读此文件。