Markdown 文档编写语法指北

    内部分享   Markdown  评论

👌 2020-01-14 Markdown 文档编写语法指北

FileInfo Filename - Markdown Syntax And Writing Specifications Guide.md Version - v1.2.2001（2020/01/14 ~ 2020/01/15） Author - standuke Email - shadowdoker@gmail.com DescriptionKey - Markdown Syntax And Writing Specifications & Chinese and Western typography & Punctuation Specification

文件编写约定

在文件开头将会标注文件的信息，文件信息包括文件名称，用于文件检索。同时会标注文件的版本信息，版本信息格式为v + 大版本号 + 修订版本号 + 修订年月，例如v1.2.1909所代表的含义为第一个大版本、第二个修订版、修订年月为 2019 年 9 月。之后为作者及联系方式。文档描述和关键字用于搜索软件检索文档。

欢迎效仿

Markdown 的设计哲学

Markdown 是一种轻量级标记语言，创始人为约翰·格鲁伯（John Gruber）。它允许人们『使用易读易写的纯文本格式编写文档，然后转换成有效的 XHTML（或者 HTML）文档』。 故 Markdown 的目标是实现文档的「易读易写」。其中最需要强调的是它的易读性。一份使用 Markdown 格式的文件在纯文字发布的情况下，看起来都不会像是有许多符号所组成的文档。 由于Markdown的轻量化、易读易写特性，并且对于图片，图表、数学式都有支持，当前许多网站都广泛使用 Markdown 来撰写帮助文档或是用于论坛上发表消息。

文章结构及阅读指北

在本篇文档中将会分为三大部分。第一部分是基础的 Markdown 语法以及使用范例；第二部分为书写排版及中西文混排范例（部分来自百度前端团队、知乎）；第三部分为标点符号使用范例（来自知乎）。相关可查看 Github 规范 以及 知乎修改规范 、中文文案排版指北

[TOC]

⚠️ 以上为文档简介，正文及规范从下文开始，因为考虑到三大部分的独立性，故各个部分均相互独立，且均以 一级标题 开始

Markdown 语法

1. 标题

Markdown 语法：

# 第一级标题 `<h1>` 
## 第二级标题 `<h2>` 
###### 第六级标题 `<h6>`

效果如下：

第一级标题 <h1>

第二级标题 <h2>

第六级标题 <h6>

2. 强调

Markdown 语法：

*这些文字会生成`<em>`*
_这些文字会生成`<u>`_

**这些文字会生成`<strong>`**
__这些文字会生成`<strong>`__

效果如下：

这些文字会生成<em> 这些文字会生成<u>

这些文字会生成<strong> 这些文字会生成<strong>

3. 换行

四个及以上空格加回车。

4. 列表

无序列表

Markdown 语法：

* 项目一 无序列表 `* + 空格键`
* 项目二
	* 项目二的子项目一 无序列表 `TAB + * + 空格键`
	* 项目二的子项目二

效果如下：

  • 项目一 无序列表 * + 空格键
  • 项目二
    • 项目二的子项目一 无序列表 TAB + * + 空格键
    • 项目二的子项目二

有序列表

Markdown 语法：

1. 项目一 有序列表 `数字 + . + 空格键`
2. 项目二 
3. 项目三
	1. 项目三的子项目一 有序列表 `TAB + 数字 + . + 空格键`
	2. 项目三的子项目二

效果如下：

  1. 项目一 有序列表 数字 + . + 空格键
  2. 项目二
  3. 项目三
    1. 项目三的子项目一 有序列表 TAB + 数字 + . + 空格键
    2. 项目三的子项目二

列表中嵌入代码块语法

1. 项目一 有序列表 `数字 + . + 空格键`
    
    列表中嵌入代码块必须前后空一行，如这个写法
       
    ```js
    function fancyAlert(arg) {
      if(arg) {
        $.facebox({div:'#foo'})
      }
    }
    ```
    
    其他文本。
    
2. 项目二

任务列表（Task lists）

Markdown 语法：

