Markdown 是一种轻量级标记语言,创始人为约翰·格鲁伯(John Gruber)。它允许人们使用易读易写的纯文本格式编写文档,然后转换成有效的 XHTML (或者 HTML )文档。这种语言吸收了很多在电子邮件中已有的纯文本标记的特性。

——来自中文维基百科

Markdown 方便记忆、容易书写,用户可以使用这些标记符号以最小的输入代价生成极富表现力的文档,且语法和各类资源的支持不断完善,因而受到了许多人的欢迎。本文详细介绍了 Markdown 的主要语法规则。供个人测试与备忘之用。本站的 Markdown 编辑器默认为 markdown-it 。


Markdown 简明语法手册


段落与换行

使用空白行将一行或多行文本进行分隔以创建段落,一般不建议用空格(spaces)或制表符(tabs)缩进段落。

在一行的末尾添加两个或多个空格,然后按回车键(return),即可创建一个换行(line break)其效果与 HTML 代码中的 <br> 相同。

斜体和粗体

使用 *** 表示斜体和粗体, *** 则表示同时使用粗体与斜体。

示例:

这是 斜体,这是 粗体,这是 粗斜体

This is an italic word. This is a bold word. This is an italic bold word.

分级标题

使用 === 表示一级标题,使用 --- 表示二级标题。

示例:

1
2
3
4
5
6
7
这是一个一级标题
============================

这是一个二级标题
--------------------------------------------------

### 这是一个三级标题

也可以选择在行首加井号表示不同级别的标题 (H1-H6),例如:# H1, ## H2, ### H3,#### H4。

超链接

使用 [描述](链接地址 "title文本") 为文字增加普通链接。

一些 Markdown 解析器会自动将 URL 转换为链接,如果不希望自动将 URL 转换为链接,则可以通过 反引号 将 URL 表示为代码 。

示例:

这是去往 Github 的链接。

还可以使用 [文件名](路径) 添加指向本地文件的链接,示例采用了相对链接,建议使用绝对链接。

示例:

这里引用了 icon.png 文件。

此外,通过 markdown-it-link-preview Hexo 插件可以实现 URL 网页预览,将描述改为 @preview 即可。(需引入CSS,比较麻烦)。

无序列表

使用 *+- 表示无序列表。

示例:

  • 无序列表项 一
  • 无序列表项 二
  • 无序列表项 三

有序列表

使用数字和点表示有序列表。

示例:

  1. 有序列表项 一
  2. 有序列表项 二
  3. 有序列表项 三

文字引用

使用 > 表示文字引用,使用多个 > 表示多层文字引用。

示例:

赋得古原草送别
【唐】白居易

离离原上草,一岁一枯荣。
野火烧不尽,春风吹又生。
远芳侵古道,晴翠接荒城。
又送王孙去,萋萋满别情。

行内代码块

使用 `代码` 表示行内代码块。

示例:

让我们聊聊 html

代码块

Markdown 支持四十一种语言的语法高亮的显示,行号显示。但包括本站在内的部分网站只支持高亮一些常见的语言。

使用 四个缩进空格 表示代码块,在半角输入状态下,在键盘上用两次 Tab 键实现快速缩进。在 ``` 之后加入语言名称即可实现语法高亮。

未指定语言示例:

这是一个代码块,此行左侧有四个不可见的空格。

Python 示例:

1
2
3
4
5
6
7
8
9
10
11
12
@requires_authorization
def somefunc(param1='', param2=0):
'''A docstring'''
if param1 > param2: # interesting
print 'Greater'
return (param2 - param1 + 1) or None

class SomeClass:
pass

>>> message = '''interpreter
... prompt'''

JavaScript 示例:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
/**
* nth element in the fibonacci series.
* @param n >= 0
* @return the nth element, >= 0.
*/
function fib(n) {
var a = 1, b = 1;
var tmp;
while (--n >= 0) {
tmp = a;
a += b;
b = tmp;
}
return a;
}

document.write(fib(10));

删除线、下划线和高亮

使用 ~~ 表示删除线, ++ 表示下划线。

这是一段错误的文本。

这段文本添加了下划线。

特殊缩进

由于缩进空格用于表示代码块,因此可通过 HTML 语言中的空格占位符 &ensp;&#8194;&nbsp;&#160;(不换行空格)实现文本缩进。

特别地,对于中文输入需要段落首行缩进而言,则可以使用表示两个空格的占位符 &emsp;&#8195; ,使用2个即可缩进2个汉字。

    使用4个&#160;实现缩进
使用2个&emsp;实现缩进

插入图像

使用 ![描述](图片链接地址 "替代文本") 插入图像。

示例:

    ![我的头像](https://www.emiliabear.com/img/avatar.jpg "ナチュラルファンタジー")

我的头像

字符转义

反斜线 \ 用于插入在 Markdown 语法中有特殊作用的字符。分别输入:

这是用来 *演示* 的 _文本_,

这是用来 \*演示\* 的 \_文本\_。

会显示为:

这是用来 演示文本

这是用来 *演示* 的 _文本_。

Markdown 的字符转义功能有限,\ 只能转义一个或一对字符,可以转义的字符包括:

1
2
3
4
5
6
7
8
9
10
11
12
\
`
*
_
{}
[]
()
#
+
-
.
!

