MD | About Markdown

GitHub Pages： https://zhouie.cn/markdown-doc/

1. 认识 Markdown

HTML ( HyperText Markup Language ) 作为一种超文本标记语言 ( Markup Language ) 应运而生，无数的网页从此有了主次分明，层次清晰的格式。
如果将 HTML 比作一架重机枪，那么 Markdown 就是一把手枪，满足了主要的文本格式标记的需求，可是操作性却大大简化。
秉承 易读易写 的宗旨，Markdown 作为一种轻量级标记语言 ( Lightweight Markup Language ) ，让无数的程序猿和文字工作者爱不释手。

1.1 Markdown的优点

• 专注你的文字内容而不是排版样式，安心写作
• 轻松的导出 HTML、PDF 和本身的 .md 文件
• 纯文本内容，兼容所有的文本编辑器与字处理软件
• 随时修改你的文章版本，不必像字处理软件生成若干文件版本导致混乱
• 可读、直观、学习成本低

1.2 Markdown 的现状

有时候一件事情的真相，不是来自于对它的思考，而是来自于对它的感觉。
——Stanley Kubrick

这是 John Grumber 最喜欢的用来解释 Markdown 设计初衷的一句话，Markdown 语言希望带来的就是纯粹的写作的感觉，旨在简洁、高效，也由于 Markdown 的易读易写，人们用不同的编程语言实现了多个版本的解析器和生成器。

目前不同的 Markdown 工具集成了不同的功能（但基础功能大致相同），例如 流程图 与 时序图 ，复杂表格 与 复杂公式 的呈现。
我相信随着 Markdown 语法的逐渐普及开来，以后更多的平台会支持 Markdown 书写模式，并集成更加完整的功能模块。

虽然功能的 “丰富” 并没有什么本质的缺点，但这个程度一旦 “过” 了头，终归有些背离初衷，与 “易读易写” 出现矛盾，开始在编写的过程中觉得有些许吃力了。那这个时候，用户可能会觉得，不如使用专业化的工具来撰写更有效率。

1.3 Markdown官方文档

• 创始人 John Gruber 的 Markdown 语法说明
• Markdown 中文版语法说明

了解一下 John Gruber

2004 年 John Gruber创造 Markdown 语言，14年间，Markdown 语言从程序员圈子中逐渐扩散开来，成为了越来越多的电脑写作者第一选择。

John Gruber 是一个资深果粉，他的个人博客 Daring Fireball 被人戏称为 苹果官方喉舌博客。所以你应该懂为什么最好的 Markdown 编辑器都集中在 Mac 平台上了吧。

---

2. 使用Markdown

2.1 标题

Markdown 通过在行首添加 1 ~ 6个 # 符号来定义不同级别的标题，最多到六级标题。
注意 ：# 后最好是需要加一个空格。

• 书写格式

  # 一级标题
  ## 二级标题
  ### 三级标题
  ###### 六级标题
  

• 解析效果
  

特别的，还可使用 = (高阶标题) 和 - (次阶标题) 标记 一级 和 二级 标题。
注意：= 和 - 的个数在不同 Markdown 工具中都有不同，但这倒不是多大的问题了，简单试试就知道了。

• 书写格式

 效果和一级标题一样
 =
 效果和二级标题一样
 -

• 解析效果
  

2.2 加粗、斜体 和 删除线

• markdown使用 * 和 _ 强调文本，使用一个 * 和 _ 包围的文本会被转化为 斜体 ；而用两个 * 和 _ 包围的文本则会被转化成 加粗 ；使用两个~包围的文本会被转化为 删除线

• 但如果你的 * 、_ 和 ~ 两边都有空白的话，它们就只会被当成普通的符号，这其实也是一个需要注意的地方

• 如果要在文字前后直接插入普通的 星号 * 或 下划线 _ ，你可以用 反斜杠 \ 转义

• 书写格式

  *斜体文字*
  _斜体文字_
  **加粗文字**
  __加粗文字__
  ~~删除内容~~
  

• 解析效果
  斜体文字
  斜体文字
  加粗文字
  加粗文字
  删除内容

2.3 列表

Markdown支持 无序列表 和 有序列表。
无序列表可以使用 * ， + ， - 三者中任意符号来标记；有序列表则使用 数字 加 . 来标记。
注意：标记后面最好是需要加一个空格，有序列表的数字会被按顺序自动更正。通常情况下，无序列表的项目符号是按照实心圆、空心圆、实心方格的层级关系递进的。

• 书写格式

  有序列表
  1. 第一点
  2. 第二点
  5. 第三点
  
  无序列表
  - 这是无序列表项目
  + 这是无序列表项目
  * 这是无序列表项目
  
  嵌套的列表
  + 呵呵
      * 嘉嘉
      - 嘻嘻
      - 吼吼
          - 嘎嘎
          + 桀桀
  * 哈哈
  

• 解析效果
  有序列表

  1. 第一点
  2. 第二点
  3. 第三点

  无序列表

  • 这是无序列表项目
  • 这是无序列表项目
  • 这是无序列表项目

  嵌套的列表

  • 呵呵
    • 嘉嘉
    • 嘻嘻
    • 吼吼
      • 嘎嘎
      • 桀桀
  • 哈哈

