https://github.com/kenpusney/markdown-style-guide
Markdown 风格指南
https://github.com/kenpusney/markdown-style-guide
Last synced: 9 months ago
JSON representation
Markdown 风格指南
- Host: GitHub
- URL: https://github.com/kenpusney/markdown-style-guide
- Owner: kenpusney
- License: cc0-1.0
- Created: 2020-02-23T10:46:50.000Z (almost 6 years ago)
- Default Branch: master
- Last Pushed: 2020-02-23T11:45:09.000Z (almost 6 years ago)
- Last Synced: 2025-03-24T01:33:51.630Z (10 months ago)
- Homepage:
- Size: 11.7 KB
- Stars: 11
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Markdown 风格指南
> 本文档主要讲述了 Markdown 作为富文本基础格式的时候编写专业文档时应当采取的格式，
> 读者应当具备一些基础的 Markdown 知识，了解 Markdown 各种内嵌样式和块状样式的用法和区别。
> 关于 Markdown 文档的详细规范，可以参考 CommonMark 规范。
> 中文文本的排版格式，参考 GitHub《中文文案排版指北》。
[TOC]
## 目标
本指南主要有以下几个目标：
- **一致性**：保证在遵循 CommonMark 标准的同时，使用更严格的规范来统一风格，避免因为风格导致的奇异解读；
- **可读性**：在源码模式下依然能够正确地掌握和理解文档的结构，清晰阅读文档的内容；
- **易理解**：通过控制内容的结构和颗粒度，让读者更容易理解和掌握文档的信息。
## 结构
通常来说标准的文档结构如下：
```markdown
# 标题
简介
[TOC]
## 分节
分节内容。
## 参考
- https://example.com
```
- `# 标题` 对于有额外标题区域的文档（如微信公众号等），标题部分在正文内容中可以省略
- `[TOC]`如果使用的文档平台支持自动生成目录，那 [TOC] 节最好加上
- `## 分节`所有除文档标题外的分节标题都应该从 2 级标题开始，每一级的子分节只能有一层标题递增
- `## 参考`参考区域可以作为给读者获取更多信息的指导内容，放置一些相关的备注和链接。
## 字符限制
Markdown 文档对换行符不敏感，对于非连续换行，会尝试通过尾部字符（英文句号）来决定是否拆分段落。
所以尽可能按照项目源码规范（比如 80 字符一行）来选择拆行，这样既不失文档的标准性，
又能在非渲染模式下可以正常阅读。
字符数较长的 URL 链接和表格除外。
要这样做：
```markdown
你可以这样来安排一个段落，
其实看起来不会差太远。
但是如果有一个[占据空间非常大非常长的链接](https://https://gerrit.googlesource.com/gitiles/+/master/Documentation/markdown.md)。
就让他保持那么长吧。
```
## 尾部空格
尽量不要在尾部加两个空格来进行换行。
大部分行尾的空格会被一些编辑器给忽略掉，造成不必要的麻烦。
如果需要切分段落，通过额外一个空行来实现。
要这样做：
```markdown
这是第一段。
这是第一段的第二句。
这是第二段。跟第一段之间记得空一行。
```
## 标题
### 尽量使用`#`来写标题
Markdown 虽然支持`===`和`---`来表示一级标题和二级标题，但因为其区分比较让人迷惑
（你第一反应是`---`是一级标题还是二级标题？），并且丢失了跟其他层级标题的一致性。
要这样做：
```markdown
## 这样才是一个标准的标题
```
不要这样做：
```markdown
别这样做，因为你很难确定这是第几层标题
----
```
### 标题的空白处理
`#`之后要添加一个空格，标题前后各空一行。
`#`前不要添加空格。
空白能够更加突出标题，提升文档源码的可读性。
要这样做：
```markdown
## 标题
段落
## 另一个标题，跟前面要空一行
另一个段落，跟标题之间要空一行。
```
不要这样做：
```markdown
## 标题前面多出来个空格
##内容跟标题之间挨得紧密，中间也没留空白
内容紧接着标题。
```
### 标题中的标点
标题尾部不要出现任何类似句号或者冒号的标点。标题会作为目录的一部分，目录中出现尾部标点会显得十分的滑稽。
要这样做：
```markdown
## 参考
- [参考链接](https://example.com)
```
不要这样做：
```markdown
## 参考：
## 这是下文的一个主要观点。
```
## 列表
### 尽量保持列表项内容简短
如果列表项内容需要多句话描述完，考虑拆分成更深一级的子分节来表示。
### 避免太长（列表项太多）的列表
通常一个列表不要超过 4 项。除非内容主题就是列举项目（比如购物清单等），否则请尝试其他展示形式（比如图表、流程等）。
不要这样做：
```markdown
1. xxx
2. yyy
...
19. zzz
```
### 列表缩进
顶层列表的引导符号要顶行书写。
在列表引导符号后添加一个空格。
次一级的内嵌列表，引导符号与前一级的内容对齐，保证层次感。
要这样做：
```markdown
- 第一层
- 第二层
- 第三层
- 回到第二层
1. 有序列表也是这样
1. 看起来会更清晰
1. 层级明确并且不会导致缩进混乱。
```
不要这样做：
```markdown
- 第一层符号前面空了几格
- 下一层紧挨着上一层
- 再下一层多缩进了了几格
```
### 列表项要突出重点
如果列表项内容超出了一句话，尽量通过简短的摘要或总结在列表项之前突出重点。
## 引用
`>` 与引用内容之间使用一个空格分隔，`>`之前不能有空格。
引用内容的每一行都要使用`>`，包括空行。
引用应该是作为正文的补充说明引入，不应该有太多的内容。如果引用内容超过了半屏显示，容易中断读者关注正文的上下文。这种时候尽量把引用通过链接的方式引入。
要这样做：
```markdown
> 学医救不了中国人。
>
> —— 鲁迅
```
不要这样做：
```markdown
> 空格打头，
>与内容之间没有间隔，
> 与内容之间间隔太多，
> 跳过了一个空行。
> —— 鲁迅
```
## 代码块
代码块与上下文之间要有空行间隔。
使用隔离式代码块(` ``` `)时，尽量加上语言标签。
要这样做：
参考以下代码（fenced）
```javascript
console.log("hello world")
```
或者（indented）
console.log("hello world")
都可以得出结果。
## 内联元素
内联元素之间尽量不要存在内部边界空格。
要这样做：
```markdown
**加粗字体**
_倾斜字体_
[链接](http://example.com)
`代码元素`
```
不要这样做：
```markdown
** 加粗字体 **
_ 倾斜字体 _
[ 链接 ]( http://example.com )
` 代码元素 `
```
### 内联元素格式注意事项
- `**加粗字体**`信息主要用来强调，突出显示主要的信息，比如句子中的关键字，或者是列表项突出的重点信息；
- `_倾斜字体_`用来区分文本内有相关性的部分内容，比如英文书籍名，或者是其他相关引用；
- `` `代码元素` ``用于文档中的一些符号信息，比如代码片段等。
### 链接
隐式链接一定要保留尾部的空`[]`块。
要这样做：
```markdown
[link-to-something][]
```
不要这样做：
```markdown
[link-to-something]
```
引用式链接的定义列表，一定要放在文档的最底部，作为引用和参考链接存在。
引用式链接的 URL 不要使用尖括号包括起来。
链接 ID 尽量使用小写字母。并按照字母序排序。
链接的标题要使用双引号来包括。
要这样做：
```markdown
[link](https://example.com "链接")
[another-link][1]
[1]: https://example.com "另一个链接"
```
#### 要使用具有描述性的链接文本
只是给出一个“这里”或者“链接”这样的词语，很难给读者传达你想要描述的内容。
要这样做：
```markdown
你可以参考[CommonMark 标准文档](https://commonmark.org/)来了解更多内容。
```
不要这样做：
```markdown
点击[这里](https://example.com)获取更多相关信息。
```
## 参考
- [Google Markdown Style](https://github.com/google/styleguide/blob/gh-pages/docguide/style.md)
- [Markdown Style Guide by Ciro Santilli](https://cirosantilli.com/markdown-style-guide)
- [CommonMark](https://commonmark.org/)
- [中文文案排版指北](https://github.com/mzlogin/chinese-copywriting-guidelines)