most in Chinese, rest in English

0%

Markdown语法说明

发表于 更新于 分类于 Valine：
本文字数： 11k 阅读时长 ≈ 18 分钟

Markdown 是一种轻量级标记语言，它允许人们使用易读易写的纯文本格式编写文档，然后转换成格式丰富的HTML页面。简单的来说，Markdown就是用“标记符号”表示“格式”。Markdown语法标签与HTML语法标签是一一对应的。在这里，本文介绍一些Markdown的基本语法以及自己运行Markdown脚本的编译器。

Sublime Text 编辑器

由于Markdown非常好的好用，有很多在线和离线的编辑器。

  • 在线编译器：dillinger，StackEdit，MaHua，简书，马克飞象。
  • Windows 编译器：MarkdownPad，MarkPad，Smark，Miu
  • OSX 编译器：Mou，MacDown，Ulysses，iA Writer，MWeb
  • 跨平台编译器：Cmd Markdown，小书匠编辑器，FarBox，Sublime Text，Atom，ReText

因为作者本身写代码都在Sublime Text 3里面写，所以虽然要装一些额外的插件，自己还是不想再下载额外的工具了。因此，以下介绍如何在Sublime Text 3 里面编译Markdown:

安装插件 Package Control

Sublime Text 3 中默认已经安装好了此插件。在preferences 里面可以查看是否已经安装好。如果没有，可以参考官方文档进行安装。

安装插件 Markdown Editing

通过按组合键Ctrl+Shift+P或是点击Preference->Package Control调出命令面板，然后再输入 install，选择 Package Control: install package。 稍等，在弹出的对话框中搜索 Markdown Editing，找到之后按 enter 键确认安装。如果安装成功，之后会自动弹出纯文本形式显示的插件说明。点击 Preferences，在 Package Settings 里面会显示有 Markdown Editing 的插件设置选项，在里面可以更改该插件的设置。

安装插件 Markdown Preview

通过按组合键Ctrl+Shift+P或是点击Preference->Package Control调出命令面板，然后再输入 install，选择 Package Control: install package。 稍等，在弹出的对话框中搜索 Markdown Preview，找到之后按 enter 键确认安装。如果安装成功，之后会自动弹出纯文本形式显示的插件说明。点击 Preferences，在 Package Settings 里面会显示有 Markdown Preview 的插件设置选项，在里面可以更改该插件的设置。

更改 Markdown Editing 插件设置

Markdown Editing 的默认设置在Preferences -> Package Settings -> Markdown Editing -> Markdown GFM Settings - Default 里面，背景主题和layout 分别设定为：

1
2
3
"color_scheme": "Packages/MarkdownEditing/MarkdownEditor.tmTheme",
// Layout
"draw_centered": true,

这样会导致背景颜色和其他类型文件在Sublime Text 中的背景颜色不一致。同时layout的设定会导致Markdown 页面左侧会有大量留白。由于Default的设定是不能改的，我们只能从其对应的Markdown GFM Settings - User 里面改。加入以下内容来替换掉default的设定：

1
2
3
4
5
6
{
// Default color scheme
"color_scheme": "Monokai.sublime-color-scheme",
// Layout
"draw_centered": false,
}

更改 Markdown Preview 插件设置

进入Preferences，点击Key Bindings，在弹出的界面右侧用户设置中添加如下代码：

1
[ { "keys": ["alt+m"], "command": "markdown_preview", "args": {"target": "browser", "parser":"markdown"} }, ]

则可以设置 alt + m 组合为预览排版好的 HTML 样式的热键，预览工具是本机上设置的默认浏览器。在对应的Markdown文件中按下快捷键即可在浏览器上预览。此快捷键还可以把鼠标勾选的部分区域内容渲染到浏览器网页上。

开启 Mathjax 数学环境支持

