Markdown使用教程

2023-03-15 2023-03-15 xiebruce Comments 0 Comment31 Views0 Likes

Markdown官网：由于markdown最初只是John Gruber和Aaron Swartz两人创建的简单的标记语言，并没有什么“官网”，如果说有，那就是John Gruber的个人博客：Markdown: Syntax。

说明：除了下划线和高亮，本文所有markdown语法均在github issue区域测试通过。

什么是markdown？

Markdown由John Gruber和Aaron Swartz创建于2004年，它是一种轻量级标记语言，用于在纯文本编辑器下编写格式化文本(比如加粗、斜体、加链接等等)。

Markdown其实是一种html子集语法，它使用简单的符号来格式化文本，经过markdown引擎解析，即可渲染出对应的html页面，以此来达到快速格式化文本的目的。

比如，下图为有道云笔记设置标题的方法，是通过选中后点击菜单设置的(加粗、斜体等同理)

而Markdown编辑器，允许你用一些符号标记直接把文字设置为你想要的格式，如下所示

# 一级标题
## 二级标题
**加粗**
*斜体*

用一个井号开头表示一级标题，两个井号表示二级标题，两个星号括住表示加粗，一个星号括住表示斜体，支持markdown语法的编辑器，识别到这些符号，就会自动把它们转换为一级标题、二级标题、加粗、斜体，如下图

Markdown优缺点

Markdown的优点：

1、比起用鼠标手动点击菜单，使用符号标记来格式化文本，更方便，格式更统一，能快速写出排版美观的格式化的文档；
2、易读，即使不使用markdown编辑器解析，看上去也能看出文章的结构很清晰；
3、方便共享，只要把你的markdown内容保存为.md文件(其实就是纯文本文件)，别人用任意一个支持markdown的编辑器打开就可以查看，不依赖于特定的软件/app。直接粘贴到支持markown的博客后台，发布就能显示出格式，无需你重新去用鼠标点来点去调格式。

Markdown的缺点：

1、由于markdown渲染后本质是html，所以复制到其它markdown编辑器的时候，图片是带不过去的，所以最好事先把图片上传到网上，返回一个能公共访问的图片链接，这样由于图片不是在本地，无论你复制到哪里都能看；
2、如果你的markdown中用到了latex(编写数学公式，化学反应式常用latex)或流程图语法，那么它的兼容性会大大降低(不同的markdown编辑器对latex和流程图支持程度可能不一样)。

图床：
由于这个原因，很多人开发了一些方便的图片上传工具，用于把图片上传到一些云服务/云盘之类的，再返回能公共访问的图片链接，我们在markdown中插图片的时候，插入这些能公共访问的链接，就不会导致markdown内容拷贝到另一个markdown编辑器后，出现图片无法查看的问题，一般我们把这类图片上传工具叫“图床工具”，而把用于存储图片的地方叫“图床”。我自己也开发了一款图床工具：PicUploader。

Markdown的标记类型

由于Markdown只是html的子集，它并不是为了替代html，所以它并不具有html的所有标记，当对应的标记没有时，你可以直接用html标记，甚至整篇markdown文件全部用html也行，但这就违背html的初衷了。

Markdown有以下标记：

1、h1-h6标题
2、加粗
3、斜体
4、删除线
5、行内代码
6、代码块
7、链接
8、图片
9、水平线
10、有序/无序列表
11、任务列表
12、表格
13、文本引用
14、脚注

无Markdown标记的功能：

1、下划线
2、上标/下标
3、高亮

一般来说，无Markdown标记的功能(比如高亮/下划线/上标/下标等)可直接用html标签来实现，但也有部分线上编辑器因为安全和样式统一等原因，不允许你直接使用html。

以上为markdown基本功能，但markdown中通常还能支持latex(经常用于写数学公式和化学反应式等)和流程图(如mermaid)，只是不同平台对这个支持程度可能不一样，但基本的还是能支持的。

我之前写过一篇：Markdown画流程图(mermaid的基本使用)。

h1-h6标题

一般用#号，1-6个#号，分别代表h1-h6标题(#号与文字之间要有一个空格)

# 一号标题
## 二号标题
### 三号标题
#### 四号标题
##### 五号标题
###### 六号标题

六种标题如下所示

我自己一般使用一号标题作为文章标题，二号和三号标题作为目录，四五六号标题我个人平时基本不使用，因为一旦到了第四级，从样式上就比较难看出它是标题了(当然这也跟不同Markdown解析引擎有关)。

