Markdown指南

什么是Markdown？

Markdown是一种轻量级标记语言，您可以用它为纯文本文档添加格式元素。它允许您使用简单、易读的语法创建格式化文本，可以转换为HTML和其他格式。

将Markdown视为一种无需复杂文字处理器即可编写格式化文档的方式。您只需在纯文本中添加特殊字符来指示格式，如粗体、斜体或代码。

为什么使用Markdown？

Markdown非常简单且易于学习。您可以在短短10分钟内掌握基础知识。格式符号直观 - 星号表示强调，井号表示标题。您只需输入并添加简单符号来格式化文本。

Markdown在任何平台和任何文本编辑器上都能工作。由于文件是纯文本，即使在几十年后也始终可读。文件轻量且加载迅速。

Markdown在各个平台都有广泛支持。GitHub、Reddit、Discord和Slack都使用Markdown。Obsidian、Notion和VS Code等流行应用程序原生支持它。这使其成为文档、笔记和Web内容的完美选择。

Markdown与Git等版本控制系统完美配合。您可以专注于内容而不受格式干扰。团队协作更容易，因为每个人都可以在没有特殊软件的情况下编辑文件。

Markdown开发历史

起源：原版Markdown（2004年）

Markdown最初由John Gruber在2004年创建，Aaron Swartz做出了重要贡献。Gruber将其设计为一种使用易读易写的纯文本格式编写的简单方式，可以转换为结构有效的HTML。这是John Gruber最初设计和实现的"核心"，包含最基本的格式语法 - 我们称之为"基本原版风味"。

基本语法（原版Markdown包含）：

  • •
    标题：使用#符号（# 标题）

  • •
    强调：

  • •
    斜体：使用*或_包围文本（*斜体*或_斜体_）
  • •
    粗体：使用**或__包围文本（**粗体**或__粗体__）

  • •
    列表：

  • •
    无序列表：使用*、-或+（- 项目）
  • •
    有序列表：使用数字和句点（1. 项目）
  • •
    链接：使用[链接文本](链接地址)
  • •
    图片：使用![图片描述](图片地址)

  • •
    代码块：用空格缩进（通常4个空格或1个Tab）

  • •
    引用：使用>符号（> 这是引用）
  • •
    水平线：使用---或***

问题：不一致的实现

然而，原版Markdown缺乏严格的正式规范。这导致不同Markdown解析器在处理边缘情况时行为不一致。

空白处理：例如，在列表项中，多少个空格的缩进算作子列表？是2个空格、3个空格还是4个空格？不同的解析器可能有不同的判断。

换行处理：在某些情况下，常规换行（\n）应该被解析为<br>（换行）标签，还是应该简单地作为文本中的空格处理？这也可能因解析器而异。

HTML混合使用：Markdown允许嵌入HTML。然而，在一些复杂的HTML结构中，Markdown解析器如何处理其中的Markdown语法也存在模糊区域。

解决方案：CommonMark（2014年）

2014年9月，引入了CommonMark来解决这些不一致问题。由John MacFarlane领导，它为Markdown提供了严格的规范。

CommonMark提供了精确的规范，其中每个边缘情况都有明确定义。它包括一个包含600多个测试用例的综合测试套件，以确保实现之间的一致性。该规范提供了一个参考实现，作为其他解析器遵循的标准。它保持与大多数现有Markdown文档的向后兼容性，同时确保明确的解析，相同的输入在所有兼容解析器中始终产生相同的输出。

扩展风味和附加功能

随着用户有不同的需求，出现了各种扩展的Markdown风味来满足特定要求。

GitHub风味Markdown（GFM）附加语法：

  • •
    表格：使用管道语法创建表格
  | 标题1 | 标题2 | 标题3 |
  |-------|-------|-------|
  | 单元格1 | 单元格2 | 单元格3 |
  | 单元格4 | 单元格5 | 单元格6 |
  • •
    删除线：使用~~包围文本（~~删除的文本~~）

  • •
    任务列表：创建交互式复选框

  - [x] 已完成任务
  - [ ] 未完成任务
  • •
    围栏代码块：使用带语言规范的三重反引号
  ```javascript
  function hello() {
    console.log("Hello World!");
  }
  ```
  • •
    自动链接：URL和电子邮件地址自动变为可点击

其他流行扩展：

  • •
    脚注：学术写作使用[^1]语法
  这是带脚注的句子[^1]。
  [^1]: 这是脚注内容。

结果：这是带脚注的句子¹。

  • •
    数学表达式：科学文档使用$E=mc^2$
  • •
    表情符号快捷方式：使用:smile:变成😊

  • •
    定义列表：用于词汇表和技术文档

  术语1
  : 术语1的定义
  
  术语2
  : 术语2的定义
  : 术语2的另一个定义

结果：创建带有突出显示术语和缩进定义的格式化列表

如何工作？

Markdown遵循简单的三步工作流程：

步骤1：创建Markdown文件

首先，使用任何文本编辑器创建带有.md或.markdown扩展名的纯文本文件。使用简单的格式符号编写内容：

步骤2：使用Markdown工具处理

您的.md文件然后由Markdown转换工具或处理器处理。这些工具读取您的Markdown文件并将其转换为所需的输出格式。

步骤3：输出到各种格式

Markdown处理器可以将您的文件转换为多种格式：

Web显示：

  • •
    转换为HTML用于网站、博客和Web应用程序

  • •
    在浏览器中显示具有适当样式的格式化内容

文档：

  • •
    转换为PDF用于可打印文档和报告

  • •
    生成Word文档（.docx）用于办公用途
  • •
    创建LaTeX用于学术论文和出版物

发布：

  • •
    生成电子书（EPUB格式）

  • •
    创建演示幻灯片
  • •
    制作文档网站

这个工作流程意味着您在Markdown中写一次，然后使用不同的工具将内容转换为您需要的任何格式 - 无论是在网站上显示、打印为PDF还是作为文档共享。

附加资源

基本文档