Skip to main content

試試我們的 Chrome 擴充功能，更快地轉換 Markdown

Markdown 語法詳解：從基礎到精通的完整指南

最全面的 Markdown 語法學習指南，系統性介紹所有核心語法元素。從標題、文字格式化到清單、引用，包含詳細範例和最佳實務。

發佈時間：
更新時間：
入門
twmarkdown語法, markdown標題, markdown文字格式, markdown清單, markdown引用, markdown學習2PT1MbeginnerTutorialTechnology

Markdown 语法概念图

什么是 Markdown 语法

Markdown 语法是一种轻量级标记语言的格式化规则集合，由 John Gruber 在 2004 年创建[1]。它使用简单的文本符号来表示格式化元素，如标题、粗体、斜体、链接和列表等。Markdown 的核心理念是让文档在纯文本状态下就具有良好的可读性，同时能够轻松转换为 HTML 或其他格式。

Markdown 语法的设计哲学体现在其创始人 John Gruber 的原始描述中："Markdown 的语法完全由标点符号组成，这些标点符号经过精心选择，看起来就像它们所表示的意思"[2]。这种直观性使得 Markdown 成为了技术写作、文档编写和内容创作的首选工具。

与传统的富文本编辑器不同，Markdown 采用纯文本格式，这意味着您可以使用任何文本编辑器来编写 Markdown 文档。这种简洁性带来了诸多优势：文件体积小、版本控制友好、跨平台兼容性强，以及学习成本低。无论您是程序员、技术写作者、博客作者还是学生，掌握 Markdown 语法都能显著提升您的文档编写效率。

Markdown 语法的标准化经历了多个阶段的发展。最初的 Markdown 规范相对简单，但随着使用场景的扩展，出现了许多变体和扩展。CommonMark 项目致力于创建一个明确、无歧义的 Markdown 规范[3]，而 GitHub Flavored Markdown (GFM) 则在标准 Markdown 基础上增加了表格、任务列表等实用功能[4]。

为什么要掌握 Markdown 语法

掌握 Markdown 语法在当今的数字化工作环境中具有重要意义。首先，Markdown 已经成为技术文档的事实标准。GitHub、GitLab、Stack Overflow、Reddit 等主流平台都支持 Markdown 格式，这意味着熟练使用 Markdown 语法能够让您在这些平台上更有效地交流和协作。

从效率角度来看，Markdown 语法能够显著提升写作速度。传统的富文本编辑器需要频繁使用鼠标进行格式化操作，而 Markdown 允许您在不离开键盘的情况下完成所有格式化工作。研究表明，熟练的 Markdown 用户的写作速度比使用传统编辑器的用户快 30-50%[5]。

Markdown 语法的另一个重要优势是其出色的可移植性。由于 Markdown 文档是纯文本格式，它们可以在任何设备、任何操作系统上打开和编辑。您不必担心软件兼容性问题，也不会遇到格式丢失的困扰。这种特性使得 Markdown 成为长期文档存储的理想选择。

在版本控制方面，Markdown 语法展现出了独特的优势。Git 等版本控制系统能够精确跟踪 Markdown 文档的变化，显示具体的文本修改内容。这对于团队协作和文档维护来说是极其宝贵的功能。相比之下，二进制格式的文档（如 Word 文档）在版本控制中只能显示文件已更改，无法展示具体的修改内容。

从学习投资回报率的角度来看，Markdown 语法具有学习成本低、应用范围广的特点。基础语法可以在几小时内掌握，而这些知识可以在多个平台和场景中重复使用。无论是编写技术文档、撰写博客文章、制作演示文稿，还是记录会议纪要，Markdown 都能提供一致的写作体验。

基础语法核心

Markdown 语法对比图

基础语法是 Markdown 的核心组成部分，这些语法元素在几乎所有 Markdown 解析器中都得到支持。掌握这些基础语法能够满足大部分日常写作需求，是学习 Markdown 的重要基础。

标题语法

标题是文档结构的骨架，Markdown 提供了两种创建标题的方法。主要方法是使用井号（#）符号，这种方法支持六个级别的标题，对应 HTML 中的 h1 到 h6 标签。

井号标题语法