如果想要在 Markdown 中插入数学公式，可以使用 LaTeX 的语法来书写，但是直接使用 LaTeX 语法来书写一段数学公式，使用 Markdown Preview 插件预览时的效果是不成功的，我们需要开启 Mathjax 数学环境支持。进入到Preferences -> Package Settings -> Markdown Preview -> Settings里面加入以下内容。 与上面的插件不同，这个插件是 pymdownx 提供的，因此添加到字典中, 同时还需要需要提供 js 文件的 URL ：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
{
    "js": [
        "https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.4/MathJax.js",
        "res://MarkdownPreview/js/math_config.js"
    ],

    /*
        Markdown extension configuration.

        To specify a function in this JSON configuration, create an object with the key "!!python/name"
        and set it to the import path to the function "module.submodule.etc.function".
    */
    "markdown_extensions": [
        // Python Markdown Extra with SuperFences.
        // You can't include "extra" and "superfences"
        // as "fenced_code" can not be included with "superfences",
        // so we include the pieces separately.
        "markdown.extensions.smart_strong",
        "markdown.extensions.footnotes",
        "markdown.extensions.attr_list",
        "markdown.extensions.def_list",
        "markdown.extensions.tables",
        "markdown.extensions.abbr",
        {
            "markdown.extensions.codehilite": {
                "guess_lang": false
            }
        },
        // Extra's Markdown parsing in raw HTML cannot be
        // included by itself, but "pymdownx" exposes it so we can.
        "pymdownx.extrarawhtml",

        // More default Python Markdown extensions
        {
            "markdown.extensions.toc":
            {
                "permalink": "\ue157"
            }
        },
        "markdown.extensions.meta",
        "markdown.extensions.sane_lists",
        "markdown.extensions.smarty",
        "markdown.extensions.wikilinks",
        "markdown.extensions.admonition",

        // PyMdown extensions that help give a GitHub-ish feel
        "pymdownx.superfences",  // Nested fences and UML support
        {
            "pymdownx.magiclink": {   // Auto linkify URLs and email addresses
                "repo_url_shortener": true,
                "repo_url_shorthand": true
            }
        },
        "pymdownx.tasklist",     // Task lists
        {
            "pymdownx.tilde": {  // Provide ~~delete~~
                "subscript": false
            }
        },
        {
            "pymdownx.emoji": {  // Provide GitHub's emojis
                "emoji_index": {"!!python/name": "pymdownx.emoji.gemoji"},
                "emoji_generator": {"!!python/name": "pymdownx.emoji.to_png"},
                "alt": "short",
                "options": {
                    "attributes": {
                        "align": "absmiddle",
                        "height": "20px",
                        "width": "20px"
                    },
                    "image_path": "https://assets-cdn.github.com/images/icons/emoji/unicode/",
                    "non_standard_image_path": "https://assets-cdn.github.com/images/icons/emoji/"
                }
            }
        },
        {
            "pymdownx.arithmatex":
            {
                "generic": true,
                "smart_dollar": false
            }
        }
    ],
}

由于上面用到了math_config.js文件，而Sublime 本身是没有这个文件的，所以需要在对应的 js 目录下新建该文件。
首先，在Sublime工具栏Preferences > Browser Packages… 打开Packages目录，该目录所在的路径就是Sublime中包的保存路径。
然后，由于上面配置文件中设置的 js 路径是res://MarkdownPreview/js/math_config.js，该路径是相对于sublime包的保存路径而言的，因此我们需要在该目录下新建路径“MarkdownPreview/js/math_config.js”，同时添加math_config.js文件内容如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
MathJax.Hub.Config({
  config: ["MMLorHTML.js"],
  extensions: ["tex2jax.js"],
  jax: ["input/TeX", "output/HTML-CSS", "output/NativeMML"],
  tex2jax: {
    inlineMath: [ ['$','$'], ["\\(","\\)"] ],
    displayMath: [ ['$$','$$'], ["\\[","\\]"] ],
    processEscapes: true
  },
  TeX: {
    extensions: ["AMSmath.js", "AMSsymbols.js"],
    TagSide: "right",
    TagIndent: ".8em",
    MultLineWidth: "85%",
    equationNumbers: {
      autoNumber: "AMS",
    },
    unicode: {
      fonts: "STIXGeneral,'Arial Unicode MS'"
    }
  },
  displayAlign: "center",
  showProcessingMessages: false,
  messageStyle: 'none'
});

配置完成后，结果如下：

1
2
3
\begin{equation}
    \sum\limits_{0}^{+\infty} \dfrac{n^2}{2}
\end{equation}
formula

基本语法

段落

非常自然，一行文字就是一个段落。

1
这是一个段落。

会被解释成

1
<p>这是一个段落。</p>

如果你需要另起一段，请在两个段落之间隔一个空行。

1
2
3
这是一个段落。

这是另一个段落。

会解释成

1
2
<p>这是一个段落<p>
<p>这是另一个段落</p>

粗体斜体：

1
2
3
4
*这是斜体*
_这也是斜体_
**这是粗体**
***这是粗体+斜体***

会被解释成

1
2
3
4
<em>这是斜体</em>
<em>这也是斜体</em>
<strong>这是粗体</strong>
<strong><em>这是粗体+斜体</strong></em>

删除线

1
~~删除线~~

会被解释成

1
<strike>删除线</strike>

标题

markdown总支持1~6六级标题，通过在一行之前加上不同数量的井号来表示。行尾可以加上任意数量的井号字符，这些字符不会算作标题内容。通常会加上相等数量的字符以保持对称。