#号也可以有闭合标签，就像其它都用闭合标签一样，但一般没必要这么写，因为标题是单独一行的，没有闭合标签不会影响解析

一号和二号标题，还可以有另一种写法：

1、文字下方加=号即会被识别为一号标题(=号数量不限，可以一个，也可以多个)；
2、文字下方加-号即会被识别为二号标题(-号数量不限，可以一个，也可以多个)；

如下图所示

加粗/斜体/删除线

**双星号括住的文字会被加粗**
__双下划线括住的文字也会被加粗__

*单星号括住的文字会被设置为斜体*
_单下划线括住的文字会被设置为斜体_

~~双波浪线括住的文字会被添加删除线~~

***加粗和斜体嵌套***
**_加粗和斜体嵌套_**

**加粗内*部分*斜体**
__加粗内*部分*斜体__

*斜体内**部分**加粗*
*斜体内__部分__加粗*
_斜体内**部分**加粗_
_斜体内**部分**加粗_

~~删除的文字内**部分**被加粗~~
~~删除的文字内__部分__被加粗~~
~~删除的文字内*部分*被斜体~~

**加粗的文字~~部分被删除~~，*部分*斜体**
__加粗的文字~~部分被删除~~，*部分*斜体__

可以看到，嵌套时，以下划线括住的文字在内部是不会被加粗的，其它部分都正常

行内代码

使用两个反引号括住的部分即为行内代码
“` `echo $aaa` “`，行内代码会被解析为用``标签对括住。

如下图，右侧为markdown引擎解析后的样式

行内代码内如果要显示反引号本身，就要用更多的反引号括住(至少多一个，多两个三个也无所谓)，并且要原样显示的反引号必须与括住的反引号之间有一个空格。

比如
“` control+` “`是在行内代码中显示1个反引号，那么你要写成“` “control+` “ “`(用2个反引号括住)；
比如
“` control+“ “`是在行内代码中显示2个反引号，那么你要写成““ “`control+“ “` ““(用3个反引号括住)；
比如control+```是在行内代码中显示3个反引号，那么你要写成````control+``` ````(用4个反引号括住)。

总之，要显示n个反引号，就要用n+1个反引号去括住，并且要显示的反引号与括住的反引号之间要有一个空格。另外，任何在行内代码内的符号，都会被原样显示，而不会被解析。

代码块

用一对3反引号(至少3个，也可以4个5个或更多)括住的一块区域，就是代码块

```
echo $aaa
echo $bbb
```
</code></pre>

这是代码块
<img src="https://img.xiebruce.top/2023/03/15/50f87b1c8e8dc804ce3bedfb2828b260.jpg" alt="" />

上面的代码块会被解析为以下标签形式(注意pre和code之间就是没换行没空格的，不能格式化，格式化就不对了)

<pre data-language=HTML><code class="language-markup line-numbers"><pre class="notranslate"><code class="notranslate">echo $aaa
echo $bbb
</code></pre>
</code></pre>

<hr />

<strong>给代码块指定解析语言</strong>

在反引号旁边写上语言，即可使用该种语言来解析(主要用于语法高亮显示关键字)，一般网页的都是用PrismJs来解析，它支持的语言请看：<a class="wp-editor-md-post-content-link" href="https://prismjs.com/#supported-languages">Prism Supported languages</a>

<pre><code class="line-numbers">```js
function test(){
    console.log("This is a test!");
}
```

```python
if not 1 > 2:
    print('true')
else:
    print('false')
```

```bash
#!/usr/bin/env bash
printf "%-10s %-8s %-4s\n" 姓名 性别 体重kg  
printf "%-10s %-8s %-4.2f\n" 郭靖 男 66.1234
printf "%-10s %-8s %-4.2f\n" 杨过 男 48.6543
printf "%-10s %-8s %-4.2f\n" 郭芙 女 47.9876
```
</code></pre>

<img src="https://img.xiebruce.top/2023/03/15/b13c34871047d3aef31a1f0e64d7f2a3.jpg" alt="" />

<hr />

与行内代码块类似，如果代码块内要原样显示反引号，则用于括住的反引号一定要比显示的多，比如我显示1个或2个，那直接用三反引号括住就行(毕竟至少是三个反引号)，如果我要显示3个反引号，那就要用一对4反引号括住。

