简明的 Markdown 笔记

Github Pages 推荐使用 Markdown 语言编写博客内容。今天就来说一下Markdown

上学那会短暂的接触过Markdown，学了点皮毛就放下了，工作中比较少用到，所以不曾重视，直到有一天需要用的时候发现竟然连最基本的语法都可以写错，于是决定花点时间重新温习一下。真正开始使用它是在 GitHub Pages 里写博客和用它编辑项目的 README 文件。做了一点research发现撰写开发文档，编辑微信公众号文章和邮件内容等等都可以完美的原生支持，突然发现原来Markdown并不鸡肋。相反，可以说，Markdown 如今已经渗透了技术的方方面面，成为了撰写文本文档的首选。

那么首先我们一起来看一下它的「定义」：

Markdown 是一种轻量级标记语言，创始人为 John Gruber。它允许人们「使用易读易写的纯文本格式编写文档，然后转换成有效的 XHTML（或者 HTML）文档」。——维基百科

一起看看这门语言吧！

背景
语法
- 标题
atx-style 一级标题
- 二级标题
  - 六级标题
Setext-style 一级标题

背景

优点

专注于文字内容；
纯文本，易读易写，可以方便地纳入版本控制；
语法简单，没有什么学习成本，能轻松在码字的同时做出美观大方的排版。

使用场景

各类代码托管平台

主流的代码托管平台，如 GitHub、GitLab、BitBucket、Coding、Gitee 等等，都支持 Markdown 语法，很多开源项目的 README、开发文档、帮助文档、Wiki 等都用 Markdown 写作。
技术社区和写作平台

StackOverflow、掘金、简书、GitBook

个人感觉比较遗憾的一点是各平台可能采用不同语言实现的 Markdown 解析引擎，或采用同一解析引擎的不同版本，而且可能有不同程度的定制与扩展，这导致在不同平台上使用 Markdown 写作时体验并不完全一致。不过幸好对于大家公认的一些标准语法，各家都是支持的。

编辑工具

理论上任何一款文本编辑器都能用于编辑 Markdown 文档，它们分别提供了不同程度的语法高亮、预览等功能，以下只是列举其中一部分，选择自己称手的即可。

现代编辑器

VSCode
传统编辑器

Vim / Sublime Text / Notepad++
IDE 自带编辑器

IntelliJ IDEA / WebStorm
专用编辑器

Ulysses / Mou / Typora / Markpad
在线编辑器

各种支持 Markdown 的网站都提供了在线编辑器

语法

标题

Markdown：

# atx-style 一级标题

## 二级标题

###### 六级标题

Setext-style 一级标题
===

二级标题
---

预览效果：

atx-style 一级标题

二级标题

六级标题

Setext-style 一级标题

二级标题

对应 HTML：

<h1>atx-style 一级标题</h1>

<h2>二级标题</h2>

<h6>六级标题</h6>

<h1>Setext-style 一级标题</h1>

<h2>二级标题</h2>

段落

中间没有空行的连续不断的几行文字被视为一个段落。

Markdown：

白日依山尽，

黄河入海流。
（句号后面没空格）

欲穷千里目，

更上一层楼。  
（句号后面有俩空格）

预览效果：

白日依山尽，

黄河入海流。（句号后面没空格）

欲穷千里目，

更上一层楼。
（句号后面有俩空格）

对应 HTML：

<p>白日依山尽，</p>

<p>黄河入海流。
（句号后面没有空格）</p>

<p>欲穷千里目，</p>

<p>
  更上一层楼。
  <br>
  （句号后面有俩空格）
</p>

行内格式

对段落或者部分文本的强调效果。

Markdown：

后面俩字**加黑**

后面俩字*斜体*

预览效果：

后面俩字加黑

后面俩字斜体

对应 HTML：

<p>
  后面俩字
  <strong>加黑</strong>
</p>
<p>
  后面俩字
  <em>斜体</em>
</p>

引用块

Markdown：

> 引用块段落一。
>
> 引用块段落二。
>> 内嵌引用块段落一。
>
> ### 引用块内的标题

预览效果：

引用块段落一。

引用块段落二。

内嵌引用块段落一。

引用块内的标题

对应 HTML：

<blockquote>
  <p>引用块段落一。</p>
  <p>引用块段落二。</p>
  <blockquote>
    <p>内嵌引用块段落一。</p>
  </blockquote>
  <h3 id="引用块内的标题">引用块内的标题</h3>
</blockquote>

超链接

Markdown 支持行内式链接和引用式链接。

Markdown：