分隔线

在一行中使用三个或更多的 *-_ 来添加分隔线,多个字符之间可以有空格(空白符),但不能有其他字符。


简单表格

单元格和表头

使用 | 来分隔不同的单元格,使用 - 来分隔表头和其他行。为了美观,可以使用空格对齐不同行的单元格,并在左右两侧都使用 | 来标记单元格边界:

1
2
3
4
|    name    | age |
| ---------- | --- |
| Emily | 20 |
| Mike | 32 |
name age
Emily 12
Mike 32

对齐

在表头下方的分隔线标记中加入 :,即可标记下方单元格内容的对齐方式:

:--- 代表左对齐

:--: 代表居中对齐

---: 代表右对齐

此外,表格中也可以插入其他 Markdown 中的行内标记。

1
2
3
4
5
| 项目        | 价格   |  数量  |
| -------- | -----: | :----: |
| 计算机 | \$1600 | 5 |
| 手机 | \$12 | 12 |
| 管线 | \$1 | 234 |
项目 价格 数量
计算机 $1600 5
手机 $12 12
管线 $1 234

如果需要在表格中显示|符号,可用其 HTML 字符编码(|)来实现。

也可以在 Tab Convert Online 像 Excel 那样直观地编辑表格,并输出为 Markdown 等其他语言。

Markdown 进阶语法手册

进阶语法可能需要额外安装对应的插件支持,因此并非所有编辑器都支持下列提到的进阶语法,包括本站也是如此。

内容目录

不同插件有不同的用法,日后补充。在段落中填写 [TOC] 以显示全文内容的目录结构,但是本站主题支持直接显示目录所以填写 [TOC] 没有任何效果。

[TOC]

注释

Markdown 写作通常采用脚注。注脚需要 markdown-it-footnote 插件的支持。使用 [^keyword] 表示注脚,之后在文档末尾使用 [^keyword] 表示脚注内容。

这是一个注脚[1]的样例。

这是第二个注脚[2]的样例。

还可以改为使用 markdown-it-sidenote 插件将注释移到文章右侧,使用方法与脚注类似。

下标与上标

字符下标需要 markdown-it-sub 插件的支持,上标需要 markdown-it-sup 插件的支持。

在需要下标的字符前后添加~,在需要上标的字符前后添加^。当然也可以使用HTML标签<sub><sup>

示例:

H2O 是水的化学符号。22等于4。

折叠块

折叠块需要 markdown-it-collapsible 插件。

示例

1
2
3
+++ Click me!
Hidden text
+++
 Click me!

Hidden text

缩写解释

需要安装 markdown-it-abbr 插件。

示例:

1
2
3
4
*[HTML]: Hyper Text Markup Language
*[W3C]: World Wide Web Consortium
The HTML specification
is maintained by the W3C.

The HTML specification
is maintained by the W3C.

LaTeX 公式

$ 表示行内公式:

质能守恒方程可以用一个很简洁的方程式 E=mc2E=mc^2 来表达,只需输入 $E=mc^2$

$$ 表示整行公式[3]

1
2
3
$$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}$$

f(x1,xx,,xn)=x12+x22++xn2f(x_1,x_x,\ldots,x_n) = x_1^2 + x_2^2 + \cdots + x_n^2