- [ ] 任务一 未做任务 `- + 空格 + [ ]`
- [x] 任务二 已做任务 `- + 空格 + [x]`

效果如下：

  • 任务一 未做任务 - + 空格 + [ ]
  • 任务二 已做任务 - + 空格 + [x]

5. 图片

Markdown 语法：

![GitHub set up](http://URL/set-up-git.gif)
格式: ![Alt Text](url)

效果如下：

GitHub set up

6. 链接

Markdown 语法：

email <example@example.com>
[GitHub](http://github.com)
自动生成连接  <http://www.github.com/>

效果如下：

Email 连接： example@example.com 连接标题Github网站 自动生成连接像： http://www.github.com/ 这样

7. 区块引用

Markdown 语法：

某某说:
> 第一行引用
> 第二行费用文字

效果如下：

某某说:

第一行引用 第二行费用文字

8. 行内代码

Markdown 语法：

像这样即可：`<addr>` `code`

效果如下：

像这样即可：<addr> code

9. 多行或者一段代码

Markdown 语法：

```js
function fancyAlert(arg) {
  if(arg) {
    $.facebox({div:'#foo'})
  }

}
```

效果如下：

function fancyAlert(arg) {
	if(arg) {
		$.facebox({div:'#foo'})
	}

}

10. 顺序图或流程图

Markdown 语法：

```sequence
张三->李四: 嘿，小四儿, 写博客了没?
Note right of 李四: 李四愣了一下，说：
李四-->张三: 忙得吐血，哪有时间写。
```

```flow
st=>start: 开始
e=>end: 结束
op=>operation: 我的操作
cond=>condition: 确认？

st->op->cond
cond(yes)->e
cond(no)->op
```

效果如下（「」）：

张三->李四: 嘿，小四儿, 写博客了没?
Note right of 李四: 李四愣了一下，说：
李四-->张三: 忙得吐血，哪有时间写。

st=>start: 开始
e=>end: 结束
op=>operation: 我的操作
cond=>condition: 确认？

st->op->cond
cond(yes)->e
cond(no)->op

更多请参考：http://bramp.github.io/js-sequence-diagrams/, http://adrai.github.io/flowchart.js/

11. 表格

Markdown 语法：

第一格表头 | 第二格表头
--------- | -------------
内容单元格 第一列第一格 | 内容单元格第二列第一格
内容单元格 第一列第二格 多加文字 | 内容单元格第二列第二格

效果如下：

第一格表头 第二格表头
内容单元格 第一列第一格 内容单元格第二列第一格
内容单元格 第一列第二格 多加文字 内容单元格第二列第二格

12. 删除线

Markdown 语法：

加删除线像这样用： ~~删除这些~~

效果如下：

加删除线像这样用： 删除这些

13. 分隔线

以下三种方式都可以生成分隔线：

***

*****

- - -

效果如下：

14. MathJax

Markdown 语法：

块级公式：
$$	x = \dfrac{-b \pm \sqrt{b^2 - 4ac}}{2a} $$

\\[ \frac{1}{\Bigl(\sqrt{\phi \sqrt{5}}-\phi\Bigr) e^{\frac25 \pi}} =
1+\frac{e^{-2\pi}} {1+\frac{e^{-4\pi}} {1+\frac{e^{-6\pi}}
{1+\frac{e^{-8\pi}} {1+\ldots} } } } \\]

行内公式： $\Gamma(n) = (n-1)!\quad\forall n\in\mathbb N$

效果如下（「」）：

块级公式： $$ x = \dfrac{-b \pm \sqrt{b^2 - 4ac}}{2a} $$

\[ \frac{1}{\Bigl(\sqrt{\phi \sqrt{5}}-\phi\Bigr) e^{\frac25 \pi}} = 1+\frac{e^{-2\pi}} {1+\frac{e^{-4\pi}} {1+\frac{e^{-6\pi}} {1+\frac{e^{-8\pi}} {1+\ldots} } } } \]

行内公式： $\Gamma(n) = (n-1)!\quad\forall n\in\mathbb N$

15. 脚注（Footnote）

Markdown 语法：

这是一个脚注：[^sample_footnote]

效果如下：

这是一个脚注：1

16. 高亮（Highlight）

Markdown 语法：

==example==

效果如下： ==example==

17. 注释和阅读更多

Markdown 语法：

<!-- comment -->
<!-- more -->

注 阅读更多的功能只用在生成网站或博客时，插入时注意要后空一行。

18. 锚点链接

Markdown 语法：

任意 1-6 个 # 标注的标题都会被添加上同名的锚点链接

[标题1](#标题1) 
[标题2](#标题2) 
[标题3](#标题3) 

# 标题1
## 标题2
### 标题3

锚点跳转的标识名称，可使用任意字符，大写字母要转换成小写

[Github标题1](#github标题1)

### Github标题1

多单词锚点的空格用 - 代替

[Github 标题2 Test](#github-标题2-test)

### Github 标题2 Test

多级序号需要去除 .

[2.3. Github 标题](#23-github-标题)

### 2.3. Github 标题

注 Github 并不支持 HTML 形式的锚点链接，它有自己的规则。由于很多渲染器不支持锚点，故尽量少使用锚点。非英文的锚点字符，在单击跳转时，在浏览器的 url 中会按照规则进行 encode 和 decode。 更多请参考：https://my.oschina.net/antsky/blog/1475173/

19. TOC

Markdown 语法：

[TOC]

效果如文档开头的目录

书写排版及中西文混排范例

1. 书写排版范例

文档大标题必须以 # 开头 章节标题必须以 ## 开始，而不是 # 凡是标题，下方正文书写必须空一行

例如：

// bad
##章节1

// bad
## 章节1 ##

// good
## 章节1

// bad
## 章节1
内容
## 章节2

// good
## 章节1

内容

## 章节2

代码段的必须「MUST」使用 Fenced code blocks 风格，如下所示：

console.log("");

表格的写法应该参考 GFM，如下所示：

First Header Second Header
Content Cell Content Cell
Content Cell Content Cell
Left-Aligned Center Aligned Right Aligned
col 3 is some wordy text $1600
col 2 is centered $12
zebra stripes are neat $1

2. 中西文混排范例

中西文混排应该采用如下规则：

【基本规则】

  • 英文和数字使用半角字符
  • 中文文字之间不加空格
  • 中文文字与英文、阿拉伯数字及 @ # $ % ^ & * . ( ) 等符号之间加空格
  • 中文标点之间不加空格
  • 中文标点与前后字符（无论全角或半角）之间不加空格
  • 如果括号内有中文，则使用中文括号
  • 如果括号中的内容全部都是英文，则使用半角英文括号
  • 当半角符号 / 表示「或者」之意时，与前后的字符之间均不加空格
  • 结尾不改写西文专有名词中的半角标点如 “McDonald’s”
  • 中西文（和其他西文半角符号）间留一个半角空格
  • 中文和阿拉伯数字之间同样需留一个半角空格包裹
  • 中文内容的引号应使用直角引号「」或『』
  • 包裹西文内容的引号可以使用 "" 或 ''
  • 包裹西文内容的括号可以使用 () 或（）

以下示例的情况无需修改： 为什么 OS X 的市场份额不及 Windows？ 苹果公司 (Apple) 的招聘流程是怎样的？ 1970 年代的美国电影有哪些推荐？ 如何理解 ‘double irish with a dutch sandwich’ 避税方法？

【表达方式】

  • 应当遵循《The Element of Style》
  • 使段落成为文章的单元
  • 一个段落只表达一个主题
  • 通常在每一段落开始要点题，在段落结尾要扣题
  • 使用主动语态
  • 陈述句中使用肯定说法
  • 删除不必要的词
  • 避免连续使用松散的句子
  • 使用相同的结构表达并列的意思
  • 将相关的词放在一起
  • 在总结中，要用同一种时态（这里指英文中的时态，中文不适用，所以可以不理会）
  • 将强调的词放在句末
  • 避免模糊 误：最近有哪些值得推荐的喜剧电影？ 正：2012 年 7 月 有哪些值得推荐的喜剧电影？
  • 与内容无关的冗余修辞，需要删除

需要修改的词语 网络用语例：「东东」 应为「东西」 ，「神马」应为「什么」 口头语例：「为啥」应为「为什么」 不文明用语例：「牛逼」应为「厉害」「强大」等 错别字：「斯德哥尔摩综合症」应为「斯德哥尔摩综合征」

扩展阅读 Google 后来也出了 Markdown 规范，很多和这里是一样的，但也增加了一些约定，可以参考

标点符号使用

注意事项

避免重复混乱

英文问号（?）、重复（？？？）、混乱（？！） 逗号：英文逗号（,）、重复（，，，）、混乱（，，。）

问号

选择问句中，问号只用在末尾 误：今后十年内，主流手机的系统谁主沉浮？Android？Windows Phone？MeeGo ？iOS？ 正：今后十年内，主流手机的系统谁主沉浮？Android、Windows Phone、MeeGo、iOS？

连续提问时，每个-问句的后面都以问号结尾 误：当前移动互联网的第一大入口是什么，竞争力如何？ 正：当前移动互联网的第一大入口是什么？竞争力如何？

省略号

使用规范的「……」，禁用各种错误变体「。。」「。。。」「。。。。。。」出于简洁考虑，尽量不在标题中使用省略号 省略号使用「……」，而「。。。」仅用于表示停顿

顿号

同类、并列的单字、词语和短语用顿号分隔并列的书名号、引号之间，可用可不用，全文统一即可

书名号

书名、篇名、报纸名、杂志名、歌曲名、影剧名和图表名，用书名号标识括号用作注明翻译或原文时应置于书名号外 误：《旺达与巨像（Shadow of the Colossus）》好玩吗？ 正：《旺达与巨像》（Shadow of the Colossus）好玩吗？

引号

包裹对象为中文时使用直角引号「」或『』包裹对象为西文时可以使用 "" 或 '' 且左右留有半角空格间接引用中句末的句号、问号、感叹号等标点符号应去掉 用直角引号（「」）代替双引号（""） 误：鸡蛋被嫌小时母鸡反驳「你下一个试试？」的逻辑或理由是什么？ 正：鸡蛋被嫌小时母鸡反驳「你下一个试试」的逻辑或理由是什么？

括号

使用括号对内容进行补充说明（如增加信息、消除歧义等）括号的使用原则： 去掉括号的内容句子依然是正确通顺的需要使用外语来详细或准确表述的名词，应当放入括号中 误：为什么样本方差 sample variance 的分母是 n-1？ 正：为什么样本方差（sample variance）的分母是 n-1？ 或：正：为什么样本方差 (sample variance) 的分母是 n-1？

纠错更新

「使用顿号连接的短语必须是名词性的」这个判断是错误的，是否有其他限制，暂未见可靠出处。（来自葛易） 「使用括号注明对名称的翻译（或原文）应置于书名号内」这个用法是错误的，Shadow of the Colossus 是对「《旺达与巨像》」进行注释，而非「旺达与巨像」。（来自 Raymond Wang、黄继新） 不建议在标题等公共区域将『』「」做书名号使用，以保持统一和规范、避免混乱。（来自梁海） 需要删除的词语「指称」加上「楼主」。个人建议「伟大」应改为「强大」，因为它最接近「牛逼」的本意。（来自郅帅杰）

修订信息

版本号 修订日期 修订人 备注
v1.1.2001 2020-01-14 NUO 建立文档
v1.2.2001 2020-01-15 NUO 添加相关出处链接；添加锚点

  1. 这里是脚注信息，在脚注后直接添加即可，渲染器会直接放置在文章末尾 ↩︎

StandukeYunshen Technology Co., Ltd. - SRE Engineer

Focus on Linux Openstack Kubernetes vSphere Photograph Coding