首页/技术文章/Markdown 学习手册

Markdown 学习手册

详细介绍 Markdown 基础语法、扩展语法 GFM 及 Typora 编辑器的使用。

2023-03-31技术文章
MarkdownTypora写作

一、Markdown 概述

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

起源

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

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

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

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

演进

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

二、基础语法

字体

标题

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

使用底线的语法：

CODEmarkdown
这是一个标题===
CODEmarkdown
这是一个标题---

语法说明：

  1. 底线是=表示一级标题。
  2. 底线是-表示二级标题。
  3. 底线符号的数量至少 2 个。
  4. 这种语法只支持这两级标题。

使用 # 的语法：

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

语法说明：

  1. 在行首插入#可标记出标题。
  2. #的个数表示了标题的等级。
  3. 建议在#后加一个空格。
  4. Markdown 中最多只支持前六级标题

语法规范：

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

粗体和斜体

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

粗体格式的语法：

CODEmarkdown
**粗体**或__粗体__

斜体格式的语法：

CODEmarkdown
*斜体*或_斜体_

语法规范：

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

段落与换行

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

语法说明

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

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

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

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

语法规范：

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

关于换行，建议如下：

  1. 当超过 80 个字符后进行换行。
  2. 在一句话结束（。或！或？）之后换行。
  3. 当URL较长时换行。

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

列表

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

有序列表的语法：

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

无序列表的语法：

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

嵌套列表的语法：

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

语法说明如下：

  1. 列表中可以嵌套列表。
  2. 有序列表和无序列表也可以互相嵌套。

使用规范：

  1. 建议使用-来标记无序列表，因为*容易跟粗体和斜体混淆，而+不流行。
  2. 如果一个列表中所有的列表项都没有换行，建议使用 1 个空格。
  3. 如果列表项有换行，则建议给无序列表使用 3 个空格，给有序列表使用2个空格。
  4. 如果一个列表中的每个列表项都只有 1 行，建议列表项之间不要有空行。
  5. 如果列表项中有换行，建议在列表项之间空 1 行，这样会比较容易区分多行列表项的开始和结束。
  6. 建议在列表前/后都空 1 行。
  7. 数字、字符、符号列表使用英文半角句号，句号后加空格。

分隔线

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

使用分割线的语法：

CODEmarkdown
***或---或___

语法说明：

  1. 分隔线须使用至少 3 个以上的*/-/_来标记。
  2. 行内不能有其他的字符。
  3. 可以在标记符中间加上空格。

图片

插入图片的语法：

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

语法说明如下：

  1. 图片替代文字在图片无法正常显示时会比较有用，正常情况下可以为空。
  2. 图片地址可以是本地图片的路径也可以是网络图片的地址。
  3. 本地图片支持相对路径和绝对路径两种方式。

链接

文字链接

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

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

引用链接

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

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

语法说明如下：

  1. 链接标记可以有字母、数字、空格和标点符号。
  2. 链接标记不区分大小写。
  3. 定义的链接内容可以放在当前文件的任意位置，建议放在页尾。
  4. 当链接地址为网络地址时要以 http/https 开头，否则会被识别为本地地址。

网址链接

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

CODEmarkdown
<URL 或邮箱地址>

使用规范

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

行内代码与代码块

行内代码

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

CODEmarkdown
`代码`

代码块

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

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

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

使用规范

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

引用

语法：

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

CODEmarkdown
> 引用内容

语法说明如下：

  1. 多行引用也可以在每一行的开头都插入>。
  2. 在引用中可以嵌套引用。
  3. 在引用中可以使用其他的 Markdown 语法。
  4. 段落与换行的格式在引用中也是适用的。

使用规范：

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

转义

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

CODEmarkdown
\特殊符号

可被转义的符号：

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

三、扩展语法 GFM

围栏代码块

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

围栏代码块语法：

CODEmarkdown
```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 / 毕小朋著. —北京：电子工业出版社， 2019.8