如下所示，在代码块内显示三个反引号，则要用4个反引号括住它

<pre><code class="language-md line-numbers">````
control+```
````

渲染出来是这样的

另外，与行内代码一样，任何在代码块内的符号，都会被原样显示，而不会被解析。

链接

行内链接：方括号后跟着一个圆括号，方括号中填链接文字，圆括号中填url，被markdown渲染后就会成为一个链接。

[Github](https://www.github.com)、[Google](https://www.google.com)、[Baidu](https://www.baidu.com)

解析后的链接如下所示

引用链接：链接和文字分开，优点是可以写title值(要用“单引号”或“双引号”或“圆括号”括住)

[Github][1]、[Google][2]、[百度][3]、[Bruce's Blog]、[Apple][A]、[apple][a]
这是一段正常的文字
这是一段正常的文字
这是一段正常的文字
<!--链接行前面必须要有一行空行-->
[1]: https://www.github.com '这是title1'
[2]: https://www.google.com "这是title2"
[3]: https://www.baidu.com (这是title3)
[Bruce's Blog]: https://www.xiebruce.top
[A]: https://www.apple.com.cn

引用还可以是空格、字母和符号，如果是空格，则第一个方括号中的文字会被作为引用文字，如果是字母，则不分大小写。

如下图所示

自动链接：
按上面的规则，如果你希望链接文字为链接自身，则可以这样写

[https://www.baidu.com](https://www.baidu.com)

但事实上你可以用尖括号简写

<https://www.baidu.com>

如下图所示，使用尖括号的自动链接更方便

图片

行内图片：图片与链接类似，在链接的前面加个感叹号就是图片了，括号里放的自然就是图片链接了(可以是相对路径)，方括号内文字会被设置到<img alt="这是图片">，所以方括号文字为空也是可以的

![这是图片](https://i.imgur.com/efjdf7s.png)

如下图所示

引用图片：仅仅比引用链接多一个感叹号，其它用法都跟引用链接一样(也可以加title)

![这是图片][1]

[1]: https://i.imgur.com/efjdf7s.png '这是title'

带链接的图片
把图片看成一个整体放到方括号内即可

[![这是图片](https://i.imgur.com/efjdf7s.png)](https://www.google.com)

如下图所示

写的时候，可以先写出图片

![这是图片](https://i.imgur.com/efjdf7s.png)

再写出链接

[](https://www.google.com)

最后把前面的图片代码整个放入链接中的方括号内即可。

水平线

水平线其实就是<hr/>标签，我们可以用以下方法，最常用的还是三个横杠---

<!--三条横杠-->
---
<!--三个星号-->
***
<!--三个下划线-->
___

<!--以上三种符号之间可以有一个或多个空格-->
- - -
* * *
_ _ _

如下图所示，它们实际上都会被解析为<hr/>

无序列表

把“减号”或“加号”或“星号”放在列表项的前面(符号与文字之间要有空格)，就会被解析为无序列表，但最常见的还是用减号

- 列表项1
- 列表项2
- 列表项3

+ 列表项1
+ 列表项2
+ 列表项3

* 列表项1
* 列表项2
* 列表项3

以下为无序列表

无序列表嵌套，只要把下层的横杠对齐上层的文字即可

- 列表项1
  - 列表11
    - 列表111
    - 列表112
  - 列表12
    - 列表121
    - 列表122
- 列表项2
  - 列表21
    - 列表211
    - 列表212
  - 列表22
    - 列表221
    - 列表222

有序列表

有序列表以“数字”加“英文句点”或“英文右括号”开头，句点或右括号后面要有一个空格，如果数字不是连续的，它会以第一个数字为准按顺序往下，而不会按你写的数字显示

1. 有序列表项1
2. 有序列表项2
3. 有序列表项3

---

3. 有序列表项1
5. 有序列表项2
9. 有序列表项3

1) 有序列表项1
2) 有序列表项2
3) 有序列表项3

有序列表嵌套

1. 有序列表项1
   1. 有序列表11
      1. 有序列表111
      2. 有序列表112
   2. 有序列表12
2. 有序列表项2
   1. 有序列表21
   2. 有序列表22
3. 有序列表项3
   1. 有序列表31
   2. 有序列表32

无序和有序列表相互嵌套

- 无序列表项1
  1. 有序列表项1
     - 无序列表项1
     - 无序列表项2
  2. 有序列表项2
- 无序列表项2
- 无序列表项3

任务列表

任务列表如下所示，需要注意的是，方括号内用x表示对勾，如果不勾，那就要用空格代替x，即方括号内要么是x，要么是空格

- [ ] 列表项1
  - [ ] 列表项11
  - [x] 列表项22
- [x] 列表项2
- [x] 列表项3

如下图所示，嵌套时，下层的横杠要对齐上层的左方括号

表格

直接用竖杠表示列，第二行竖杠之间要用三个(或以上)横杠格开，这是关键，否则竖杠只是竖杠而不会成为表格

| 默认左对齐 | 左对齐 | 居中对齐 | 右对齐 |
| --- | :--- | :---: | ---: |
| 11 | 12 | \| | ` |
| 21 | 22 | `` | 24 |

