Markdown书写备忘录

Markdown { 简明手册 | jiǎn míng shǒu cè }

[[toc]]

基本语法

Markdown 应用

  • Markdown 是一种轻量级标记语言,它允许人们使用易读易写的纯文本格式编写文档。
  • Markdown 语言在 2004 由约翰·格鲁伯(英语:John Gruber)创建。
  • Markdown 编写的文档可以导出 HTML、Word、图像、PDF、Epub 等多种格式的文档。
  • Markdown 编写的文档后缀为 .md 或 .markdown。

Markdown 能被使用来撰写电子书,如:Gitbook。

当前许多网站都广泛使用 Markdown 来撰写帮助文档或是用于论坛上发表消息。例如:GitHub、简书、reddit、Diaspora、Stack Exchange、OpenStreetMap 、SourceForge 等。

Markdown是一种轻量级的「标记语言」,建议使用 Chrome 浏览器,体验最佳效果。

Markdown 标题

说明

  • 在文字下方加 === 可使上一行文字变成一级标题
  • 在文字下方加 可使上一行文字变成二级标题
  • 在行首加井号(#)表示不同级别的标题,例如:# H1, ##H2, ###H3

Markdown 段落

字体

说明

  • 使用*(或_)**(或__) 表示斜体粗体
  • 使用 / 表示 /下划线/ ,使用~~ 表示删除线
  • 使用^(或^^)表示上标下标
  • 使用 ! 号+数字 表示字体 !24 大! !12 小! 1
  • 使用两个(三个)!号+RGB 颜色 表示!!#ff0000 字体颜色!!(!!!#f9cb9c 背景颜色!!!)2

示例

[!!#ff0000 红色超链接!!](http://www.qq.com)
[!!#ffffff !!!#000000 黑底白字超链接!!!!!](http://www.qq.com)
[新窗口打开](http://www.qq.com){target=_blank}
鞋子 !32 特大号!
大头 ^`儿子`^ 和小头 ^^`爸爸`^^
爱在~~西元前~~**当下**

效果 !!#ff0000 红色超链接!! !!#ffffff !!!#000000 黑底白字超链接!!!!! 新窗口打开 鞋子 !32 特大号! 大头 儿子 和小头 爸爸 爱在西元前当下

段落

Markdown 段落没有特殊的格式,直接编写文字就好,段落的换行是使用两个空格以上加上回车。

MARKDOWN
Markdown[空格][空格][回车]
Markdown

当然也可以在段落后面使用一个空行表示重新开始一个段落

MARKDOWN
Markdown
[空行]
Markdown

还可以使用 <br/> 实现强制换行 显示效果如下所示:

Markdown Markdown

引用

说明

  • 在行首使用 > 表示文字引用

示例

> 野火烧不尽,春风吹又生

效果

野火烧不尽,春风吹又生

分隔线

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

MARKDOWN

***
___
- - -
* * *
_ _ _

显示效果如下所示:

删除线

如果段落上的文字要添加删除线,只需要在文字的两端加上两个波浪线 ~~ 即可:

MARKDOWN
正常文本
~~删除文本~~

显示效果如下所示:

正常文本 删除文本

下划线

下划线可以通过 HTML 的 <u> 标签来实现:

MARKDOWN
<u>下划线文本</u>

显示效果如下所示:

下划线文本

脚注

脚注是对文本的补充说明,Markdown 脚注的格式如下:

MARKDOWN
[^ 要脚注的文本]
Markdown[^ Markdown]

[^ Markdown ]:一种轻量级标记语言

显示效果如下所示:

Markdown [Markdown](https://blog.eurkon.com/post/c894e39a.html#fn_ Markdown)。

Markdown. 一种轻量级标记语言 [↩︎](https://blog.eurkon.com/post/c894e39a.html#reffn_ Markdown)

Markdown 列表

Markdown 支持有序列表和无序列表。

无序列表

说明

  • 在行首使用 *,+,- 表示无序列表

示例

- 无序列表项 一`默认`
- 无序列表项 二
- 无序列表2.1
- 无序列表2.2
- 无序列表项 三
+ 无序列表3.1`空心圆`
+ 无序列表3.1
- 无序列表四
* 无序列表4.1`实心方块`
* 无序列表4.2

效果

  • 无序列表项 一默认
  • 无序列表项 二
    • 无序列表2.1
    • 无序列表2.2
  • 无序列表项 三
    • 无序列表3.1空心圆
    • 无序列表3.1
  • 无序列表四
    • 无序列表4.1实心方块
    • 无序列表4.2

有序列表

说明

  • 在行首使用数字、字母、汉字和点表示有序列表

示例

1. 有序列表项 一`阿拉伯数字`
1. 有序列表项 二
I. 有序列表项 2.1`罗马数字`
I. 有序列表项 2.2
I. 有序列表项 2.3
1. 有序列表 三
a. 有序列表3.1`希腊字母`
a. 有序列表3.2
a. 有序列表3.3
1. 有序列表 四
一. 有序列表4.1`中文数字`
一. 有序列表4.2
一. 有序列表4.3

效果

  1. 有序列表项 一阿拉伯数字
  2. 有序列表项 二 I. 有序列表项 2.1罗马数字 I. 有序列表项 2.2 I. 有序列表项 2.3
  3. 有序列表 三
  1. 有序列表3.1希腊字母
  2. 有序列表3.2
  3. 有序列表3.3
  1. 有序列表 四 一. 有序列表4.1中文数字 一. 有序列表4.2 一. 有序列表4.3

列表嵌套

列表嵌套只需要在子列表中的选项前面添加四个空格即可:

MARKDOWN
1. 第一项:
- 第一项嵌套的第一个元素
- 第一项嵌套的第二个元素
2. 第二项:
1. 第二项嵌套的第一个元素
2. 第二项嵌套的第二个元素

显示效果如下所示:

  1. 第一项:
    • 第一项嵌套的第一个元素
    • 第一项嵌套的第二个元素
  2. 第二项:
    1. 第二项嵌套的第一个元素
    2. 第二项嵌套的第二个元素

Markdown 区块

Markdown 区块引用是在段落开头使用 > 符号,然后后面紧跟一个空格符号:

MARKDOWN
> 区块引用

显示效果如下所示:

区块引用

另外区块是可以嵌套的,一个 > 符号是最外层,两个 > 符号是第一层嵌套,以此类推:

MARKDOWN
> 最外层
> > 第一层嵌套
> > > 第二层嵌套

显示效果如下所示:

最外层

第一层嵌套

第二层嵌套

区块中使用列表

区块中使用列表实例如下:

MARKDOWN
> 区块中使用列表
> 1. 第一项
> 2. 第二项
> + 第一项
> + 第二项
> + 第三项

显示效果如下所示:

区块中使用列表

  1. 第一项
  2. 第二项
  • 第一项
  • 第二项
  • 第三项

列表中使用区块

如果要在列表项目内放进区块,那么就需要在 > 前添加四个空格的缩进。

区块中使用列表实例如下:

MARKDOWN
* 第一项
> 列表中使用区块
* 第二项

显示效果如下所示:

  • 第一项

    列表中使用区块

  • 第二项

Markdown 代码

如果是段落上的一个函数或片段的代码可以用反引号 ``` 或用三个反引号 ````` 把它包起来例如:

行内代码

说明

  • 使用 `代码` 表示行内代码

示例

让我们聊聊 `html`

效果 让我们聊聊 html

代码块

说明

  • 使用 三个` 表示代码块

效果

这是一个代码块
有两行

代码区块

代码区块使用 4 个空格或者一个制表符(Tab 键):

MARKDOWN
[空格][空格][空格][空格]print("Hello");
[Tab]print("World");

显示效果如下所示:

print(“Hello”); print(“World”);

你也可以用 ````` 包裹一段代码,并指定一种语言(也可以不指定):

MARKDOWN
[```][javascript]
$(document).ready(function () {
alert('Hello World');
});
[```]

显示效果如下所示:

JAVASCRIPT
$(document).ready(function () {
alert('Hello World');
});

Markdown 链接

说明

  • 使用 [描述](URL) 为文字增加外链接
  • 使用<URL>插入一个链接
  • URL 会自动转成链接

示例

这是 [腾讯网](https://www.qq.com) 的链接。
这是 [一个引用的][引用一个链接] 的链接。
这是一个包含中文的链接<https://www.qq.com?param=中文>,中文
直接识别成链接:https://www.qq.com?param=中文,中文 用空格结束
[引用一个链接]
[引用一个链接]: https://www.qq.com

效果 这是 腾讯网 的链接。 这是 [一个引用的][引用一个链接] 的链接。 这是一个包含中文的链接https://www.qq.com?param=中文,中文 直接识别成链接:https://www.qq.com?param=中文,中文 用空格结束 [引用一个链接] [引用一个链接]: https://www.qq.com

Markdown 图片

说明

  • 使用 ![描述](图片链接地址) 插入图像
  • 截图,在编辑器中粘贴(ctrl+V)也可以插入图像
  • 使用![描述#宽度#高度#对齐方式](图片链接地址) 可以调整图片大小3

示例

标准图片  ![一条dog#100px](images/demo-dog.png)
设置图片大小(相对大小&绝对大小) ![一条dog#10%#50px](images/demo-dog.png)
设置图片对齐方式:
**左对齐+边框**
![一条dog#auto#100px#left#border](images/demo-dog.png)
**居中+边框+阴影**
![一条dog#auto#100px#center#B#shadow](images/demo-dog.png)
**右对齐+边框+阴影+圆角**
![一条dog#auto#100px#right#B#S#radius](images/demo-dog.png)
**浮动左对齐+边框+阴影+圆角**
![一条dog#auto#100px#float-left#B#S#R](images/demo-dog.png)
开心也是一天,不开心也是一天
这样就过了两天,汪

效果 标准图片 一条dog#100px 设置图片大小(相对大小&绝对大小) 一条dog#10%#50px 设置图片对齐方式: 左对齐+边框 一条dog#auto#100px#left#border 居中+边框+阴影 一条dog#auto#100px#center#B#shadow 右对齐+边框+阴影+圆角 一条dog#auto#100px#right#B#S#radius 浮动左对齐+边框+阴影+圆角 一条dog#auto#100px#float-left#B#S#R 开心也是一天,不开心也是一天 这样就过了两天,汪

属性释义:

  • 宽度:第一个 #100px#10%#auto
  • 高度:第二个 #100px#10%#auto
  • 左对齐:#left
  • 右对齐:#right
  • 居中对齐:#center
  • 悬浮左对齐:#float-left
  • 悬浮右对齐:#float-right
  • 边框:#border#B
  • 阴影:#shadow#S
  • 圆角:#radius#R

Markdown 表格

Markdown 制作表格使用 | 来分隔不同的单元格,使用 - 来分隔表头和其他行。

语法格式如下:

MARKDOWN
| 表头 | 表头 |
| - | - |
| 单元格 | 单元格 |
| 单元格 | 单元格 |

显示效果如下所示:

| 表头 | 表头 | | | | | 单元格 | 单元格 | | 单元格 | 单元格 |

对齐方式

我们可以设置表格的对齐方式:

  • -: 设置内容和标题栏居右对齐。
  • :- 设置内容和标题栏居左对齐。
  • :-: 设置内容和标题栏居中对齐。

实例如下:

MARKDOWN
| 左对齐 | 居中对齐 | 右对齐 |
| :--| :-: | -: |
| 单元格 | 单元格 | 单元格 |
| 单元格 | 单元格 | 单元格 |

显示效果如下所示:

| 左对齐 | 居中对齐 | 右对齐 | | :– | :: | –: | | 单元格 | 单元格 | 单元格 | | 单元格 | 单元格 | 单元格 |

Markdown 高级技巧

支持的 HTML 元素

不在 Markdown 涵盖范围之内的标签,都可以直接在文档里面用 HTML 撰写。

目前支持的 HTML 元素有:<kbd> <b> <i> <em> <sup> <sub> <br> 等 ,如:

MARKDOWN
普通文本:使用 Ctrl+Alt+Del 重启电脑
HTML 文本:使用 <kbd>Ctrl</kbd>+<kbd>Alt</kbd>+<kbd>Del</kbd> 重启电脑

显示效果如下所示:

普通文本:使用 Ctrl+Alt+Del 重启电脑 HTML 文本:使用 Ctrl+Alt+Del 重启电脑

转义

Markdown 使用了很多特殊符号来表示特定的意义,如果需要显示特定的符号则需要使用转义字符,Markdown 使用反斜杠转义特殊字符:

MARKDOWN
**文本加粗**
\*\* 正常显示星号 \*\*

显示效果如下所示:

文本加粗 ** 正常显示星号 **

Markdown 支持以下这些符号前面加上反斜杠来帮助插入普通的符号:

MARKDOWN

\ 反斜线
` 反引号
* 星号
_ 下划线
{} 花括号
[] 方括号
() 小括号
# 井字号
+ 加号
- 减号
. 英文句点
! 感叹号

公式

当你需要在编辑器中插入数学公式时,可以使用两个美元符号$$包裹 TeXLaTeX 格式的数学公式来实现。提交后,问答和文章页会根据需要加载 Mathjax 对数学公式进行渲染。如:

MARKDOWN
$$
\mathbf{V}_1 \times \mathbf{V}_2 = \begin{vmatrix}
\mathbf{i} & \mathbf{j} & \mathbf{k} \\
\frac{\partial X}{\partial u} & \frac{\partial Y}{\partial u} & 0 \\
\frac{\partial X}{\partial v} & \frac{\partial Y}{\partial v} & 0 \\
\end{vmatrix}
${$tep1}{\style{visibility:hidden}{(x+1)(x+1)}}
$$

目录

说明

  • 使用[[toc]],会自动生成一个页面目录,目录内容由一级、二级、三级标题组成

信息面板

说明 使用连续三个冒号:::和关键字([primary | info | warning | danger | success])来声明

:::primary // [primary | info | warning | danger | success] 标题
内容
:::

效果 :::p 标题 内容 :::

内容

手风琴

说明 使用连续三个加号+++和关键字([ + | - ])来声明,关键字+表示默认收起,关键字-表示默认展开

+++ 点击展开更多
内容
++- 默认展开
内容
++ 默认收起
内容
+++

效果 +++ 点击展开更多 内容 ++- 默认展开 内容 ++ 默认收起 内容 +++

语法高亮

说明

  • 在```后面指明语法名
  • 加强的代码块,支持四十一种编程语言的语法高亮的显示

效果 非代码示例:

sudo apt-get install vim-gnome

Python 示例:

@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 示例:

/**
* 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));

checklist4

说明

  • 输入[ ][x],就会生成一个 checklist

示例

- [ ] AAA
- [x] BBB
- [ ] CCC

效果

  • [ ] AAA
  • [x] BBB
  • [ ] CCC

公式5

说明

  • 输入$$$,就会生成一个公式
  • 访问 MathJax 参考更多使用方法

示例

块级公式:$$
\begin{aligned}
P(B|A)&=\frac{P(AB)}{P(A)}\\
P(\overline{B}|A)&=1-P(B|A)=1-\frac{P(AB)}{P(A)}
\end{aligned}
$$
行内公式: $e=mc^2$

效果 块级公式:$$ \begin{aligned} P(B|A)&=\frac{P(AB)}{P(A)}\ P(\overline{B}|A)&=1-P(B|A)=1-\frac{P(AB)}{P(A)} \end{aligned}

$$ 行内公式: \(e=mc^2\)

插入音视频

说明

  • 使用 !v[描述](视频链接地址) 插入视频
    • 使用 !v[描述](视频链接地址){poster=封面地址} 插入视频并配上封面
  • 使用 !audio[描述](视频链接地址) 插入音频

示例

这是个演示视频  !video[不带封面演示视频](images/demo.mp4)
这是个演示视频 !video[带封面演示视频](images/demo.mp4){poster=images/demo-dog.png}
这是个假音频!audio[描述](视频链接地址)

效果 这是个演示视频 !video不带封面演示视频 这是个演示视频 !video带封面演示视频 这是个假音频!audio描述

带对齐功能的表格

说明

  • 一种比较通用的markdown表格语法

示例

|项目(居中对齐)|价格(右对齐)|数量(左对齐)|
|:-:|-:|:-|
|计算机|¥1600|5|
|手机机|¥12|50|

效果 |项目(居中对齐)|价格(右对齐)|数量(左对齐)| |:-:|-:|:-| |计算机|¥1600|5| |手机机|¥12|50|

流程图6

说明

效果 小明老婆让小明下班时买一斤包子,如果遇到卖西瓜的,买一个。

左右结构

graph LR
A[公司] -->| 下 班 | B(菜市场)
B --> C{看见<br>卖西瓜的}
C -->|Yes| D[买一个包子]
C -->|No| E[买一斤包子]

上下结构

graph TD
A[公司] -->| 下 班 | B(菜市场)
B --> C{看见<br>卖西瓜的}
C -->|Yes| D[买一个包子]
C -->|No| E[买一斤包子]

时序图7

说明

效果

sequenceDiagram
A-->A: 文本1
A->>B: 文本2
loop 循环1
loop 循环2
A->B: 文本3
end
loop 循环3
B -->>A: 文本4
end
B -->> B: 文本5
end

状态图8

说明

效果

stateDiagram
[*] --> A
A --> B
A --> C
state A {
[*] --> D
D --> [*]
}
B --> [*]
C --> [*]

UML图9

说明

效果

classDiagram
Base <|-- One
Base <|-- Two
Base : +String name
Base: +getName()
Base: +setName(String name)
class One{
+String newName
+getNewName()
}
class Two{
-int id
-getId()
}

饼图10

说明

效果

pie
title 饼图
"A" : 40
"B" : 30
"C" : 20
"D" : 10

注释11

说明

  • 使用中括号+冒号([]:)生成单行注释
  • 使用中括号+尖号+冒号([^]:)生成多行注释
  • 多行注释以连续两次回车结束

示例

下面是一行单行注释
[注释摘要]: 这是一段注释,不会显示到页面上
上面面是一行单行注释
下面是多行注释
[^注释摘要]: 这是一段多行注释,不会显示到页面上
可以换行
可以缩进
以两次回车结束

上面是多行注释

效果 下面是一行单行注释 [注释摘要]: 这是一段注释,不会显示到页面上 上面面是一行单行注释 下面是多行注释

上面是多行注释

脚注12

说明

  • 在段落中引用多行注释即会生成脚注
  • 脚注中括号中的数字以引用脚注的顺序自动生成
  • 点击脚注的数字可以跳转到脚注详情或回到引用脚注位置

示例

这里需要一个脚注[^脚注别名1],另外这里也需要一个脚注[^another]。
[^脚注别名1]: 无论脚注内容写在哪里,脚注的内容总会显示在页面最底部
以两次回车结束

[^another]: 另外,脚注里也可以使用一些简单的markdown语法
>比如 !!#ff0000 这里!!有一段**引用**

效果 这里需要一个脚注13,另外这里也需要一个脚注14

比如 !!#ff0000 这里!!有一段引用

编辑器操作能力

通过快捷按钮修改字体样式

bubble menu

复制html内容,粘贴成markdown

说明

  • 粘贴html内容时会自动转成markdown,也可以选择粘贴为纯文本格式
  • 可以拖拽调整预览区域的宽度

copy and paste

快捷键

| 功能| 按键(Windows) | 按键(macOS) | |–|–| |1级标题| Ctrl + 1| + 1| |2级标题| Ctrl + 2| + 2| |3级标题| Ctrl + 3| + 3| |4级标题| Ctrl + 4| + 4| |5级标题| Ctrl + 5| + 5| |6级标题| Ctrl + 6| + 6| |加粗| Ctrl + b| + b| |斜体| Ctrl + i | + i| |插入链接| Ctrl + l | + l| |插入代码块| Ctrl + k | + k| |插入图片| Ctrl + g | + g| |插入公式| Ctrl + m | + m|

协议

/**
* Tencent is pleased to support the open source community by making CherryMarkdown available.
*
* Copyright (C) 2021 THL A29 Limited, a Tencent company. All rights reserved.
* The below software in this distribution may have been modified by THL A29 Limited ("Tencent Modifications").
*
* All Tencent Modifications are Copyright (C) THL A29 Limited.
*
* CherryMarkdown is licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/

特性展示

语法特性

支持了所有常用的、通用的语法,除此之外我们还支持了一些有意思的语法

特性 1:图片缩放、对齐、引用

语法

![img #宽度#高度#对齐方式][图片URL或引用]

其中,宽度高度支持:绝对像素值(比如200px)、相对外层容器百分比(比如50%), 对齐方式候选值有:左对齐(缺省)、右对齐(right)、居中(center)、悬浮左、右对齐(float-left/right) 图片尺寸

特性 2:根据表格内容生成图表

表格图表

特性 3:字体颜色、字体大小

字体样式

功能特性

特性 1:复制Html粘贴成MD语法

html转md

使用场景

  • Markdown初学者快速熟悉MD语法的一个途径
  • 为调用方提供一个历史富文本数据迁成Markdown数据的方法

特性 2:经典换行&常规换行

br

使用场景

团队对markdown源码有最大宽度限制?一键切回经典换行(两个及以上连续换行才算一个换行)

特性 3: 多光标编辑

br

使用场景

想要批量修改?可以试试多光标编辑(快捷键、搜索多光标选中等功能正在开发中)

特性 4:图片尺寸

wysiwyg

特性 5:导出

wysiwyg

性能特性

局部渲染

CherryMarkdown会判断用户到底变更了哪个段落,做到只渲染变更的段落,从而提升修改时的渲染性能

wysiwyg

局部更新

CherryMarkdown利用virtual dom机制实现对预览区域需要变更的内容进行局部更新的功能,从而减少了浏览器Dom操作,提高了修改时预览内容更新的性能

wysiwyg


  1. 该语法是CherryMarkdown专有语法,可能无法在其他markdown平台上使用该语法↩︎

  2. 该语法是CherryMarkdown专有语法,可能无法在其他markdown平台上使用该语法↩︎

  3. 该语法是CherryMarkdown专有语法,可能无法在其他markdown平台上使用该语法↩︎

  4. 该语法不是markdown通用语法,无法保证在其他markdown平台上进行正确渲染↩︎

  5. 该语法不是markdown通用语法,无法保证在其他markdown平台上进行正确渲染↩︎

  6. 该语法不是markdown通用语法,无法保证在其他markdown平台上进行正确渲染↩︎

  7. 该语法不是markdown通用语法,无法保证在其他markdown平台上进行正确渲染↩︎

  8. 该语法不是markdown通用语法,无法保证在其他markdown平台上进行正确渲染↩︎

  9. 该语法不是markdown通用语法,无法保证在其他markdown平台上进行正确渲染↩︎

  10. 该语法不是markdown通用语法,无法保证在其他markdown平台上进行正确渲染↩︎

  11. 该语法不是markdown通用语法,无法保证在其他markdown平台上进行正确渲染↩︎

  12. 该语法不是markdown通用语法,无法保证在其他markdown平台上进行正确渲染↩︎

  13. 无论脚注内容写在哪里,脚注的内容总会显示在页面最底部 以两次回车结束↩︎

  14. 另外,脚注里也可以使用一些简单的markdown语法↩︎