行内式 [Blog](https://hishamelamir.github.io "My Personal Blog") 链接，带 title。

行内式 [GitHub](https://github.com/hishamelamir) 链接。

引用式 [博客][1] 链接。

引用式 [GitHub][2] 链接，带 title。

[1]: https://hishamelamir.github.io
[2]: https://github.com/hishamelamir "我的 GitHub 主页"

预览效果：

行内式博客链接，带 title。

行内式 GitHub 链接。

引用式博客链接。

引用式 GitHub 链接，带 title。

对应 HTML：

<p>行内式 <a href="https://hishamelamir.github.io" title="我的个人博客">博客</a> 链接，带 title。</p>

<p>行内式 <a href="https://github.com/hishamelamir">GitHub</a> 链接。</p>

<p>引用式 <a href="https://hishamelamir.github.io">博客</a> 链接。</p>

<p>引用式 <a href="https://github.com/hishamelamir" title="我的 GitHub 主页">GitHub</a> 链接，带 title。</p>

图片

在超链接的写法前加一个 !，就是引用图片的方法。

Markdown：

![Alt text](https://hishamelamir.github.io/favicon.ico "favicon")

预览效果：

对应 HTML：

<img src="https://hishamelamir.github.io/favicon.ico" alt="Alt text" title="favicon">

列表

包括有序列表和无序列表。

Markdown：

- 苹果
- 葡萄
- 榴莲

1. 苹果
2. 葡萄
3. 榴莲

预览效果：

苹果
葡萄
榴莲

苹果
葡萄
榴莲

对应 HTML：

<ul>
  <li>苹果</li>
  <li>葡萄</li>
  <li>榴莲</li>
</ul>
<ol>
  <li>苹果</li>
  <li>葡萄</li>
  <li>榴莲</li>
</ol>

其中无序列表的标记可以使用 +、- 或 *，有序列表前的数字可以是乱序的。

代码块

支持行内代码和代码块。

Markdown：

Given an array of integers, return indices of the two numbers such that they add up to a specific target.
You may assume that each input would have exactly one solution, and you may not use the same element twice.

``` python
def twoSum(self, nums: 'List[int]', target: 'int') -> 'List[int]':
    dict = {}
    for i, v in enumerate(nums):
        another = target - v
        if another not in dict:
            dict[v] = [another, i]
        else:
            return [dict[another][1],i]
```

预览效果：

Given an array of integers, return indices of the two numbers such that they add up to a specific target. You may assume that each input would have exactly one solution, and you may not use the same element twice.

def twoSum(self, nums: 'List[int]', target: 'int') -> 'List[int]':
        dict = {}
        for i, v in enumerate(nums):
            another = target - v
            if another not in dict:
                dict[v] = [another, i]
            else:
                return [dict[another][1],i]

上例中的语言标记 python 可选填，可用于在编辑器和渲染后的效果里添加语法高亮。

块式代码也可以对整个代码段缩进四个空格，或一个 Tab 来实现。

水平分割线

使用一个单独行里的三个或以上 *、- 来生产一条水平分割线，它们之间可以有空格。

Markdown：

***

-----

- - -

预览效果：

对应 HTML：

<hr />

<hr />

<hr />

嵌入 HTML

Markdown 标记语言的目的不是替代 HTML，也不是发明一种更便捷的插入 HTML 标签的方式。它对应的只是 HTML 标签的一个很小的子集。

对于那些没有办法用 Markdown 语法来对应的 HTML 标签，直接使用 HTML 来写就好了。

扩展语法

本节的内容是介绍一些受到广泛支持的 Markdown 扩展语法。

表格

Markdown：

| 编号  | 姓名（左） | 年龄（右） | 性别（中） |
| ----- | :--------  | ---------: | :------:   |
| 0     | 张三       | 28         | 男         |
| 1     | 李四       | 29         | 男         |

预览效果：

编号	姓名（左）	年龄（右）	性别（中）
0	张三	28	男
1	李四	29	男

对应 HTML：

<table>
  <thead>
    <tr>
      <th>编号</th>
      <th align="left">姓名（左）</th>
      <th align="right">年龄（右）</th>
      <th align="center">性别（中）</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>0</td>
      <td align="left">张三</td>
      <td align="right">28</td>
      <td align="center">男</td>
    </tr>
    <tr>
      <td>1</td>
      <td align="left">李四</td>
      <td align="right">29</td>
      <td align="center">男</td>
    </tr>
  </tbody>
</table>

任务列表

在 GitHub / GitLab 里有较好的支持。

Markdown：

- [x] 洗碗
- [ ] 清洗油烟机
- [ ] 拖地

预览效果：

洗碗
清洗油烟机
拖地

对应 HTML：

<ul class="contains-task-list">
  <li class="task-list-item"><input type="checkbox" id="" disabled="" class="task-list-item-checkbox" checked=""> 洗碗</li>
  <li class="task-list-item"><input type="checkbox" id="" disabled="" class="task-list-item-checkbox"> 清洗油烟机</li>
  <li class="task-list-item"><input type="checkbox" id="" disabled="" class="task-list-item-checkbox"> 拖地</li>
</ul>

删除线

Markdown：

后面三个字打上~~删除线~~。

预览效果：

后面三个字打上~~删除线~~。

对应 HTML：

<p>后面三个字打上<del>删除线</del>。</p>

自动链接

自动链接扩展，即：当识别到 URL，或用 <、> 包括的 URL 时，会自动为其生成 a 标签。

Markdown：

https://github.com

<example@gmail.com>

预览效果：

https://github.com

example@gmail.com

对应 HTML：

<p><a href="https://github.com">https://github.com</a></p>

<p><a href="mailto:example@gmail.com">example@gmail.com</a></p>

emoji

以 GitHub Pages 为例。

Markdown：

:camel: :blush: :smile:

预览效果：

对应 HTML：

<p>
  <img class="emoji" title=":camel:" alt=":camel:" src="https://assets-cdn.github.com/images/icons/emoji/unicode/1f42b.png" height="20" width="20">
  <img class="emoji" title=":blush:" alt=":blush:" src="https://assets-cdn.github.com/images/icons/emoji/unicode/1f60a.png" height="20" width="20">
  <img class="emoji" title=":smile:" alt=":smile:" src="https://assets-cdn.github.com/images/icons/emoji/unicode/1f604.png" height="20" width="20">
</p>

Hisham El-Amir (Tech Blog)

简明的 Markdown 笔记

背景

优点

使用场景

编辑工具

语法

标题

atx-style 一级标题

二级标题

六级标题

Setext-style 一级标题

二级标题

段落

行内格式

引用块

引用块内的标题

超链接

图片

列表

代码块

水平分割线

嵌入 HTML

扩展语法

表格

任务列表

删除线

自动链接

emoji

参考

GitHub Flavored Markdown Spec

Search

Table of Contents