[TOC]
优雅的写文档
markdown简介
- markdown是一种标记语言
Markdown是一种可以使用普通文本编辑器编写的标记语言，通过简单的标记语法，它可以使普通文本内容具有一定的格式。
Markdown 的目标是实现「易读易写」。可读性，无论如何，都是最重要的。一份使用 Markdown 格式撰写的文件应该可以直接以纯文本发布，并且看起来不会像是由许多标签或是格式指令所构成。
- markdown语法简洁
Markdown的语法简洁明了、学习容易，而且功能比纯文本更强，因此有很多人用它写博客。世界上最流行的博客平台WordPress和大型CMS如Joomla、Drupal都能很好的支持Markdown。完全采用Markdown编辑器的博客平台有Ghost和Typecho。(这是百度百科上的解释)
Markdown 语法的目标是：成为一种适用于网络的书写语言。
Markdown 不是想要取代 HTML，甚至也没有要和它相近，它的语法种类很少，只对应 HTML 标记的一小部分。Markdown 的构想不是要使得 HTML 文档更容易书写。在我看来， HTML 已经很容易写了。Markdown 的理念是，能让文档更容易读、写和随意改。HTML 是一种发布的格式，Markdown 是一种书写的格式。就这样，Markdown 的格式语法只涵盖纯文本可以涵盖的范围。
为什么要用markdown
markdown是为哪些使用者设计的
首先要确定你是否真的需要markdown，使用某种工具是为了提高效率或者某种体验的，如果这种工具并不能显著帮你改善体验，那就让它见鬼去吧，哪怕这个工具学起来很简单。
markdown是为那些需要经常码字或者进行文字排版的、对码字手速和排版顺畅度有要求的人群设计的，他们希望用键盘把文字内容啪啪啪地打出来后就已经排版好了，最好从头到尾都不要使用鼠标。这些人包括经常需要写文档的码农、博客写手、网站小编、出版业人士等等。通常情况下，网络上需要进行大量文字输入的地方都可以通过所见即所得的方式排版，本地写作的话则可以使用word这类常用的文本编辑软件，当然你也可以蛋疼地手工使用html标签实现排版效果——而markdown只是使这一切更方便了一点而已，所以如果你觉得现有文本编辑方式完全够用了，就别费神折腾了（除非你在使用像github这样markdown作为主流编辑方式的网站）
以上内容来自知乎：
作者：花生
markdown的优点
- 语法简洁
markdown语法一共就那么几个，几分钟就能背下来
- 简单、轻量级
就是很轻量，很简单
- 纯文本
纯markdown是没有格式的，意味着你可以随心所欲的复制张贴
- 标签有行业标准
意味着你不用去纠结word里面的字号，标题，缩进，等等各种,大家写的文档在同样的解释器下都是一个样子
- 平台支持完善
各大平台：github, StackOverFlow, segmentfault, csdn, 印象笔记, 有道云笔记, 简书......
markdown的缺点
markdown最大的缺点就是方言较多，不同的平台间的语法会有细微的差别，尤其是高阶语法，初级语法基本大家都是一样的，但是，高阶语法你不见得会用到（后面会细说）。
程序员为什么要用markdwon
- 省事
你是一个程序员，为什么要去折腾word? 用markdown吧，不用再理会那些奇奇怪怪的选择。
- 简单
if...else...都比这个还要难吧
- README.md
你以为readme是用什么写的
- 各大代码托管平台
还没有见过不支持markdown的代码托管平台,不迎合程序员你托管什么代码？
- 各大笔记
时不时的记一点笔记，当然是要markdown写了！有道云笔记，为知笔记，onenote等等。对了，印象笔记不支持，但是他有马克飞象啊！
- 装逼
作为程序员你竟然不知道markdown？
markdown基础语法
标题
标题有两种写法，一种是下标式的，只支持二级标题；一种是用#,一个到六个，分别对应移到六级标题，在html里面会被解析成h1~h6
这是一个一级标题
==============
这是一个二级标题
---------------------------
# 这是一级标题
## 这是二级标题
### 这是三级标题 ###
#### 这是四级标题
##### 这是五级标题
###### 这是六级标题
代码块
原生的markdown语法中代码是用一对`包起来的代码块，就像这样
print("hello world")
根据实测，各大平台基本都支持用一对```包起来的代码块，这样包起来的代码能支持超长代码块，而且个别平台还支持指定语言高亮，语法为```php，如github
引用
markdown里用的很多，语法为英文的 >，在html里，引用会解析成blockquote标签
> 这是一个引用
列表
列表可以分为有序列表和无序列表，无序列表可以使用星号，加号或者减号（*、+、-）创建，它们三者效果都是一样的，有序列表则直接在每一项前面加上阿拉伯数字与小数点即可
- 效果
- 第一项
- 第二项
- 第三项
- 第一项
- 第二项
- 第三项
- 第一项
- 第二项
- 第三项
- 有序列表第一项
- 有序列表第二项
- 有序列表第三项
- 源码
* 第一项
* 第二项
* 第三项
+ 第一项
+ 第二项
+ 第三项
- 第一项
- 第二项
- 第三项
1. 有序列表第一项
2. 有序列表第二项
3. 有序列表第三项
强调
使用星号（*）和底线（_）作为标记强调字词的符号，被 * 或 _ 包围的字词会被转成用 <em> 标签包围，用两个 * 或 _ 包起来的话，则会被转成 <strong>
- 效果
斜体
斜体
加粗
加粗
删除线
- 代码
*斜体 *
_斜体_
**加粗**
__加粗__
~~删除线~~
链接
Markdown使用两种方法创建链接，行内创建与引用创建，行内创建一般使用得比较多
- 行内创建
这是一个示例链接
这是一个示例[链接](http://baidu.com "这是一个标题")
- 引用创建
这是一个示例链接，百度还是可以的，但是要多学学谷歌, 百度一下你就知道，google一下，你知道的更多
- 代码
这是一个示例[链接][1]，[百度][2]还是可以的，但是要多学学[谷歌][3], [百度一下][2]你就知道，[google][ou]一下，你知道的更多
[1]:http://www.kunming.cn "kunming"
[2]:http://www.baidu.com "baidu"
[3]:http://www.google.com "Google"
[ou]:http://www.google.com "Google"
图片
图片的语法和链接很相似
- 行内创建
这是一个示例
- 引用创建
这是一个示例![图片][4]，第二个示例![图片][5]， 第三个示例![图片][4]
[4]: ./Koala.jpg "Koala"
[5]: ./Jellyfish.jpg "Jellyfish"
分割线
在行下方空一行然后输入三个或三个以上-, *, _,表示一条分割线
- 效果
- 代码
---
***
___
注脚
在需要添加注脚的文字后加上脚注名字[^注脚名字],称为加注。 然后在文本的任意位置(一般在最后)添加脚注，脚注前必须有对应的脚注名字。
注意：经测试注脚与注脚之间必须空一行，不然会失效。成功后会发现，即使你没有把注脚写在文末，经Markdown转换后，也会自动归类到文章的最后。
- 效果
使用 Markdown[1]可以效率的书写文档, 直接转换成 HTML[2], 你可以使用 Leanote[3] 编辑器进行书写。
- 代码
使用 Markdown[^1]可以效率的书写文档, 直接转换成 HTML[^2], 你可以使用 Leanote[^Le] 编辑器进行书写。
[^1]:Markdown是一种纯文本标记语言
[^2]:HyperText Markup Language 超文本标记语言
[^Le]:开源笔记平台，支持Markdown和笔记直接发为博文
自动链接
- 效果
- 代码
<http://baidu.com/>
转义
markdown好多符号都有特殊的语法格式，但是如果要真正的符号怎么办，可以用一个反斜杠来转义\
*这个是一对星号*
\*这个是一对星号\*
markdown进阶简介
表格
不管是哪种方式，第一行为表头，第二行分隔表头和主体部分，第三行开始每一行为一个表格行。
列于列之间用管道符|隔开。原生方式的表格每一行的两边也要有管道符。
第二行还可以为不同的列指定对齐方向。默认为左对齐，在-右边加上:就右对齐,:\-:就是居中对齐。
- 效果
| 学号 | 姓名 | 分数 |
|---|---|---|
| 小明 | 男 | 75 |
| 小红 | 女 | 79 |
| 小陆 | 男 | 92 |
- 代码
|学号|姓名|分数|
|--:|--:|--:|
|小明|男|75|
|小红|女|79|
|小陆|男|92|
流程图
- 效果
st=>start: 开始:>https://www.zybuluo.com
io=>inputoutput: 数据
op=>operation: 操作
cond=>condition: Yes or No?
sub=>subroutine: 子程序
e=>end: 结束
st->io->op->cond
cond(yes)->e
cond(no)->sub->io
- 代码
flow
st=>start: Start:>https://www.zybuluo.com
io=>inputoutput: verification
op=>operation: Your Operation
cond=>condition: Yes or No?
sub=>subroutine: Your Subroutine
e=>end
st->io->op->cond
cond(yes)->e
cond(no)->sub->io
更多语法参考：流程图语法参考
UML序列图
- 效果
Title:连接建立的过程
客户主机->服务器主机: 连接请求（SYN=1,seq=client_isn）
服务器主机->客户主机: 授予连接（SYN=1,seq=client_isn）\n ack=client_isn+1
客户主机->服务器主机: 确认（SYN=0,seq=client_isn+1）\nack=server_isn+1
- 代码
sequence
Title:连接建立的过程
客户主机->服务器主机: 连接请求（SYN=1,seq=client_isn）
服务器主机->客户主机: 授予连接（SYN=1,seq=client_isn）\n ack=client_isn+1
客户主机->服务器主机: 确认（SYN=0,seq=client_isn+1）\nack=server_isn+1
语法参考：https://bramp.github.io/js-sequence-diagrams/
LaTeX 公式
- 效果
质能守恒方程可以用一个很简洁的方程式 \(E=mc^2\)来表达。
$$\sum_{i=1}^n a_i=0$$
$$f(x_1,x_x,\ldots,x_n) = x_1^2 + x_2^2 + \cdots + x_n^2 $$
$$\sum^{j-1}_{k=0}{\widehat{\gamma}_{kj} z_k}$$
$$x=\frac{-b\pm\sqrt{b^2-4ac}}{2a}$$
- 代码
质能守恒方程可以用一个很简洁的方程式 \\(E=mc^2\\)来表达。
$$\sum_{i=1}^n a_i=0$$
$$f(x_1,x_x,\ldots,x_n) = x_1^2 + x_2^2 + \cdots + x_n^2 $$
$$\sum^{j-1}\_{k=0}{\widehat{\gamma}\_{kj} z_k}$$
$$x=\frac{-b\pm\sqrt{b^2-4ac}}{2a}$$
访问 MathJax 参考更多使用方法。
工具选择
windows平台
markpad
markdownpad
mac平台
mou
linux平台
Remarkable
web端
简书
全平台
cmdmarkdown 作业部落出品
国产优秀markdown编辑器，界面漂亮，就是导出要充会员
sublimeText 神级编辑器
需要两个插件markdown editing 和 markdown preview
配置markdown preview为：
{
"enable_mathjax": true,
"enable_uml": true,
}
参考资料
- 语法手册--一个很全的markdown语法总结 http://blog.leanote.com/post/freewalk/Markdown-语法手册
- 简体中文版语法说明 http://wowubuntu.com/markdown/index.html
- git地址：git@git.kunming.cn:yangbaojin/markdown-docs.git
https://git.kunming.cn/yangbaojin/markdown-docs.git
[Jellyfish]: http://upload-images.jianshu.io/upload_images/3707543-d9cd19b92d74785a.jpg?imageMogr2/auto-orient/strip%7CimageView2/2/w/1240)