1
2
3
4
5
# 这是 H1 #
## 这是 H2 ##
### 这是 H3 ###
...
###### 这是 H6 ######

H1和H2

在文本下方添加底线来实现。

1
2
3
4
5
这是 H1
=======

这是 H2
-------

引用

通过在行首加上大于号>来添加引用格式。引用可以嵌套，也可以嵌套其他格式。(此行是一个引用的格式)

1
2
3
4
5
6
> This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet,
consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.

> Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse
id sem consectetuer libero luctus adipiscing.

列表

无序列表使用星号、加号或是减号作为列表标记(都是等价的)：

1
2
3
* Red
- Green
+ Blue

有序列表则使用数字接着一个英文句点，数字并不会影响输出的 HTML 结果：

1
2
3
1. Red
1. Green
2. Blue

内联代码

用反引号来标记内联代码，它们会解释成<code>标签。如果代码的内容中有反引号，请用两个反引号包裹。代码中的&、<、>符号都会自动转义。

1
`a=2`

代码区域

可以首行首缩进4个空格。也可以用三个反引号独占一行来标记。

1
2
3
4
    这是一个代码区块。
`` ` 
这是一个代码区块。 
`` `

会被解释成：

1
2
<pre><code>这是一个代码区块。
</code></pre>

换行

  • 换行单倍行距：按键 space, space, enter
  • 换行双倍行距：按键 enter, enter

分隔线

你可以在一行中用三个以上的星号、减号、底线来建立一个分隔线，行内不能有其他东西。你也可以在星号或是减号中间插入空格。下面每种写法都可以建立分隔线：

1
2
3
4
5
* * *
***
*****
- - -
---------------------------------------

链接

链接的书写格式如下：

1
2
[an example](http://example.com/)
[an example](http://example.com/ "Optional Title")

会被解释为

1
2
<a href='http://example.com/'>an example</a>
<a href='http://example.com/' title="Optional Title">an example</a>

如果链接的地址和名字重复，可以用尖括号语法将其简化。

1
<http://example.com/>

表格

表格是github风格独有的语法，但近年来渐渐被大多数编辑器支持。

1
2
3
4
5
| Item     | Value | Qty   |
| :------- | ----: | :---: |
| Computer | $1600 |  5    |
| Phone    | $12   |  12   |
| Pipe     | $1    |  234  |

会被解释成：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
<thead>
<tr>
  <th align="left">Item</th>
  <th align="right">Value</th>
  <th align="center">Qty</th>
</tr>
</thead>
<tbody><tr>
  <td align="left">Computer</td>
  <td align="right">$1600</td>
  <td align="center">5</td>
</tr>
<tr>
  <td align="left">Phone</td>
  <td align="right">$12</td>
  <td align="center">12</td>
</tr>
<tr>
  <td align="left">Pipe</td>
  <td align="right">$1</td>
  <td align="center">234</td>
</tr>
</tbody></table>

对于一些复杂表格来说，尤其是需要合并单元格的表格，还是推荐用html 的格式来进行书写。

图片

Markdown有自己表示图片的方法如下。然而有些时候我们需要修改图片大小之类的一些参数，而此自带的方法不如html 中<img>标签灵活：

1
2
![Alt text](/path/to/img.jpg)
![Alt text](/path/to/img.jpg "Optional Title")

会被解释为：

1
2
<img src='/path/to/img.jpg' alt='Alt text' />
<img src='/path/to/img.jpg' alt='Alt text' title='Optional Title' />

转义

markdown支持在以下字符前面插入反斜杠：

1
2
3
4
5
6
7
8
9
10
11
12
\   反斜线
`   反引号
*   星号
_   底线
{}  花括号
[]  方括号
()  括弧
#   井字号
+   加号
-   减号
.   英文句点
!   惊叹号

插入之后，将不再解析这些字符，而是原样输出。

高级语法

只有少数编辑器支持，使用前请先确认。

数学公式

内联的TeX公式使用一个美元符号标记：

1
$\Gamma(n) = (n-1)!\quad\forall n\in\mathbb N$

TeX公式块用独占一行的两个美元符号来标记：

1
2
3
$$
a^2 = 2
$$

也可以用equation的标签表示：

1
2
3
4
5
6
7
8
9
10
11
12
13
\begin{equation}
\begin{eqnarray}
f(x) = a_nx^n \\
g(x) = x^2
\end{eqnarray}
\end{equation}

$$
\begin{gather}
(a+b) \times c = a\times c + b \times c \notag \\
ac= a\times c \\
\end{gather}
$$

比较推荐用第二种写法，但是需要确认自己的编辑器是否支持第二种写法。因为其生成的公式会有序号。而且如果在里面嵌套标签的话，看起来更加和谐。

参考文献: