Markdown学习手册

Guangran

[i=s] 本帖最后由 Guangran 于 2025-4-8 20:18 编辑 [/i]

前言

EmulatedLab 论坛支持 Markdown 写作了，这里写一篇简单的教程介绍一下 Markdown 以供大家参考。

# Markdown概述

Markdown是一种轻量级标记语言，它允许人们使用易读、易写的纯文本格式编写文档。

起源

据GitHub Flavored Markdown（GFM）官方文档介绍， Markdown是由约翰·格鲁伯（John Gruber）在亚伦·斯沃茨（Aaron Swartz）的帮助下开发，并在2004年发布的标记语言。

其设计灵感主要来源于纯文本电子邮件的格式，目标是让人们能够使用易读、易写的纯文本格式编写文档，而且这些文档可以转换为HTML（Hyper Text Markup Language，超文本标记语言）文档。

简单点说，Markdown就是由一些简单的符号（如 * / - > [] () #）组成的用于排版的标记语言，其最重要的特点就是可读性强。

Markdown相当于简化了的HTML，它只提供用户最常用的语法格式，更易读和易写，用户可以不必关心复杂的HTML标签，只专注于写作就行了。

演进

起初Markdown主要用于网络写作，后来人们希望Markdown能够应用到更多的领域，如写书、记笔记、写文档、写幻灯片等。由于Markdown本身功能有限，一些特定的需求和场景无法被满足，因此产生
了许多扩展语法，这些语法在基础语法之上新增了如表格、任务列表、围栏代码块等功能。

# 基础语法

字体

1. 标题

在Markdown语法中，标题支持使用两种标记：底线（-/=）和 #。

使用底线的语法如下：

这是一个标题
===

这是一个标题
---

语法说明：

1）底线是 =表示一级标题。

2）底线是 -表示二级标题。

3）底线符号的数量至少2个。

4）这种语法只支持这两级标题。

使用#的语法如下：

# 这是一个一级标题
## 这是一个二级标题
### 这是一个三级标题

语法说明：

1）在行首插入 #可标记出标题。

2）#的个数表示了标题的等级。

3）建议在 #后加一个空格。

4） Markdown中最多只支持前六级标题

语法规范

1. 建议使用 #标记标题，而不是 ===或 ---，因为后者会难以阅读和维护。
2. 要保持间距，建议标题的前后都要空1行（除非标题在文档开头）；#与标题文本之间也要有1个空格，否则会导致阅读困难。
3. 不要有多余的空格。建议标题要写在一行的开头，结尾也不要有空格。
4. 建议标题的结尾不要有标点符号，如句号、逗号、冒号、分号等。
5. 建议标题要尽量简短，这样方便引用，特别是当生成目录时。如果原拟的标题是一个长句，可以从长句中提取标题，而将长句作为标题下的内容。

2. 粗体和斜体

在Markdown中，粗体由两个 *或两个 _包裹，斜体由1个 *或1个 _包裹。

粗体格式的语法如下：

**粗体**
或
__粗体__

斜体格式的语法如下：

*斜体*
或
_斜体_

语法规范

1. 建议粗体使用2个 *包裹，斜体使用1个 *包裹，因为 *比较常见，而且比 _可读性更强。
2. 在粗体和斜体语法标记的内部，建议不要有空格。

段落与换行

Markdown中的段落由一行或多行文本组成，不同的段落之间使用空行来标记。

语法说明：

1）如果行与行之间没有空行，则会被视为同一段落。

2）如果行与行之间有空行，则会被视为不同的段落。

3）空行是指行内什么都没有，或者只有空格和制表符。

4）如果想在段内换行，则需要在上一行的结尾插入两个以上的空格然后按回车键。

语法规范：

为了便于阅读，应该限制每行字符的数量，通常每行不超过80个字符，可以在编辑器中进行设置。

关于换行，建议如下：

1）当超过80个字符后进行换行。

2）在一句话结束（。或 ！或 ？）之后换行。

3）当URL较长时换行。

通常URL较长会导致行字符数量超过限制，为了提高可读性，可以在URL之前加一个换行符。

1. 列表

在Markdown中支持使用有序列表和无序列表，有序列表用 数字序号+英文句号+空格+列表内容来标记，无序列表由 */+/- +空格+列表内容来标记。

有序列表的语法如下:

数字序号 + 英文句号 + 空格 + 列表内容

无序列表的语法如下:

*/+/- + 空格 + 列表内容

嵌套列表的语法示例如下:

+ 第一层列表
TAB + 第二层列表
TAB + TAB + 第三层列表

语法说明如下：

1）列表中可以嵌套列表。

2）有序列表和无序列表也可以互相嵌套。

使用规范

1） 建议使用 -来标记无序列表，因为 *容易跟粗体和斜体混淆，而 +不流行。

2） 如果一个列表中所有的列表项都没有换行，建议使用1个空格。

3） 如果列表项有换行，则建议给无序列表使用3个空格，给有序列表使用2个空格。

4） 如果一个列表中的每个列表项都只有1行，建议列表项之间不要有空行。

5） 如果列表项中有换行，建议在列表项之间空1行，这样会比较容易区分多行列表项的开始和结束。

6） 建议在列表前/后都空1行。

7） 数字、字符、符号列表使用英文半角句号，句号后加空格。

2. 分隔线

在Markdown中，分隔线由 3个以上的 */-/_来标记。

使用分割线的语法如下

***
或
---
或
___

语法说明

1）分隔线须使用至少3个以上的 */-/_来标记。

2）行内不能有其他的字符。

3）可以在标记符中间加上空格。

图片