2.4 引用

在段落前添加一个 > 符号即可将该段落标记为引用
注意： > 后最好是需要加一个空格；>、>> 和 >>> 等多层嵌套的使用，有点不太好总结，不要问我为什么，实践出真知。

• 书写格式

  一般用法
  > 这是引用
  
  迭代使用（引用中的引用）
  > 这是一级引用
  >> 这是二级引用
  >>> 这是三级引用
  >>
  >> 这是二级引用
  >
  > 这是一级引用
  
  引用的区块内也可使用其他 Markdown 语法
  > **加粗**，*斜体*，~~删除线~~
  > 
  > 1. 这是第一行列表项。
  > 3.  这是第二行列表项。
  > 5.  这是第三行列表项。
  >
  > 给出一些例子代码：
  >
  >     return shell_exec("echo $input | $markdown_script");
  

• 解析效果
  一般用法

  这是引用

  迭代使用（引用中的引用）

  这是一级引用

  这是二级引用

  这是三级引用

  这是二级引用

  这是一级引用

  引用的区块内也可使用其他 Markdown 语法

  加粗，斜体，删除线

  1. 这是第一行列表项。
  2. 这是第二行列表项。
  3. 这是第三行列表项。

  给出一些例子代码：

  return shell_exec("echo $input | $markdown_script");
  

• 补充一下
  引用区块 > 和代码区块 ````的区别：>引用区块中的文本保留Markdown语法，而 ````代码块中的文本不保留Markdown语法。

2.5 分割线

分割线最常使用就是三个或以上 * ，还可以使用 - 和 _ 。
注意：使用 --- 作为水平分割线时，要在它的前面空一行，防止 --- 被当成标题标记的表示方式。

• 书写格式

  ***
  ---
  ___
  

• 解析效果

  ---

  ---

  ---

2.6 插入链接

markdown文本中插入链接非常方便，有 文内链接 和 引用链接 两种方式。
注意：
文内链接 和 引用链接 显示效果是一样的，但是在编辑状态下的使用情况不一样。文内链接紧跟链接文字，可以在看到链接文字的同时清楚的知道链接地址，但是不便于多次重复利用。
引用链接可以重复使用，但一般都是将一些链接放在一起统一管理，如一段文字后面或文章结尾，因此在找到链接和链接文字的对应关系上有些麻烦，各有利弊，分情况使用吧。

• 书写格式

  文内链接
  这是一个文内链接的[例子](http://example.com/ "鼠标悬浮此处显示的标题")。
  [这个](http://example.net/)链接在鼠标悬浮时没有标题。
  [这个](/about/)链接是本地资源。
  
  引用链接
  这是一个引用链接的 [例子][id]，[例子2][]。
  [id]: http://example.com/  "鼠标悬浮标题（可选）"
  [例子2]: http://example.com/ 
  注意，这里的 id 没有大小写区分，如果省略 id ，则前面方括号的内容会被用作 id 。
  
  我常用的网站包括 [Google][1]， [Yahoo][2] 和 [MSN][3] 。
  [1]: http://google.com/        "Google"
  [2]: http://search.yahoo.com/  "Yahoo Search"
  [3]: http://search.msn.com/    "MSN Search"
    
  也可以写成
  
  我常用的网站包括 [Google][]，[Yahoo][] 和 [MSN][] 。
  [google]: http://google.com/        "Google"
  [yahoo]:  http://search.yahoo.com/  "Yahoo Search"
  [msn]:    http://search.msn.com/    "MSN Search"
  

• 解析效果
  文内链接
  这是一个文内链接的
  这是一个链接的例子。
  这个链接在鼠标悬浮时没有标题。
  这个链接是本地资源。
  

2.7 插入图片

插入图片和插入链接非常类似，只是在方括号前多一个 ! 。
![Alt text](/path/to/img.jpg "Optional title")

• Alt text为如果图片无法显示时显示的文字。
• /path/to/img.jpg为图片所在路径。
• Optional title为显示标题。显示效果为在你将鼠标放到图片上后，会显示一个小框提示，提示的内容就是Optional title。

注意：Markdown 语法目前还没有某种合适的办法指定图片的宽高，但据我所知，很多平台以及在这个方向作出相当多的改进了，一起期待吧！

• 书写格式

  文内链接
  ![idol](http://pcx2lec2u.bkt.clouddn.com/201808051449_378.jpg)
  
  引用链接
  ![idol][idol]
  [idol]: http://pcx2lec2u.bkt.clouddn.com/201808051449_378.jpg
  

• 解析效果
  文内链接
  

2.8 表格

表格的书写格式一目了然，还是很方便简洁的。

• 书写格式

  | 左对齐 | 中间对齐 | 右对齐 |
  | :---   |  :---:   |   ---: |
  | 左1    |  中1     |  右1   |
  | 左2    |  中2     |  右3   |
  

• 解析效果