文档规范
Markdown 规范

Markdown 规范

本文规定了文档撰写时必须遵守的 Markdown 规范。

# 1 文档结构与命名

文件夹需以中文命名，Markdown 文件需以英文命名。
- 英文命名时，用 - 连接单词，不要用 _。
- 英文命名时，建议使用小写字母（README.md 除外）。
一级目录表示专栏，二级、三级目录表示文章分类，不能超过三级目录。
除一级目录和首页文件 README.md 外，其他目录和文件必须加上序号，如 01.JS 部分、03.js-advanced-155.md 等。
- README.md 文件（如有）的序号必须为 00。

# 2 Front Matter

文档的 Front Matter 必须使用 yaml 格式，且至少包含 title、lang、date、permalink 四个字段。

title 字段表示文档的标题，必须为中文（且无序号）。
lang 字段表示文档的语言，必须为 zh-CN。
date 字段表示文档的创建时间，格式为 YYYY-MM-DD HH:mm:ss（自动创建，无需修改）。
permalink 字段表示文档的 URL，必须以 / 开头、结尾，如 /standard/markdown/。

注意

permalink 的层级必须与文档的目录层级一致，README.md 的层级与其所在目录层级一致。

---
title: Markdown 规则
lang: zh-CN
date: 2022-10-23 16:23:47
permalink: /standard/markdown/
---

1
2
3
4
5
6

# 3 标题

文档中的标题必须使用 # 标题，不要使用 =、- 等标题。
文档中不要出现 h1 标题，即 # 标题。
不能超过 h4 标题，即 #### 标题，h4 标题下仍有分支时，使用有序列表或加粗代替。
文档中的标题 原则上 应按顺序使用，不要越级使用。
文档中的标题推荐使用序号，并与标题层级一致，如 ## 1 标题、### 1.1 标题。
标题应当避免孤立编号（即同级标题只有一个），避免上下级标题重名。

# 4 正文

正文使用 Markdown 语法撰写，请先阅读中文排版规则和 Markdown 基本语法。

# 4.1 符号规定

必须使用 ** 和 * 表示加粗和斜体，不要使用 __ 和 _。
必须使用 --- 表示分割线，不要使用 *** 或 +++。
必须使用 - 表示无序列表，不要使用 * 或 +。
有序列表的数字必须与实际序号一致。

# 4.2 链接与图片

内部链接必须使用根路径开始的相对路径，如 [/standard/markdown/](/standard/markdown/)。
外部链接推荐使用 Markdown 语法，而非 HTML 语法，如 [百度](https://www.baidu.com)。
纯链接必须使用尖括号包裹，如 <https://www.baidu.com/>。
图片推荐使用图床，而非本地图片。

# 4.3 代码

详见代码规范。

# 4.4 语言风格

应当避免错别字、语法错误、易引起歧义的表达等。

# 5 参考资料

推荐在文档中注明参考资料，如本文文末的参考资料。

全文的参考资料推荐放在文末，并使用 h2 标题（可以不加序号）。
某部分的参考资料推荐放在该部分的末尾，不要使用标题，使用 参考： 注明。
参考资料推荐使用无序列表。
对于链接类的参考资料，使用 []() 语法和 <> 语法均可。

# 6 其他

未尽事宜，参见技术文档写作规范（Markdown） (opens new window)，若有冲突，以本文为准。

# 参考资料

在 GitHub 中编辑此页

上次更新于: 2022/10/26 23:50:01

← 代码规范 Markdown 基本语法→