Scan to join WeChat groupdev-docs —— Docs/ 排版与结构
适用：新建、编辑、整理项目 Docs/ 下的 .md。本技能只管排版与结构；功能文档的内容与生产流程见 writing-functional-docs。
一、禁序号（最高优先级）
标题、目录名、列表项一律不带序号（1. 2.1 第一章 01-）。唯一例外是操作步骤——顺序错就会失败的，才用有序列表。
| 禁止 | 改为 |
| --- | --- |
| # 2.1 大厅设定 | # 大厅设定 |
| ## 3.2.1 功能说明 | ## 功能说明 |
| 01-设计核心目标/ | 设计核心目标/ |
| 1. 用户管理 / 2. 权限控制 | - 用户管理 / - 权限控制 |
| 1. 打开设置 2. 点击保存 3. 确认退出 | 保留有序（真步骤） |
二、标题
- 一篇文档只有一个
#；层级连续，不跳级（#之后不能直接###）。 - 标题文字前后不留空格，标题内不留序号。
三、Obsidian 元素
| 元素 | 规范 |
| --- | --- |
| 内部文档链接 | [[文档名]]（不含 .md）；带别名 [[文档名\|显示文字]] |
| 标签 | frontmatter tags: [VR, 设计文档]（半角逗号），3–5 个；分层用 /，如 系统/社交 |
| Callout | > [!NOTE] [!TIP] [!IMPORTANT] [!WARNING] [!ERROR]，下一行起写正文 |
| 代码块 | 三反引号 + 语言标识；行内代码用单反引号 |
| 其它 | 强调 **粗体**、表格用标准 Markdown 语法、外部链接 [文字](URL) |
相关文档：文末列「相关文档」的 [[…]]；A 引用了 B，就给 B 补上反向链接（双向）。
四、目录结构
- 顶层按用途分，名字随项目走（实测常见：
功能/设计/规范/须知/归档/MOCs/），不要硬凑一套固定分类。 - 代码相关功能统一走三文件：
Docs/功能/模块/<模块名>/下放配置.md、示例.md、API.md。
| 文件 | 写什么 |
| --- | --- |
| 配置.md | 概述、环境要求、依赖项、配置字段表 |
| 示例.md | 快速开始、典型场景、带注释的代码片段 |
| API.md | 类/接口、方法签名、参数与返回值、事件 |
- 三个文件都带 frontmatter
tags；模块之间用 wikilink 互连；模块文件夹名不带序号。 - 需要更多分类（框架、组件、任务步骤…）时按项目实际添加，不强制。
五、文件命名
小写字母/数字/连字符（user-auth-flow.md），或语义清晰的中文名（用户认证流程.md）；不用空格与特殊字符。
六、交付前自检
- [ ] 标题、目录名、列表无序号（真步骤除外）
- [ ] 只有一个
#，层级连续 - [ ] 相关文档有
[[wikilink]]，文末有 3–5 个 tag（半角逗号） - [ ] 功能模块三文件齐全（配置 / 示例 / API）
- [ ] 文件名无空格与特殊字符
- [ ] 只动格式：不改原意、不删内容、不加原文没有的东西