插入图片的语法如下

![图片替代文字](图片地址)

语法说明如下：

1）图片替代文字在图片无法正常显示时会比较有用，正常情况下可以为空。

2）图片地址可以是本地图片的路径也可以是网络图片的地址。

3）本地图片支持相对路径和绝对路径两种方式。

链接

1. 文字链接

文字链接就是把链接地址直接写在文本中。语法是用方括号包裹链接文字，后面紧跟着括号包裹的链接地址，语法如下所示：

[链接文字](链接地址)

2. 引用链接

引用链接是把链接地址作为“变量”先在 Markdown 文件的页尾定义好，然后在正文中进行引用。其语法如下：

在正文中引用链接标记，可以理解为引用定义好的变量：
[链接文字][链接标记]
在底部定义链接标记，可以理解为定义一个地址变量：
[链接标记]: 链接地址

语法说明如下：

1）链接标记可以有字母、数字、空格和标点符号。

2）链接标记不区分大小写。

3）定义的链接内容可以放在当前文件的任意位置，建议放在页尾。

4）当链接地址为网络地址时要以http/https开头，否则会被识别为本地地址。

3. 网址链接

在 Markdown 中，将网络地址或邮箱地址使用 <>包裹起来会被自动转换为超链接。其语法如下：

<URL 或邮箱地址>

4. 使用规范

1. 在Markdown中，链接标题的信息应该更丰富，从标题中应该可以知道链接的内容，要使用有意义的链接标题。
2. 建议使用 <>包裹自动链接，这种方式更通用。
3. 自动链接要以 http/https 开头。

行内代码与代码块

1. 行内代码

在Markdown中，行内代码引用使用`包裹，语法如下：

`代码`

2. 代码块

在Markdown中，代码块以Tab键或4个空格开头，语法如下。

以 Tab 键开头：
	def test_print():
		pass
或者以 4 个空格开头：
    def test_print():
        pass

[!point]因为代码块使用 Tab 键或 4 个空格开头的效果不够直观，很多扩展语法（如 GFM）提供了围栏代码块，并且支持语法高亮。

3. 使用规范

1. 除行内代码可以使用`包裹以外，如果我们想转义或强调某些字符，也可以使用`包裹。
2. 如果代码超过1行，请使用围栏代码块（扩展语法），并显式地声明语言，这样做便于阅读，并且可以显示语法高亮。但如果我们编写的是简单的代码片段，使用 4 个空格缩进的代码块也许更清晰。
3. 很多Shell命令都要粘贴到终端中去执行，因此最好避免在Shell命令中使用任何换行操作；可以在行尾使用一个 \，这样既能避免命令换行，又能提高源码的可读性。
4. 建议不要在没有输出内容的Shell命令前加 $。在命令没有输出内容的情况下，$是没有必要的，因为内容全是命令，我们不会把命令和输出的内容混淆。
5. 建议在有输出内容的Shell命令前加上 $，这样会比较容易区分命令和输出的内容。

引用

语法

在Markdown中，引用由 >+引用内容来标记，如下所示：

> 引用内容

语法说明如下。

1）多行引用也可以在每一行的开头都插入 >。

2）在引用中可以嵌套引用。

3）在引用中可以使用其他的Markdown语法。

4）段落与换行的格式在引用中也是适用的。

使用规范

1. 建议在引用的标记符号 >之后添加一个空格。
2. 建议每一行引用都使用符号 >。
3. 不要在引用中添加空行。

转义

当我们想在Markdown文件中插入一些标记符号，但又不想让这些符号被渲染时，可以使用 \进行转义，语法如下：

\特殊符号

可被转义的符号：

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

# 扩展语法GFM

围栏代码块

在基础语法中，代码块使用Tab键或4个空格开头；在扩展语法中，围栏代码块使用连续3个`或3个~包裹，还支持语法高亮，可读性和可维护性更强一些。

围栏代码块语法如下：

```python
代码片段
```
或
~~~python
代码片段
~~~

语法说明如下：

围栏代码块使用连续3个`或3个~包裹，支持语法高亮并可以加上编程语言的名字。

# Markdown编辑软件——Typora

Typora是一款功能全面、简洁高效，而且又非常优雅的 Markdown 编辑器。它把源码编辑和效果预览合二为一，在输入标记之后随即生成预览效果，提供了“所见即所得”的Markdown写作体验。

主要特性：

1）实时预览：传统的Markdown编辑器都有两个窗口，左边是源码，右边是渲染后的效果。 Typora独辟蹊径，把源码编辑和效果预览合二为一，实现了真正的所见即所得。

2）扩展语法：Typora不光支持GFM，还扩展了数学公式、流程图等功能。

3）快捷操作：Typora对几乎所有的Markdown标记都提供了快捷操作方式，使用起来非常高效。

4）界面漂亮：默认支持6种主题，可自定义，好看又好用。

5）文件转换：支持多种文件格式通过导入/导出功能跟.md格式相互转换。

6）支持中文：支持中文，可以帮助大家更好地理解各项功能。

7）视图模式：支持大纲和文档列表视图，方便在不同段落和不同文件之间进
行切换。

8）跨平台：支持macOS、 Windows和Linux系统。

下载安装：

下载地址：Typora 官方中文站 (typoraio.cn)

# 最后

更多信息可以参考以下网址

Markdown官网：https://daringfireball.net/projects/markdown/

GFM官方文档：https://github.github.com/gfm/

【参考文档】
了不起的 Markdown / 毕小朋著. —北京：电子工业出版社， 2019.8

ary8888

感谢楼主，值得学习Markdown这个东西的。