三个横杠：默认左对齐；
左侧加冒号：左对齐；
右侧加冒号：右对齐；
两侧都加冒号：居中对齐；
表格内容为反引号时，直接写，不需要转义；
表格内容为竖杠时，需要用反斜杠(\)转义。

如下图所示

文本引用

在文本前使用右尖号(大于号)，大于号后面原则上要跟一个空格(但不跟空格也不会错)，这样文本就会显示成被引用的格式(文本左侧有一条竖线)

> 这是一句被引用的文本

<!--正常写法-->
> 这是一段被引用的文本
> 这是一段被引用的文本
> 这是一段被引用的文本

<!--偷懒写法，第一行有“>”号开头，后面的行只要对齐第一行的文字即可自动被解析为引用文本-->
> 这是一段被引用的文本
  这是一段被引用的文本
  这是一段被引用的文本

如下图所示

脚注

这是一个脚注[^1]。
脚注可以有多行[^2]。
脚注不仅能用数字，还能用文字[^note]。

[^1]: 这是一条引用.
[^2]: 多行脚注
  第二行开始要空两个空格.
[^note]:
    Named footnotes will still render with numbers instead of the text but allow easier identification and linking.
    This footnote also has been made with a different syntax using 4 spaces for new lines.

如下图所示，点击文字后面的脚注，它会自动跳到下边的脚注中

下划线

Markdown没有提供下划线符号，理由是下划线容易跟链接造成冲突，因为链接也带下划线。但我认为这个理由也太牵强了，因为你不提供下划线符号，但是html提供呀。

<u>这是一段被添加下划线的内容</u>

注：github不支持这个标签，可能它认为下划线容易导致文字被认为是链接吧，但是明明链接颜色是蓝色，怎么会导致误认呢？

上标/下标

Markdown没有提供上下标符号，我也不知道为什么，毕竟上下标也挺常用的。还是老方法，既然它没提供，我们就直接用html的方法。

标签对是上标，标签对是下标

<!--这是上标-->
2<sup>10</sup> = 1024

<!--这是上标-->
log<sub>8</sub>2 = 3

如下图所示

高亮显示

Markdown未提供高亮显示的符号，所以只能直接用html的标签

<mark>高亮</mark>

如下图所示，高亮一般是把文字底色设置为黄色(FFFF00)

由于这是html的特性，所以理论上所有markdown编辑器都会支持，我测试了本地四款markdown以及直接写个html页面测试，都是支持的，但有一个例外，github竟然不支持，估计是故意不支持的。

注：github不支持这个标签，可能是不希望网站到处都是一片“黄”吧。

转义符号

转义符号大家应该都很熟悉，就是反斜杠\

# 这是文字

\`echo "This is a test!"\`

制表符是\\t

如下图所示，被\转义后，#号没有被解析为一号标题，反引号`也没有被解析为行内代码，反斜杠也被原样输出(而不是跟后面的t一起被识别为制表符)

可被转义的符号有

   backslash(反斜杠)