井号标题语法是最常用和推荐的标题创建方法。语法规则非常简单：在文本前添加一个或多个井号，井号的数量决定标题的级别。需要注意的是，井号和标题文本之间必须有一个空格，这是为了确保在不同 Markdown 解析器中的兼容性[6]。

# 一级标题

## 二级标题

### 三级标题

#### 四级标题

##### 五级标题

###### 六级标题

在实际使用中，标题的层次结构应该保持逻辑性和一致性。一级标题通常用于文档标题，二级标题用于主要章节，三级标题用于子章节，以此类推。避免跳级使用标题，例如从一级标题直接跳到三级标题，这会影响文档的可读性和 SEO 效果。

替代标题语法

Markdown 还支持另一种标题语法，称为 Setext 风格，但仅支持一级和二级标题。这种语法在标题文本下方添加等号（=）或连字符（-）来表示标题级别。

# 一级标题

## 二级标题

虽然这种语法在视觉上更加突出，但由于只支持两个级别且不如井号语法简洁，在实际使用中较少采用。大多数现代 Markdown 编辑器和解析器都更好地支持井号语法。

标题最佳实践

在使用标题语法时，有几个重要的最佳实践需要遵循。首先，始终在井号和标题文本之间添加空格，这确保了跨平台的兼容性。其次，在标题前后添加空行，这有助于提高文档的可读性，特别是在纯文本状态下查看时。

这是一段普通文本。

# 这是正确的标题格式

这是标题后的内容。

另一个重要的实践是保持标题的层次结构清晰。每个文档应该只有一个一级标题，通常作为文档的主标题。二级标题用于主要章节，三级标题用于子章节，依此类推。这种结构不仅有助于读者理解文档内容，也有利于搜索引擎优化和自动生成目录。

文本格式化

文本格式化是 Markdown 中最常用的功能之一，包括粗体、斜体、删除线等基本格式。这些格式化选项使用简单的符号来实现，既直观又易于记忆。

粗体文本

粗体文本用于强调重要内容，在 Markdown 中有两种创建粗体的方法：使用双星号（**）或双下划线（__）。两种方法在功能上完全相同，但推荐使用双星号，因为它在各种 Markdown 解析器中的兼容性更好。

**这是粗体文本**
**这也是粗体文本**

在单词中间添加粗体强调时，必须使用星号而不是下划线，因为下划线在单词中间可能不被正确解析[7]。

Love**is**bold # 正确
Love**is**bold # 可能不被正确解析

斜体文本

斜体文本用于表示强调或引用，使用单星号（*）或单下划线（_）创建。与粗体类似，推荐使用星号以确保更好的兼容性。

_这是斜体文本_
_这也是斜体文本_

粗体和斜体组合

当需要同时使用粗体和斜体时，可以组合使用三个星号或下划线。这种格式在技术文档中经常用于强调特别重要的概念或术语。

**_这是粗体斜体文本_**
**_这也是粗体斜体文本_**
**_混合使用也可以_**
_**这样也行**_

删除线

删除线用于表示已删除或不再有效的内容，使用双波浪号（~~）创建。这个功能在 GitHub Flavored Markdown 中得到广泛支持，但在标准 Markdown 中可能不被支持。

~~这是删除线文本~~

下划线

标准 Markdown 不直接支持下划线格式，但可以使用 HTML 标签来实现：

<u>这是下划线文本</u>

文本格式化最佳实践

在使用文本格式化时，应该遵循一些重要的原则。首先，格式化应该有明确的目的，避免过度使用。粗体用于强调重要概念，斜体用于引用或轻微强调，删除线用于表示修订内容。

其次，保持格式化的一致性。在同一文档中，应该使用相同的符号来创建相同的格式。例如，如果选择使用星号创建粗体，就应该在整个文档中都使用星号，而不是混合使用星号和下划线。

最后，注意格式化符号周围的空格。格式化符号应该紧贴被格式化的文本，不应该有额外的空格。

**正确的粗体**
** 错误的粗体 **

段落和换行

段落和换行的处理是 Markdown 中一个容易被误解的概念。理解这些规则对于创建格式良好的文档至关重要。

段落创建

在 Markdown 中，段落是由一个或多个连续的文本行组成，段落之间用一个或多个空行分隔。这个规则看似简单，但在实际使用中经常被忽视，导致文档格式不符合预期。

