简明的 Markdown 笔记

15 Sep 2019 Tech-Post Markdown

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


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

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

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

一起看看这门语言吧!

目录

背景

优点

  1. 专注于文字内容;

  2. 纯文本,易读易写,可以方便地纳入版本控制;

  3. 语法简单,没有什么学习成本,能轻松在码字的同时做出美观大方的排版。

使用场景

  • 各类代码托管平台

    主流的代码托管平台,如 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://zhenyu0519.github.io "My Personal Blog") 链接,带 title。

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

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

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

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

预览效果:

行内式 博客 链接,带 title。

行内式 GitHub 链接。

引用式 博客 链接。

引用式 GitHub 链接,带 title。

对应 HTML:

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

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

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

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

图片

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

Markdown:

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

预览效果:

Alt text

对应 HTML:

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

列表

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

Markdown:

- 苹果
- 葡萄
- 榴莲

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

预览效果:

  • 苹果
  • 葡萄
  • 榴莲
  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:

预览效果:

: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>

参考

Search

    Table of Contents