docs-format

name	docs-format
description	操作Markdown文档时使用。文档格式技能，遵循量潮科技文档格式标准，用于生成或检查规范文档。

文档格式技能

CHANGELOG 格式

子模块版本标注

主仓库 CHANGELOG 中涉及子模块更新的条目，必须标注目标 tag 版本号：

### 变更
- 更新子模块：qtadmin(v0.2.0)、tutorial(v0.0.3)、roadmap(v0.0.2)

版本号来源于子模块自身的 git tag。未发布的子模块用 commit SHA 前 7 位代替。

遵循 量潮科技文档格式标准

写作原则

• 删：删除不必要的格式元素，优先用段落和标题
• 简：能用列表就不表格，能用文字就不列表
• 少：全文格式元素（分隔线、表格、加粗）尽量少
• 一：同一概念全程使用相同名称

标题规范

• 最多使用三级标题（# / ## / ###）
• 避免在标题中使用标点符号
• 标题应简洁，明确概括内容
• 一级标题仅文档标题使用一次

分隔线规范

分隔线（---）用于划分文档主要部分：

• 优先用空行+标题区分章节
• 分隔线仅用于重要划分点
• 全文最多使用 3 处

列表规范

无序列表（-）适用于：

• 并列的多个要点
• 不分先后顺序的内容
• 短小的条目

有序列表（1.）适用于：

• 有明确顺序的步骤
• 需要编号的操作流程
• 排名或优先级

避免场景：

• 列表项过长（超过两行）
• 嵌套超过 2 级
• 滥用列表代替段落

嵌套列表：

• 缩进使用 2 个空格
• 嵌套层级不超过 2 级

代码块

必须标注代码语言类型：

git status

def hello():
    print("Hello")

行内代码使用反引号：variable、function()、file.md

表格规范

表格用于呈现多维度需对比的数据。

应使用表格的场景：

• 需要横向对比多个项目
• 数据具有明确的列属性
• 信息结构化为行记录

应避免的场景：

• 仅是简单的名词-定义对应（用列表代替）
• 两列且无对比需求
• 单元格内容过长

基本格式：

列1	列2	列3
左对齐	居中	右对齐

规范：

• 表头加粗
• 列对齐使用冒号（:--、:--:、--:）
• 内容简洁，避免单元格过长

链接规范

外部链接：[链接文本](https://example.com)

内部链接：使用相对路径 [文档](./docs/guide.md)

加粗规范

加粗用于强调关键词，避免过度使用。

应使用加粗的场景：

• 首次定义关键术语
• 强调重要的操作或警告
• 引导注意力到关键信息

应避免的场景：

• 标记所有术语名词
• 连续多个加粗
• 在列表项内部使用

块引用：> 使用块引用标注重要提示、警告或引用内容

引号规范

中文文档使用中文引号：

• 直接引用：「这是引用内容」或「这是引用内容」
• 术语引用：「变量名」

应使用引号的场景：

• 直接引用他人的话语或文本
• 引用特定术语或概念名称（首次定义时）
• 强调某个词汇的特殊含义或用法
• 标注按钮、菜单项等界面元素名称

应避免的场景：

• 包裹所有术语名词
• 用于普通词汇的强调（用加粗代替）
• 在列表项或标题中频繁使用
• 包裹整个句子或段落作为"引用"

替代方案：

• 普通强调使用加粗：关键信息
• 术语使用行内代码：variable
• 大段引用使用块引用：> 引用内容