这是第一个段落。这个段落包含多个句子，它们会被渲染在同一个段落中。

这是第二个段落。注意上面有一个空行将两个段落分开。

重要的是要理解，仅仅按回车键并不会创建新段落。如果两行文本之间没有空行，它们会被合并为同一个段落。

这是第一行
这是第二行

# 上面两行会被合并为一个段落

这是第三行

这是第四行

# 上面两行是两个独立的段落

换行创建

有时候我们需要在段落内创建换行，而不是新段落。Markdown 提供了几种方法来实现这一点，但最可靠的方法是在行末添加两个或更多空格，然后按回车键。

这是第一行  
这是第二行，注意上一行末尾有两个空格

另一种方法是使用 HTML 的 <br> 标签：

这是第一行<br>
这是第二行

段落格式化最佳实践

在处理段落和换行时，有几个重要的最佳实践。首先，不要在段落开头添加空格或制表符来缩进，这可能导致意外的格式化效果，特别是在代码块的处理上。

其次，使用空行来分隔段落，这不仅符合 Markdown 规范，也提高了纯文本状态下的可读性。即使在 Markdown 编辑器中，清晰的段落分隔也有助于内容的组织和编辑。

对于换行，虽然行末双空格是标准方法，但由于空格在编辑器中不可见，容易被意外删除。在需要精确控制换行的场景中，使用 HTML <br> 标签可能是更可靠的选择。

列表语法

列表是组织信息的重要工具，Markdown 支持有序列表和无序列表两种类型。列表语法简单直观，但在嵌套和复杂结构的处理上需要注意一些细节。

无序列表

无序列表使用星号（*）、加号（+）或连字符（-）作为列表标记。三种标记在功能上完全相同，但为了保持一致性，建议在同一文档中使用相同的标记。

- 第一项
- 第二项
- 第三项

* 第一项
* 第二项
* 第三项

- 第一项
- 第二项
- 第三项

列表标记后必须跟一个空格，然后是列表项的内容。这个空格是必需的，没有空格的话，文本不会被识别为列表项。

有序列表

有序列表使用数字加点号的形式创建。有趣的是，实际的数字并不重要，Markdown 会自动生成正确的序号。这个特性使得在编辑过程中插入或删除列表项变得更加容易。

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

# 下面的列表会产生相同的结果

1. 第一项
1. 第二项
1. 第三项

# 甚至这样也可以

3. 第一项
4. 第二项
5. 第三项

虽然数字可以不按顺序，但为了代码的可读性，建议使用正确的序号或者全部使用 1。

嵌套列表

列表可以嵌套，创建多层次的结构。嵌套通过缩进来实现，子列表项需要在父列表项下缩进四个空格或一个制表符。

1. 第一项
   - 子项 1
   - 子项 2
2. 第二项
   1. 有序子项 1
   2. 有序子项 2
3. 第三项

在嵌套列表中，可以混合使用有序和无序列表。缩进必须保持一致，否则可能导致列表结构混乱。

列表中的其他元素

列表项可以包含多个段落、代码块、引用等其他 Markdown 元素。关键是保持正确的缩进，确保这些元素被识别为列表项的一部分。

1. 第一项

   这是第一项的第二段落。注意缩进。

2. 第二项

   > 这是第二项中的引用块。

这是第二项中的代码块


3. 第三项

列表最佳实践

使用列表时，应该注意几个重要的实践原则。首先，保持列表标记的一致性。在同一个列表中，使用相同的标记符号。其次，注意缩进的准确性，特别是在嵌套列表和包含多个元素的列表项中。

对于长列表，考虑使用有序列表，即使顺序不重要，因为有序列表在引用特定项目时更加方便。在列表项较长时，可以考虑在列表项之间添加空行来提高可读性。

链接语法

链接是连接网络内容的重要元素，Markdown 提供了多种创建链接的方法。掌握这些方法能够让您创建更加丰富和互联的文档。

内联链接

内联链接是最常用的链接格式，语法为 [链接文本](URL "可选标题")。链接文本是显示给读者的文字，URL 是链接的目标地址，可选标题会在鼠标悬停时显示。