k=0j1γ^kjzk\sum^{j-1}_{k=0}{\widehat{\gamma}_{kj} z_k}

访问 MathJax 参考更多使用方法。

流程图

待补充。可前往参考链接。

示例

更多语法参考:流程图语法参考

序列图

示例 1

1
2
3
Alice->Bob: Hello Bob, how are you?
Note right of Bob: Bob thinks
Bob-->Alice: I am good thanks!

示例 2

1
2
3
4
5
Title: Here is a title
A->B: Normal line
B-->C: Dashed line
C->>D: Open arrow
D-->>A: Dashed open arrow

更多语法参考:序列图语法参考

甘特图

[4]

甘特图内在思想简单。基本是一条线条图,横轴表示时间,纵轴表示活动(项目),线条表示在整个期间上计划和实际的活动完成情况。它直观地表明任务计划在什么时候进行,及实际进展与计划要求的对比。

1
2
3
4
5
6
7
8
9
10
11
12
13
title 项目开发流程
section 项目确定
需求分析 :a1, 2016-06-22, 3d
可行性报告 :after a1, 5d
概念验证 : 5d
section 项目实施
概要设计 :2016-07-05 , 5d
详细设计 :2016-07-08, 10d
编码 :2016-07-15, 10d
测试 :2016-07-22, 5d
section 发布验收
发布: 2d
验收: 3d

更多语法参考:甘特图语法参考

Mermaid 流程图

1
2
3
4
5
6
graph TD
A[Christmas] -->|Get money| B(Go shopping)
B --> C{Let me think}
C -->|One| D[Laptop]
C -->|Two| E[iPhone]
C -->|Three| F[fa:fa-car Car]

更多语法参考:Mermaid 流程图语法参考

Mermaid 序列图

1
2
3
4
Alice->John: Hello John, how are you?
loop every minute
John-->Alice: Great!
end

更多语法参考:Mermaid 序列图语法参考

定义型列表

在第一行键入术语,然后在下一行中键入冒号,冒号后跟着空格和此术语的具体定义,即可创建一个定义列表,它与无序列表在外观上有所不同。

示例:

1
2
3
4
5
6
First Term
: This is the definition of the first term.

Second Term
: This is one definition of the second term.
: This is another definition of the second term.
First Term
This is the definition of the first term.
Second Term
This is one definition of the second term.
This is another definition of the second term.

待办事宜 Todo 列表

