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
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),若有冲突,以本文为准。
# 参考资料
- 技术文档写作规范(Markdown) (opens new window)
- 文案风格指南 | LeanCloud 开放资源 (opens new window)
- 余光中:怎样改进英式中文?- 论中文的常态与变态 | LeanCloud 开放资源 (opens new window)
- 为什么文件名要小写? - 阮一峰的网络日志 (opens new window)
- Google developer documentation style guide (opens new window)
- Basic writing and formatting syntax - GitHub Docs (opens new window)
在 GitHub 中编辑此页 (opens new window)
上次更新于: 2022/10/26 23:50:01