| 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 级
- 滥用列表代替段落
嵌套列表:
代码块
必须标注代码语言类型:
git status
def hello():
print("Hello")
行内代码使用反引号:variable、function()、file.md
表格规范
表格用于呈现多维度需对比的数据。
应使用表格的场景:
- 需要横向对比多个项目
- 数据具有明确的列属性
- 信息结构化为行记录
应避免的场景:
- 仅是简单的名词-定义对应(用列表代替)
- 两列且无对比需求
- 单元格内容过长
基本格式:
规范:
- 表头加粗
- 列对齐使用冒号(
:--、:--:、--:)
- 内容简洁,避免单元格过长
链接规范
外部链接:[链接文本](https://example.com)
内部链接:使用相对路径 [文档](./docs/guide.md)
加粗规范
加粗用于强调关键词,避免过度使用。
应使用加粗的场景:
- 首次定义关键术语
- 强调重要的操作或警告
- 引导注意力到关键信息
应避免的场景:
块引用:> 使用块引用标注重要提示、警告或引用内容
引号规范
中文文档使用中文引号:
- 直接引用:「这是引用内容」或「这是引用内容」
- 术语引用:「变量名」
应使用引号的场景:
- 直接引用他人的话语或文本
- 引用特定术语或概念名称(首次定义时)
- 强调某个词汇的特殊含义或用法
- 标注按钮、菜单项等界面元素名称
应避免的场景:
- 包裹所有术语名词
- 用于普通词汇的强调(用加粗代替)
- 在列表项或标题中频繁使用
- 包裹整个句子或段落作为"引用"
替代方案:
- 普通强调使用加粗:关键信息
- 术语使用行内代码:
variable
- 大段引用使用块引用:> 引用内容