- [ ] **Markdown开发**
    - [ ] 改进 Markdown 渲染算法,使用局部渲染技术提高渲染效率
    - [ ] 支持以 PDF 格式导出文稿
    - [x] 新增Todo列表功能 [语法参考](https://github.com/blog/1375-task-lists-in-gfm-issues-pulls-comments)
    - [x] 改进 LaTex 功能
        - [x] 修复 LaTex 公式渲染问题
        - [x] 新增 LaTex 公式编号功能 [语法参考](http://docs.mathjax.org/en/latest/tex.html#tex-eq-numbers)
- [ ] **七月旅行准备**
    - [ ] 准备邮轮上需要携带的物品
    - [ ] 浏览日本免税店的物品
    - [x] 购买蓝宝石公主号七月一日的船票

对应显示如下待办事宜 Todo 列表:

  • Markdown 开发
    • 语法参考
      • 语法参考
  • 七月旅行准备

表情符号

有两种方式可以将表情符号添加到 Markdown 文档中:

  1. 将表情符号复制粘贴:从 Emojipedia 等来源复制表情符号,然后将其粘贴到文档中。

  2. 或者键入 表情符号的简码(emoji shortcodes):简码以冒号开头和结尾,两个冒号中间是表情符号的名称。

     Gone camping! :tent: Be back soon.
    
     hat is so funny! :joy:
    

Gone camping! ⛺️ Be back soon.

That is so funny! 😂

内嵌图标

一些网站支持对外开放 font-awesome 的图标,可参考对应网站的说明文档。

辅助语法:简单的 HTML 标签

大部分渲染器支持在 Markdown 语法中嵌套 Html 标签。当需要更改元素的属性(例如为文本指定颜色或更改图像的宽度)或实现其他当前 Markdown 语法无法实现的效果时,使用 HTML 标签会更方便些。

文本下划线和高亮

使用 <u></u> 标签为文本添加下划线, <mark></mark> 标签高亮文本。[5]

我是<u>下划线文本</u>。
我是<mark>高亮文本</mark>。

我是下划线文本
我是高亮文本

文本对齐

左对齐:

<p align="left">左对齐的文本</p>

左对齐的文本

居中对齐:

<center>居中对齐的文本</center>
居中对齐的文本

右对齐:

<p align="right">右对齐的文本</p>

右对齐的文本

文本颜色与字体

通过设置 font 属性调整文字的颜色和字体。

<font color="颜色的HEX代码">设定颜色后的文字</font>
<font size="4">字体大小为4</font>
<font size="5">字体大小为5</font>
<font face="黑体">我是黑体字</font>
<font face="STCAIYUN">我是华文彩云</font>

浅红色文字
字体大小为4
字体大小为5
我是黑体字
我是华文彩云

下列代码块提供了 Windows 系统和 Mac 系统的常见字体。

新细明体:PMingLiU 细明体:MingLiU 
标楷体:DFKai-SB 
黑体:SimHei 
宋体:SimSun 新宋体:NSimSun 
仿宋:FangSong 仿宋_GB2312:FangSong_GB2312 
楷体:KaiTi  楷体_GB2312:KaiTi_GB2312 
微软正黑体:Microsoft JhengHei 微软雅黑体:Microsoft YaHei 

装Office会多出来的一些字体: 
隶书:LiSu 
幼圆:YouYuan 
华文细黑:STXihei 华文楷体:STKaiti 
华文宋体:STSong 华文中宋:STZhongsong 华文仿宋:STFangsong 
方正舒体:FZShuTi 方正姚体:FZYaoti 
华文彩云:STCaiyun 华文琥珀:STHupo 
华文隶书:STLiti 
华文行楷:STXingkai 华文新魏:STXinwei 

苹果电脑中的字体: 
华文细黑:STHeiti Light [STXihei] 
华文黑体:STHeiti 
华文楷体:STKaiti 
华文宋体:STSong 
华文仿宋:STFangsong 
丽黑 Pro:LiHei Pro Medium 
丽宋 Pro:LiSong Pro Light 
标楷体:BiauKai 
苹果丽中黑:Apple LiGothic Medium 苹果丽细宋:Apple LiSung Light

更复杂的表格

  • <table> 定义表格
  • <caption> 定义表格的标题
    每个表格均有若干行,
  • <tr> 定义行
    每行被分割为若干单元格,
  • <td> 定义单元格
  • <th> 定义表头单元格,多数浏览器会把表头显示为粗体居中的文本
    据单元格可以包含文本、图片、列表、段落、表单、水平线、表格等等。

若要让表格显示边框,可在表格标签使用属性border="1"

若要实现单元格跨行,可在表头标签使用属性rowspan="2";若要实现跨列,可用colspan="2"。数字可自定义。

譬如,你可以用 Html 写一个纵跨两行的表格:

1
2
3
4
5
6
7
8
9
10
11
12
13
<table border="1">
<tr>
<th rowspan="2">值班人员</th>
<th>星期一</th>
<th>星期二</th>
<th>星期三</th>
</tr>
<tr>
<td>李强</td>
<td>张明</td>
<td>王平</td>
</tr>
</table>
值班人员 星期一 星期二 星期三
李强 张明 王平

在文字上方显示辅助文字

例如需要在汉字上方显示拼音,在日文上方显示片假名等等。可加入 <ruby> 标签。

1
2
<span lang='ja'><ruby>作画<rp></rp><rt>さくが</rt><rp></rp></ruby></span>
<ruby><rt>cháng</rt></ruby><ruby><rt>ān</rt></ruby>

显示效果:
作画さくが 、 chángān

参考资料


  1. 这是一个 注脚文本↩︎

  2. 这是另一个 注脚文本↩︎

  3. 受编辑器限制,站点的 Markdown 只支持部分简单的公式的渲染。 ↩︎

  4. 由于种种原因没有需求,本站不支持 Mermaid 。 ↩︎

  5. 实际上也可以安装 markdown-it-mark 插件实现高亮,在需要高亮的文本前后插入 == 即可。 ↩︎