用途
该技能用于将 Google Markdown 风格指南的约定应用到文档中，帮助创建可读、可移植且易于维护的 Markdown 文档，使不同项目之间的格式保持一致。当用户要求“格式化 markdown”“编写 markdown 文档”“遵循 markdown 风格指南”“应用 markdown 约定”等时，应使用该技能。
核心原则
该技能平衡三个目标：
- 源文本可读且可移植：纯文本应易于阅读。
- 语料可维护：跨团队和跨时间保持一致的格式。
- 语法简单：易于记忆和应用。
主要能力
文档结构
每个 Markdown 文档应遵循以下布局：
# Document Title
Short introduction (1-3 sentences providing high-level overview).
[TOC]
## Topic
Content.
## See also
* https://link-to-more-info
关键元素：
- H1 标题：第一个标题为 1 级，与文件名匹配或相似。
- 简介：为新手提供简要概述。
- [TOC]：简介之后的目录（如果托管平台支持）。
- H2+ 标题：所有后续标题从 2 级开始。
- See also：底部的杂项链接。
标题
使用 ATX 风格标题：
# Heading 1
## Heading 2
### Heading 3
最佳实践：
- 添加间距：标题前后各留一个空行。
-
后加空格：
## Heading而非##Heading。 - 为每个标题使用唯一、描述性的名称。
- 每个文档只有一个 H1 标题（即文档标题）。
- 标题使用句子大小写。
示例：
## Foo
### Foo summary
### Foo example
## Bar
### Bar summary
### Bar example
列表
嵌套列表间距——使用 4 空格缩进：
1. First item (2 spaces after number).
Wrapped text uses 4-space indent.
2. Second item.
* Bullet item (3 spaces after asterisk).
Wrapped text uses 4-space indent.
1. Nested numbered item.
8-space indent for wrapped text.
2. Another nested item.
* Back to bullets.
长列表使用惰性编号：
1. First item.
1. Second item.
1. Nested item.
1. Another nested item.
1. Third item.
代码
行内代码——短代码使用反引号：
Run `script.sh` to start the process.
Check the `field_name` in the table.
代码块——使用带语言标注的围栏代码块：
def foo(bar):
return bar * 2
最佳实践：
- 始终声明语言。
- 使用围栏代码块，而非缩进代码块。
- 在 shell 命令中用 \ 转义换行。
- 在列表中嵌套代码块时使用正确的缩进。
链接
行内链接：
See the [Markdown guide](markdown.md) for more info.
长 URL 或重复链接使用引用式链接：
See the [style guide] for details.
[style guide]: https://google.github.io/styleguide/docguide/style.html
最佳实践：
- 使用有信息量的链接标题（不要用“here”或“link”）。
- 使用显式路径，避免 ../ 相对路径。
- 在首次使用之后、下一个标题之前定义引用式链接。
- 在表格中使用引用式链接以保持单元格可读。
行长度
遵循 80 字符行长度限制，以便更好地集成工具和进行代码审查。
例外：
- 链接
- 表格
- 标题
- 代码块
示例：
* See the
[documentation](https://very-long-url.example.com/path/to/docs).
for more details.
表格
对于需要快速浏览的表格数据使用表格。对于更适合用列表呈现的数据则避免使用表格。
适合使用表格的情况：
- 数据分布均匀。
- 许多平行项目具有不同属性。
- 需要快速比较。
示例：
Transport | Favored by | Advantages
--------- | ---------- | -----------
Swallow | Coconuts | Fast when unladen
Bicycle | Miss Gulch | Weatherproof
使用引用式链接以保持表格单元格易于管理。
行尾空白
不要使用行尾空白。使用反斜杠进行换行：
This line needs a break,\
so it continues here.
更好的做法：通过段落分隔（双换行）完全避免使用 <br />。
快速参考
标题：
- ATX 风格：
# H1、## H2、### H3 - 前后添加空行
- 每个文档一个 H1
列表：
- 所有嵌套内容使用 4 空格缩进
- 惰性编号：长列表中所有项目使用
1.
代码：
- 行内：
`code` - 代码块：```language，并指定语言
链接：
- 有信息量的标题
- 长/重复 URL 使用引用式链接
行长度：
- 80 字符（链接、表格、标题、代码除外）
空白字符：
- 无行尾空白
- 如需要，使用 \ 进行换行
常见错误
应避免：
- 不要使用 setext 风格标题：
Heading
-------
- 不要写含糊的链接标题：
Click [here](url) for more info.
- 不要使用缩进代码块：
code without language specified
- 不要使用不一致的间距进行嵌套：
* Item
* Badly indented nested item
应使用：
- 使用带间距的 ATX 风格标题：
## Heading
- 编写描述性链接标题：
See the [installation guide](url) for setup instructions.
- 使用带语言的围栏代码块：
print("Hello")
- 使用一致的 4 空格嵌套：
* Item
* Properly indented nested item
附加资源
参考文件：
references/style-guide.md：完整的 Google Markdown 风格指南，包含所有规则、示例和边缘情况。
另请参阅：
- Google Markdown Style Guide
- CommonMark Specification
适用场景
适用于需要按照统一风格编写或格式化 Markdown 文档的场景，例如项目文档、README、技术说明、风格指南遵循等。
限制
资料中未提供关于该技能的具体安装方式、平台支持、收费情况或效果保证等信息。