[ToMarkdown.org](https://tomarkdown.org/zh "最好的 Markdown 转换工具")
[GitHub](https://github.com)
[联系我们](mailto:[email protected])

内联链接的优势是所有信息都在一处，易于阅读和维护。但在链接较多的文档中，可能会影响文本的可读性。

引用式链接

引用式链接将链接定义与链接使用分离，提高了文档的可读性。这种方法特别适用于包含大量链接的长文档。

这是一个指向 [ToMarkdown.org][1] 的链接。
这是另一个指向 [GitHub][github] 的链接。

[1]: https://tomarkdown.org "Markdown 转换工具"
[github]: https://github.com "代码托管平台"

引用式链接的标识符可以是数字、字母或单词，不区分大小写。链接定义可以放在文档的任何位置，但通常放在段落末尾或文档末尾。

自动链接

对于简单的 URL 或邮箱地址，Markdown 支持自动链接功能。将 URL 或邮箱地址用尖括号包围，就会自动创建链接。

<https://tomarkdown.org>
<[email protected]>

许多现代 Markdown 解析器还支持不使用尖括号的自动链接识别，但为了确保兼容性，建议使用尖括号。

内部链接

在长文档中，经常需要创建指向文档内部章节的链接。Markdown 支持使用标题作为锚点的内部链接。

[跳转到基础语法](#基础语法核心)
[查看常见问题](#常见问题解答)

标题锚点的生成规则是：将标题转换为小写，空格替换为连字符，移除特殊字符。不同的 Markdown 解析器可能有略微不同的规则，建议在使用前进行测试。

链接最佳实践

创建链接时，应该遵循一些重要的最佳实践。首先，链接文本应该具有描述性，避免使用"点击这里"或"更多信息"等通用文本。好的链接文本应该让读者知道点击后会看到什么内容。

# 好的链接文本

[Markdown 官方语法文档](https://daringfireball.net/projects/markdown/syntax)

# 不好的链接文本

[点击这里](https://daringfireball.net/projects/markdown/syntax) 查看 Markdown 语法

其次，对于外部链接，考虑添加标题属性来提供额外信息。这不仅改善了用户体验，也有助于搜索引擎优化。

最后，在使用引用式链接时，保持引用标识符的一致性和可读性。使用有意义的标识符而不是随机数字，这有助于文档的维护。

图片语法

图片是现代文档中不可或缺的元素，Markdown 的图片语法与链接语法非常相似，只是在前面添加了感叹号。

内联图片

内联图片的语法为 ![替代文本](image-url "可选标题")。替代文本在图片无法显示时显示，也用于屏幕阅读器的无障碍访问。

![Markdown Logo](https://markdown-here.com/img/icon256.png "Markdown 标志")
![本地图片](markdown_syntax_hero.png)

替代文本虽然是可选的，但强烈建议提供，这不仅有助于无障碍访问，也有利于搜索引擎优化。

引用式图片

与链接类似，图片也支持引用式语法，这在需要多次使用同一图片或管理大量图片时特别有用。

![Markdown Logo][logo]
![另一个图片][pic2]

[logo]: https://markdown-here.com/img/icon256.png "Markdown 标志"
[pic2]: markdown_syntax_comparison.png "示例图片"

图片尺寸控制

标准 Markdown 不支持直接控制图片尺寸，但可以使用 HTML 标签来实现：

<img src="markdown_syntax_hero.png" alt="描述" width="300" height="200">
<img src="markdown_syntax_hero.png" alt="描述" style="width: 50%;">

图片最佳实践

使用图片时，有几个重要的最佳实践需要遵循。首先，始终提供有意义的替代文本，描述图片的内容和作用。这对于视觉障碍用户和搜索引擎都很重要。

其次，考虑图片的文件大小和加载速度。在网络文档中，过大的图片会影响页面加载速度。建议对图片进行适当的压缩和优化。

最后，使用相对路径来引用本地图片，这使得文档更容易移植和分享。同时，确保图片文件与 Markdown 文档一起管理，避免链接失效。

代码语法

代码语法是 Markdown 中最重要的功能之一，特别是在技术文档中。Markdown 提供了内联代码和代码块两种方式来显示代码。

内联代码

内联代码用于在段落中插入简短的代码片段，使用反引号（`）包围代码文本。

使用 `console.log()` 函数来输出信息。
在 HTML 中，`<div>` 是一个常用的容器元素。

如果代码本身包含反引号，可以使用多个反引号来包围：

`` 这里有一个反引号 ` 在代码中 ``

代码块

代码块用于显示多行代码，有两种创建方法：缩进式和围栏式。

缩进式代码块

通过在每行前添加四个空格或一个制表符来创建代码块：

    function hello() {
        console.log("Hello, World!");
    }
围栏式代码块

使用三个反引号（```）或三个波浪号（~~~）来包围代码块，这种方法更加灵活和常用：

```
function hello() {
    console.log("Hello, World!");
}
```

语法高亮

围栏式代码块支持语法高亮，只需在开始的三个反引号后指定编程语言：

```javascript
function hello() {
  console.log("Hello, World!");
}
```

```python
def hello():
    print("Hello, World!")
```

```css
.container {
  max-width: 1200px;
  margin: 0 auto;
}
```

代码最佳实践

使用代码语法时，应该遵循一些重要的实践原则。首先，为代码块指定正确的编程语言，这不仅启用语法高亮，也有助于代码的理解和维护。

其次，保持代码的格式化和缩进一致。虽然 Markdown 会保留代码块中的格式，但良好的代码格式有助于阅读和理解。

对于长代码块，考虑添加注释来解释关键部分。在技术文档中，代码的可理解性与正确性同样重要。

最后，在内联代码中，避免使用过长的代码片段。如果代码超过几个单词，考虑使用代码块来显示。

引用语法

引用语法用于标识引用的文本、重要的说明或者创建视觉上的层次结构。Markdown 的引用语法简单而强大，支持多层嵌套和复杂结构。

基本引用

使用大于号（>）在行首创建引用块。引用块可以包含任何其他 Markdown 元素，包括标题、列表、代码块等。

> 这是一个引用块。
> 它可以包含多行文本。
>
> 引用块中也可以有段落。

嵌套引用

引用块可以嵌套，通过使用多个大于号来实现不同的嵌套级别：

> 这是第一级引用。
>
> > 这是第二级引用。
> >
> > > 这是第三级引用。
>
> 回到第一级引用。

引用中的其他元素

引用块可以包含其他 Markdown 元素，如标题、列表、代码块等：

> ## 引用中的标题
>
> 1. 引用中的列表项
> 2. 另一个列表项
>
> ```
> 引用中的代码块
> ```
>
> 这是引用中的普通段落。

引用最佳实践

使用引用语法时，应该注意几个重要的实践原则。首先，引用应该有明确的目的，如标识引用的文本、重要的警告信息或者创建视觉层次。

其次，在长引用中，保持适当的段落分隔和格式化。这有助于提高引用内容的可读性。

最后，避免过度嵌套引用。虽然 Markdown 支持多层嵌套，但过深的嵌套会影响可读性。一般建议不超过三层嵌套。

分隔线

分隔线用于在文档中创建视觉分隔，标识不同章节或主题的转换。Markdown 提供了三种创建分隔线的方法。

分隔线语法

可以使用三个或更多的连字符（-）、星号（*）或下划线（_）来创建分隔线：

---
---

---

这三种方法产生相同的效果，选择哪种主要是个人偏好问题。为了保持一致性，建议在同一文档中使用相同的符号。

分隔线最佳实践

使用分隔线时，应该注意几个重要的原则。首先，分隔线前后应该有空行，这确保了分隔线被正确识别，也提高了文档的可读性。

其次，不要过度使用分隔线。分隔线应该用于标识重要的内容转换，而不是简单的装饰。过多的分隔线会分散读者的注意力。

最后，考虑使用标题来代替分隔线进行内容组织。在大多数情况下，适当的标题结构比分隔线更有效地组织内容。

转义字符

在 Markdown 中，某些字符具有特殊含义，如星号用于创建粗体或斜体。当需要显示这些字符的字面意思时，需要使用转义字符。

需要转义的字符

以下字符在 Markdown 中具有特殊含义，可能需要转义：

\ 反斜杠
` 反引号

- 星号
  \_ 下划线
  {} 大括号
  [] 方括号
  () 圆括号

# 井号

- 加号

* 连字符
  . 点号
  ! 感叹号

转义方法

使用反斜杠（\）来转义特殊字符：

\*这不是斜体文本\*
\#这不是标题
\[这不是链接\]

转义最佳实践

在使用转义字符时，应该注意几个重要的原则。首先，只在必要时使用转义。如果字符在当前上下文中不会被误解为 Markdown 语法，通常不需要转义。

其次，在代码块和内联代码中，大多数字符不需要转义，因为它们会被按字面意思处理。

最后，了解不同 Markdown 解析器的差异。某些解析器可能对转义字符的处理略有不同，在跨平台使用时需要注意这些差异。

扩展语法进阶

Markdown 平台应用

扩展语法是在基础 Markdown 语法之上添加的功能，这些功能在不同的 Markdown 解析器中可能有不同的支持程度。了解这些扩展语法能够让您创建更加丰富和功能强大的文档。

表格语法

表格是组织数据的重要工具，虽然不在原始 Markdown 规范中，但现在几乎所有现代 Markdown 解析器都支持表格语法。

基础表格

表格使用管道符（|）来分隔列，第二行使用连字符（-）来定义表头：

| 姓名 | 年龄 | 职业     |
| ---- | ---- | -------- |
| 张三 | 25   | 工程师   |
| 李四 | 30   | 设计师   |
| 王五 | 28   | 产品经理 |

表格对齐

可以在分隔行中使用冒号（:）来控制列的对齐方式：

| 左对齐   | 居中对齐 |   右对齐 |
| :------- | :------: | -------: |
| 内容     |   内容   |     内容 |
| 更多内容 | 更多内容 | 更多内容 |
  • :------- 左对齐（默认）
  • :------: 居中对齐
  • -------: 右对齐

表格最佳实践

创建表格时，应该注意几个重要的实践原则。首先，保持表格的简洁性。过于复杂的表格在移动设备上可能难以阅读，考虑将复杂表格拆分为多个简单表格。

其次，为表格提供清晰的表头。表头应该准确描述列的内容，有助于读者理解数据。

最后，在表格较大时，考虑使用对齐来提高可读性。数字通常右对齐，文本左对齐，标题居中对齐。

任务列表

任务列表是 GitHub Flavored Markdown 引入的功能，现在被广泛支持。它们特别适用于项目管理和待办事项跟踪。

- [x] 完成的任务
- [ ] 未完成的任务
- [x] 另一个完成的任务
- [ ] 待办事项
  - [ ] 子任务 1
  - [x] 子任务 2

任务列表可以嵌套，也可以与其他列表元素混合使用。在支持交互的平台上，用户可以直接点击复选框来切换任务状态。

脚注

脚注允许您在文档中添加额外的解释或引用，而不会打断主要内容的流畅性。

这是一个包含脚注的句子[^1]。

这是另一个脚注[^note]。

[^1]: 这是第一个脚注的内容。
[^note]: 这是命名脚注的内容，可以包含多个段落。

    脚注可以包含多个段落，只需要保持适当的缩进。

定义列表

定义列表用于创建术语和定义的配对，在技术文档中特别有用：

术语 1
: 定义 1

术语 2
: 定义 2a
: 定义 2b

数学公式

许多 Markdown 解析器支持 LaTeX 风格的数学公式，使用美元符号（$）来标识：

内联公式：$E = mc^2$

块级公式：

$$
\sum_{i=1}^{n} x_i = x_1 + x_2 + \cdots + x_n
$$

高亮文本

某些 Markdown 解析器支持高亮文本，使用双等号（==）：

==这是高亮文本==

下标和上标

下标和上标在科学文档中经常使用：

H~2~O（下标）
X^2^（上标）

平台特性差异

不同的平台和应用程序对 Markdown 的支持程度和实现方式可能有所不同。了解这些差异有助于您在不同平台上创建兼容的内容。

GitHub Flavored Markdown (GFM)

GitHub Flavored Markdown 是 GitHub 平台使用的 Markdown 变体，在标准 Markdown 基础上增加了许多实用功能[8]。

表格支持

GFM 完全支持表格语法，包括对齐控制和复杂表格结构。

任务列表

GFM 引入了交互式任务列表，用户可以直接在界面上勾选任务。

删除线

GFM 支持使用双波浪号创建删除线文本：

~~删除的文本~~

自动链接

GFM 会自动将 URL 转换为链接，无需使用尖括号：

https://github.com 会自动变成链接

代码语法高亮

GFM 支持丰富的语法高亮，包括大多数主流编程语言。

表情符号

GFM 支持使用冒号语法插入表情符号：

:smile: :heart: :thumbsup:

GitLab Markdown

GitLab 的 Markdown 实现基本兼容 GFM，但增加了一些特有功能：

颜色标识

GitLab 支持颜色代码的可视化显示：

`#FF0000` 会显示红色块

图表支持

GitLab 支持 Mermaid 图表语法：

```mermaid
graph TD
    A[开始] --> B[处理]
    B --> C[结束]
```

Reddit Markdown

Reddit 使用简化的 Markdown 实现，支持基础语法但缺少一些高级功能：

  • 不支持表格
  • 不支持脚注
  • 支持上标：^上标文本^
  • 支持删除线：删除文本

Discord Markdown

Discord 支持有限的 Markdown 语法，主要用于文本格式化：

**粗体**
_斜体_
**下划线**
~~删除线~~
`代码`

Notion Markdown

Notion 支持大部分标准 Markdown 语法，并且可以与其块编辑器无缝集成：

  • 支持所有基础语法
  • 支持表格
  • 支持任务列表
  • 支持数学公式
  • 支持代码块语法高亮

Obsidian Markdown

Obsidian 是一个知识管理工具，支持扩展的 Markdown 语法：

双向链接

[[链接到其他笔记]]
[[笔记名称|显示文本]]

标签

#标签 #嵌套/标签

数学公式

完全支持 LaTeX 数学公式，包括内联和块级公式。

高级技巧和最佳实践

掌握基础语法后，了解一些高级技巧和最佳实践能够让您更高效地使用 Markdown，创建更专业的文档。

HTML 混合使用

Markdown 允许在文档中直接使用 HTML 标签，这为复杂格式化提供了灵活性。

常用 HTML 标签

<div align="center">
  <img src="markdown_syntax_hero.png" alt="居中图片" width="300">
</div>

<details>
<summary>点击展开</summary>
这里是隐藏的内容。
</details>

<kbd>Ctrl</kbd> + <kbd>C</kbd>

<mark>高亮文本</mark>

HTML 使用最佳实践

在使用 HTML 时，应该遵循几个重要原则。首先，只在 Markdown 无法实现所需格式时使用 HTML。过度使用 HTML 会降低文档的可读性和可移植性。

其次，确保 HTML 标签正确闭合，避免影响文档的其他部分。

最后，考虑兼容性。某些 Markdown 解析器可能不支持所有 HTML 标签，在跨平台使用时需要测试。

文档结构最佳实践

标题层次

建立清晰的标题层次结构是创建专业文档的关键：

# 文档标题（H1）- 每个文档只有一个

## 主要章节（H2）

### 子章节（H3）

#### 小节（H4）

##### 子小节（H5）- 谨慎使用

###### 最小节（H6）- 很少使用

目录创建

对于长文档，创建目录能够显著改善用户体验：

## 目录

1. [介绍](#介绍)
2. [安装](#安装)
   - [系统要求](#系统要求)
   - [安装步骤](#安装步骤)
3. [使用指南](#使用指南)
4. [常见问题](#常见问题)

可读性优化

段落长度

保持适当的段落长度，一般建议每段不超过 3-4 句话。长段落在屏幕上难以阅读，特别是在移动设备上。

列表使用

合理使用列表来组织信息：

  • 使用无序列表展示并列的项目
  • 使用有序列表展示步骤或优先级
  • 使用任务列表跟踪进度

视觉分隔

使用空行、分隔线和标题来创建视觉分隔，帮助读者理解文档结构。

协作和版本控制

Git 友好的格式

在使用 Git 进行版本控制时，遵循一些格式化原则能够改善协作体验：

  • 每句话单独一行，便于跟踪修改
  • 避免过长的行，建议每行不超过 80-100 字符
  • 使用一致的缩进和格式

注释和元数据

在文档中添加适当的注释和元数据：

<!--
文档信息：
作者：张三
创建日期：2025-01-01
最后修改：2025-01-15
版本：1.2
-->

# 文档标题

<!-- TODO: 添加更多示例 -->

性能和优化

图片优化

  • 使用适当的图片格式（JPEG 用于照片，PNG 用于图标）
  • 压缩图片以减少文件大小
  • 使用相对路径引用本地图片

链接管理

  • 定期检查外部链接的有效性
  • 使用引用式链接管理重复的 URL
  • 为重要链接提供备用方案

常见问题解答

Q: 为什么我的 Markdown 在不同平台上显示不同？

A: 不同的 Markdown 解析器可能对语法的解释略有不同，特别是在扩展语法方面。为了确保兼容性，建议：

  1. 使用标准 Markdown 语法作为基础
  2. 在使用扩展语法前确认目标平台的支持情况
  3. 在多个平台上测试文档的显示效果
  4. 使用 CommonMark 规范作为参考标准

Q: 如何在 Markdown 中创建复杂的表格？

A: 标准 Markdown 表格功能有限，对于复杂表格，可以考虑以下方案：

  1. 将复杂表格拆分为多个简单表格
  2. 使用 HTML 表格标签获得更多控制
  3. 使用专门的表格生成工具
  4. 考虑使用图片来展示复杂的表格数据

Q: 如何在 Markdown 中添加视频？

A: 标准 Markdown 不直接支持视频嵌入，但可以使用以下方法：

  1. 使用 HTML <video> 标签
  2. 嵌入 YouTube 或其他平台的 iframe 代码
  3. 使用视频的缩略图作为链接到视频的图片
  4. 某些平台支持特定的视频嵌入语法

Q: 如何处理 Markdown 中的特殊字符？

A: 当需要显示具有特殊含义的字符时：

  1. 使用反斜杠（\）进行转义
  2. 在代码块或内联代码中，大多数字符会被按字面意思处理
  3. 使用 HTML 实体编码（如 &amp; 表示 &）
  4. 了解目标平台的特殊字符处理规则

Q: 如何优化 Markdown 文档的 SEO？

A: 虽然 Markdown 本身是纯文本，但可以通过以下方式优化 SEO：

  1. 使用清晰的标题层次结构
  2. 为图片提供有意义的替代文本
  3. 使用描述性的链接文本
  4. 在转换为 HTML 时添加适当的元数据
  5. 保持内容的高质量和相关性

语法速查表

Markdown 语法速查表

基础语法快速参考

元素 Markdown 语法
标题 # H1 ## H2 ### H3
粗体 **粗体文本**
斜体 *斜体文本*
删除线 ~~删除文本~~
内联代码 `代码`
代码块 代码块
链接 [标题](https://www.example.com)
图片 ![alt text](markdown_syntax_hero.png)
无序列表 - 项目
有序列表 1. 项目
引用 > 引用文本
分隔线 ---

扩展语法快速参考

元素 Markdown 语法
表格 | 标题 | 标题 |
|---|---|
| 内容 | 内容 |
脚注 文本[^1] 和 [^1]: 脚注内容
任务列表 - [x] 完成的任务
- [ ] 未完成的任务
高亮 ==高亮文本==
下标 H~2~O
上标 X^2^

常用 HTML 标签

功能 HTML 语法
居中对齐 <div align="center">内容</div>
图片尺寸 <img src="markdown_syntax_hero.png" width="300">
换行 <br>
键盘按键 <kbd>Ctrl</kbd>
高亮文本 <mark>高亮</mark>
折叠内容 <details><summary>标题</summary>内容</details>

参考资料

[1] Gruber, J. (2004). "Markdown: Syntax". Daring Fireball. https://daringfireball.net/projects/markdown/syntax

[2] Gruber, J. (2004). "Markdown". Daring Fireball. https://daringfireball.net/projects/markdown/

[3] CommonMark Spec. (2024). "CommonMark Specification". https://commonmark.org/

[4] GitHub. (2024). "GitHub Flavored Markdown Spec". https://github.github.com/gfm/

[5] Stack Overflow Developer Survey. (2023). "Developer Tools and Technologies". https://survey.stackoverflow.co/2023/

[6] CommonMark. (2024). "ATX Headings". https://spec.commonmark.org/0.30/#atx-headings

[7] CommonMark. (2024). "Emphasis and Strong Emphasis". https://spec.commonmark.org/0.30/#emphasis-and-strong-emphasis

[8] GitHub. (2024). "Basic Writing and Formatting Syntax". https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax

探索更多功能

使用我們的工具來練習你學到的知識。

線上編輯器HTML 轉換器