Warning
本指南仍在编写中，内容可能不完整。
介绍
Tip
前置知识： 无
本指南主要介绍在团队文档库中撰写文档时，Markdown 文档的书写风格。
实际上，Markdown 是一种非常灵活的文档格式，其语法规则由多种不同的 Markdown 解析器定义。许多解析器有其自己的语法规则，但它们都遵循 Markdown 的基本语法。本团队常用的、使用 Markdown 语法进行文档渲染的解析器/编辑器/技术栈包括 GitHub, Obsidian, Mkdocs。
因此，本指南将介绍在上述解析器中书写 Markdown 文档时，基本能保持一致的书写风格，以确保文档在不同解析器中渲染效果类似。不同解析器特有的语法规则，将不在此指南的讨论范围内。
语法规则
标题
Tip
我们的团队文档中：
- 不使用
#来定义一级标题，而是使用title:属性来定义标题。因为#在许多 Markdown 解析器中会被解析为标题样式，这会导致渲染效果不一致。- 不要使用
===或---来定义标题，因为它们在某些解析器中可能无法正常工作。- 尽量不使用四级及以上的标题，因为它们导致过于冗长和复杂的层级，不利于阅读。
引用
引用使用 > 符号：
这是一个普通引用
对于重要提示，使用 callout 语法（也视为一种引用），为保持与 GitHub 的引用语法一致，我们推荐最常用的五种 Callout 语法：
> [!NOTE]
>
>
> 用于补充说明
> [!TIP]
>
>
> 用于提供建议
> [!IMPORTANT]
>
>
> 用于强调重要内容
> [!WARNING]
>
>
> 用于警告信息
> [!CAUTION]
>
>
> 用于危险操作警告对于代码块，推荐使用三个反引号来定义：
指定语言类型列表
- 有序列表使用数字加点
- 子列表使用减号
- 保持缩进对齐
- 无序列表使用减号
- 列表项之间空一行
- 保持同类项的符号一致
表格
Warning
表格的语法过于复杂，因此不建议使用超过 3 列的表格。尽量使用列表来替代表格。
- 使用标准的表格语法
- 表头使用连字符分隔
- 对齐方式使用冒号指定
| 左对齐 | 居中 | 右对齐 |
|:--|:--:|--:|
| 内容 | 内容 | 内容 |链接
- 内部链接使用双方括号：
[[文档名称]] - 内部链接并使用别名：
[[文档名称 | 别名]] - 内部链接并引用至标题：
[[文档名称#标题名称|标题名称]] - 外部链接使用方括号加圆括号：
[显示文本](URL) - 可以为链接添加标题：
[显示文本](URL "标题")
图片
- 使用标准的图片语法：
 - 本地图片建议使用相对路径
- 网络图片使用完整URL
常见问题
Warning
我们使用 Markdownlint 来检查文档的格式问题。这个工具会自动修复一些问题，但有些问题需要手动修复。以下是一些常见问题：
- 标题层级问题: (M025) 文档只使用一个一级标题（title属性）
- 列表缩进问题: (M032) 段落与列表项之间空一行
- 正确使用标题: (M036) 不要使用加粗来定义标题