`   backtick(反引号)
*   asterisk(星号)
_   underscore(下划线)
{}  curly braces(花括号/大括号)
[]  square brackets(方括号/中括号)
()  parentheses(圆括号/小括号)
#   hash mark(井号)
+   plus sign(加号)
-   minus sign/hyphen(减号/横杠)
.   dot(点号)
!   exclamation mark(感叹号)

注释符号

由于markdown本质是html，所以注释符号就是html的注释符号

<!-- 这段文字是注释，注释只是给人看的，不会markdown引擎被解析 -->
这段是普通文本。这段是普通文本。这段是普通文本。
这段是普通文本。这段是普通文本。这段是普通文本。
这段是普通文本。这段是普通文本。这段是普通文本。

如下图所示，注释是不会被解析显示出来的

关于换行

理论规则：两行相邻的文字，渲染后是不会换行的，必须在第一行最后添加 、\或两个空格才能换行。换行的原理，是两行文字会被放到一对p标签内，两行文字之间会被添加一个 标签(下图为github issue的markdown渲染结果)

现实规则：两行相邻文字，第一行末尾不需要加任何符号，渲染后直接就是换行的，实测了包括github issue在内的n种markdown编辑器都是这样。

以下是markdown创建人之一JOHN GRUBER的个人博客关于markdown的表述：PARAGRAPHS AND LINE BREAKS

PARAGRAPHS AND LINE BREAKS
A paragraph is simply one or more consecutive lines of text, separated by one or more blank lines. (A blank line is any line that looks like a blank line — a line containing nothing but spaces or tabs is considered blank.) Normal paragraphs should not be indented with spaces or tabs.

The implication of the “one or more consecutive lines of text” rule is that Markdown supports “hard-wrapped” text paragraphs. This differs significantly from most other text-to-HTML formatters (including Movable Type’s “Convert Line Breaks” option) which translate every line break character in a paragraph into a
tag.

When you do want to insert a
break tag using Markdown, you end a line with two or more spaces, then type return.

Yes, this takes a tad more effort to create a
, but a simplistic “every line break is a
” rule wouldn’t work for Markdown. Markdown’s email-style blockquoting and multi-paragraph list items work best — and look better — when you format them with hard breaks.

根据他的说法，markdown中两行相邻的文本，默认是不会换行的，即渲染后第二行会跟在第一行后面。如果想要换行，要在前一行的末尾添加两个空格才能换行。

但是现在的markdown编辑器，无论是客户端还是网页上，我试了不下10种，两行相邻的文字被渲染后直接就会被添加 (在标签内添加)，并不需要在第一行后面加两个或多个空格。

可能大家都觉得在markdown上看上去两行，渲染出来却是一行，看到的有渲染出来的完全不一样，有点奇怪，所以没有遵循最初的规则吧，不过规则都是慢慢完善的，最初的规则也未必是最完美的。

关于实体符号

我们知道，有时候我们需要在网页上显示html标签自身，但如果直接写，是会被解析的，所以我们要写成“实体符号”。

在Markdown中，我们无需过多关注实体符号，因为markdown会自动判断

比如a > b，它会直接把大于号转换成>，而不是“文本引用”，因为它不处于开头；
比如&符号，一般情况下它会转换成&，以便在显示的时候，显示成&符号，但是如果遇到实体符号本身，它又不会转换(因为实体符号是以&开头;结尾的)。

一句话：你完全不需要关注你写的符号是否需要写成实体符号，如果确实出现问题，到时再查资料。

在线学习Markdown
Markdown 官方教程
 GitHub Flavored Markdown Spec
Github Basic writing and formatting syntax

打赏

IMOOWI	起航天空
萌新	一冉再
凹凸实验室	风雪之隅
Mengkang's land	ChenShuai
歪麦博客	烂泥行天下
朱双印个人日志	Docker系列教程
骏马金龙

Markdown使用教程

2023-03-15 2023-03-15 xiebruce Comments 0 Comment31 Views0 Likes

什么是markdown？

Markdown优缺点

Markdown的标记类型

h1-h6标题

加粗/斜体/删除线

行内代码

代码块

链接

图片

水平线

无序列表

有序列表

任务列表

表格

文本引用

脚注

下划线

上标/下标

高亮显示

转义符号

注释符号

关于换行

关于实体符号

©版权声明

扫码在手机查看

iPhone请用自带相机扫

安卓用UC/QQ浏览器扫

什么是markdown？

Markdown优缺点

Markdown的标记类型

h1-h6标题

加粗/斜体/删除线

行内代码

代码块

链接

图片

水平线

无序列表

有序列表

任务列表

表格

文本引用

脚注

下划线

上标/下标

高亮显示

转义符号

注释符号

关于换行

关于实体符号

©版权声明

扫码在手机查看 iPhone请用自带相机扫 安卓用UC/QQ浏览器扫

扫码在手机查看

iPhone请用自带相机扫

安卓用UC/QQ浏览器扫