Markdown 文档撰写入门指南
Markdown是2004年John Gruber与Aaron Schwartz开发的轻量级标记语言，语法直观，支持标题、列表、强调等格式，可转换为HTML等多种格式，广泛用于技术文档、README文件等，有GitHub Flavored Markdown等变体，CommonMark正推动其标准化。
简介
你可能听说过Markdown，但没听说过也没关系。
用户最初接触Markdown的典型方式通常是在互联网论坛上格式化文本。至少，你可能在GitHub的README文件中见过它。Markdown的一个专业用途是编写技术文档。
技术文档作者在生成文档时有多种令人眼花缭乱的选择。这就是为什么许多作者选择Markdown——它易于使用，并且可以在不同平台之间灵活转换（至少在理论上是这样）。
1. 什么是Markdown？
你可能想知道，Markdown到底是什么？
Markdown是一种轻量级标记语言。它允许你使用典型的格式设置技术来设置数字文本文档的样式：例如，标题、强调、列表、图像和链接。Markdown文件存储为.md或.markdown格式。此外，Markdown可以选择性地转换为XHTML或HTML，以便在浏览器中很好地显示。
Markdown的许多用途包括README文件、在线讨论论坛中撰写消息、使用纯文本编辑器创建富文本、电子邮件以及技术文档。使用Markdown的流行网站包括GitHub、Trello、Reddit、SourceForge和StackExchange等。
你可能也想使用Markdown来格式化你的文档。它可以由与文本编辑器链接的静态站点生成器托管，例如Hugo，或者你可以使用端到端的专有解决方案来生成Markdown文件。
这种轻量级标记语言是在限制性强的所见即所得编辑器与直接用HTML格式化内容之间的一种折中方案。作者可以在不诉诸完整的HTML标签的情况下，最大程度地控制其信息的呈现方式。同时，Markdown解析器也支持插入HTML代码块，以扩展Markdown有限的语法，以便实现更复杂的设计。2. Markdown的后端
Markdown不仅仅是表面看起来那么简单。本节将帮助您了解在格式化Markdown文件与为网络生成最终渲染输出之间，幕后发生了什么。
除非您使用像文本编辑器和静态网站生成器这样的工具组合，否则不一定需要知道幕后的过程，但有时了解一下还是有好处的！
这个过程包括学习Markdown语法，然后理解该文件如何被渲染。
- 使用文本编辑器或专门的Markdown应用程序创建Markdown文件
- 在专门的Markdown应用程序中打开Markdown文件
- 使用Markdown应用程序和解析器将Markdown文件转换为HTML文档
- 在网页浏览器中查看HTML文件
或者，市面上也有其他工具（如Pandoc），可以将您的Markdown文件转换为其他格式，包括DO客户体验(CX)、PDF、RTF、ODT或EPUB。例如，您可以将Markdown文件转换为电子书，每个Markdown文件作为一个独立的章节。
现在就在Baklib注册，开始您的14天免费试用。
3. Markdown 的历史
Markdown 由 John Gruber 于 2004 年与 Aaron Schwartz 合作开发，因此拥有一定的历史背景。Gruber 厌倦了使用标准 HTML 格式化网页内容的复杂过程，这便是他创造 Markdown 的原因。
“Markdown 格式化语法的首要设计目标是使其尽可能易于阅读。其理念是，一份 Markdown 格式的文档应该能够以纯文本形式直接发布，而无需看起来像是被标签或格式化指令标记过。” —— John Gruber
在 Markdown 出现之前，可用的只有其他标记语言，如 HTML 和 LaTeX。Markdown 作为一种轻量级标记语言应运而生，主要面向网络写作者，其中许多人也同时是开发者。这使得 Markdown 特别适合那些需要与开发团队协作的技术文档。
回到历史本身。关于 Markdown 的冲突很快出现，主要问题在于语法缺乏标准化。当时没有
Markdown 规范，而 Gruber 也不愿意扩展语法。最终，人们开发了自己独立的实现（也称为“变体”或“风味”）。这导致了将 Markdown 从一个系统转换到另一个系统时出现问题。例如，由于语法偏差不兼容，使用 Pandoc 将 GitHub wiki 转换为 docbook 比原本应有的难度要大得多。
与HTML不同，Markdown语法并没有互联网标准。因此，CommonMark作为一项非官方倡议应运而生，旨在标准化所有不同的Markdown“变体”。CommonMark是一个标准、明确的Markdown语法规范，并附带一套全面的测试，用于根据该规范验证Markdown的实现。
这个非常简短的总结将我们带到了今天。
4. Markdown变体
正如我们刚才提到的，Markdown的非标准化特性催生了许多流行的“变体”——本质上是原始Markdown语法的扩展。这样做的原因是为了增加原始语法中没有的额外功能，例如表格、引用和语法高亮。
一些Markdown变体已经变得非常常用，例如GitHub变体，称为GitHub Flavored Markdown。它包括额外的功能，如表格、编程语言选择和语法着色。
考虑到Markdown的变体，如果你的Markdown文件使用了额外的语法，而不同的编辑器不支持这些语法，那么你的文件可能并不总是与所有编辑器兼容。Markdown实现之间缺乏一致性是人们对其的主要问题之一。
以下是当今最常见的Markdown变体列表。
5. 为什么要学习Markdown？
尽管存在一些问题，但许多人仍然在使用Markdown。你甚至不需要是开发人员就能掌握其基础知识。Markdown的优点在于，一旦你知道它是如何工作的，就很容易编写。它非常直观，易于上手，因为它基于许多人都已经接触过的电子邮件格式约定。
相较于传统的发布系统，Markdown 提供了更流畅的工作流程。与普通的写作用户界面（例如 Microsoft Word 或 Google Docs）不同，您无需中断写作去选择格式按钮。格式设置直接内嵌在文本中，并且其外观就是想要实现的效果。换句话说，列表看起来就是列表，强调看起来就是强调。
您也可以轻松阅读 Markdown 的原始状态，这与原始 HTML（充满了标签）不同。Markdown 语法与您写作的其他部分完美融合，其含义直观清晰。
Markdown 文件是可移植的，并且可以在任何兼容 Markdown 的编辑器中打开，以防您想要更换应用程序。尽管在实践中这可能不那么简单，但拥有这个选项是好的。Markdown 是平台无关的，这意味着您可以在任何文本编辑器中创建 Markdown 文件。它在许多不同的网站和应用程序中都有用。
这是一项可重复使用的技能。Markdown 用途广泛，因此您只需学习一次，就可以将其用于许多不同的活动。您可以使用 Markdown 做笔记、为网站创建内容或生成可直接打印的文档。
Markdown 的基础知识
值得学习 John Gruber 概述的基本 Markdown 语法，该语法得到了大多数 Markdown 应用程序的支持。您可能会发现 Markdown 的语法相对直观，容易掌握。如果您愿意，也可以在任何 Markdown 文件中直接编写 HTML。
你可以立即使用浏览器中的工具（如Dillinger）开始使用Markdown。
标题
所有Markdown文件都应包含标题。你需要一个1级标题作为Markdown文件的标题，并且在正文中至少使用2级标题作为子标题。标题使你的文本更易读，并有助于划分主题。
在Markdown中，通过在包含标题的行前添加井号 (#) 来格式化标题。最多可以使用六个井号，井号的数量对应标题的级别。
你的文本将如下所示：
# 1级标题
## 2级标题
### 3级标题
#### 4级标题
##### 5级标题
###### 6级标题
段落
在编写Markdown正文时，你可能希望将信息分成段落（每个段落之间有明显的间隔）。
段落之间通过一个空行（不包含任何字符的行）来分隔。
你的文本将如下所示：
段落1
段落2
换行
有时，你可能希望通过插入新行来分隔信息，其间距比段落格式要小。这被称为换行。
要在Markdown文件中插入换行，在行末至少输入两个空格然后按回车。这将为你的文本渲染一个新行。
💛🧡🧡客户评价：喜欢它为我作为一名开发人员提供的一般可定制性和自由度。还喜欢免费计划包括云托管和慷慨的配额。可以轻松启动快速副项目或 MVP。欣赏平台的一般简约、集中功能集和模块化。
你的文本将如下所示：
第1行
第2行
强调
在Markdown中编写内容时，你可能希望对某些单词或短语进行更多强调。第一种强调文本的方式是使用斜体。
通过在文本两侧各加一个星号（或者，你可以用下划线代替星号），你可以将文本设为斜体。一旦你的应用程序检测到第二个星号，该元素的格式就被视为“闭合”了。
你的文本会像这样显示：
*这段文本是斜体*
_这段文本也是斜体_
加粗格式提供的强调程度比斜体稍重一些，但操作方式完全相同。这次，用两个星号包裹你想要加粗的文本（或者，你可以用下划线代替星号）。
你的文本会像这样显示：
这段文本是加粗的
__这段文本也是加粗的__
如果你真的想强调一个观点，你可以让文本同时加粗和斜体，以赋予它更大的分量！要让文本同时加粗和斜体，请使用三个星号（或三个下划线）包裹你的单词或短语。
你的文本会像这样显示：
*这段文本是斜体且加粗的。
*
___这段文本也是斜体且加粗的___
链接（内联）
有时，在编写Markdown内容时，我们想要链接到外部网站。使用两对方括号有一个简单的方法可以做到这一点。
要在Markdown中格式化内联链接，你需要用方括号包裹链接文本。将包裹在方括号中的链接文本与包含URL的括号并排放置（确保链接文本和链接之间没有空格）。
你的文本会像这样显示：
[这是链接文本](这是链接URL)
如果你想为链接添加标题，请在链接旁边的引号内插入你的替代文本。
你的文本会像这样显示：
[这是链接文本](这是链接URL "这是一个标题")
请注意，如果您想链接到本地文件，且该文件与您的其他 Markdown 文件位于同一服务器上，您可以使用斜杠后跟相对 URL 的格式来格式化链接。
您的文本将如下所示：
[这是链接文本](/这是一个相对 URL "这是一个标题")
图片
正如人们所说，一图胜千言。在 Markdown 文件中插入图片的格式与链接类似。
以感叹号开始图片格式化。接着，使用方括号包裹图片的替代文本，紧接着是包含图片 URL 的圆括号。确保感叹号、方括号和圆括号之间没有空格。
您的文本将如下所示：
当您的 Markdown 文件渲染为 HTML 时，图片将直接嵌入到正文文本中。
列表
无序列表
有时，您可能希望将内容格式化为列表，以便于阅读。
第一种选择是使用无序列表，其中列表中的每个项目前面都有一个项目符号。Markdown 允许您使用多种不同的符号来格式化列表：星号（*）、连字符（-）或加号（+）。
您可以选择自己喜欢的符号。得到的结果是相同的。
以下是一个示例列表：
* 这是一个列表项
* 这是一个列表项
* 这是一个列表项
* 这是一个列表项
有序列表
其他时候，您可能希望按顺序（1、2、3 等）在有序列表中呈现信息。格式化有序列表时，在每个列表项前加上一个数字，后跟一个句点和一个空格。
在Markdown中，您使用哪个数字来格式化列表并不重要，因为列表总是会渲染为1、2、3……以此类推。
您的文本将呈现为：
1. 这是一个列表项
2. 这是一个列表项
3. 这是一个列表项
4. 这是一个列表项
块引用
有时在Markdown中，我们想用引用的方式来参考外部来源。这被称为块引用。您可以在块引用的第一行前加上大于号或尖括号（>）来表示一个块引用。Gruber建议在块引用的每一行前都插入尖括号。
您的文本将呈现为：
这是一个块引用
这是一个块引用
这是一个块引用
7. 中级Markdown
现在您已经掌握了基本的Markdown，您可能想尝试一些稍微高级的格式。
水平分割线
水平分割线是一个有用的小元素，您可以用它在Markdown文件中视觉上分割文本块。水平分割线由三个或更多的连字符（-）、星号（*）或下划线（_）表示。无论您使用哪个符号，渲染出的输出效果都相同。
您的文本将呈现为：
代码块和代码片段
代码片段
当我们用Markdown写作时，经常需要引用代码片段作为示例。这在技术文档中尤其常见。Markdown允许您使用反引号（`）来包装代码片段以格式化它。第一个反引号“打开”片段，第二个反引号“关闭”它。
你的文本将像这样展示：`这是一个代码片段`
代码块
当你在 Markdown 文件中需要包含更大块的代码时，格式化代码块非常有用。通过使用一个制表符或四个空格缩进代码块的每一行来格式化你的代码块。
这是一个代码块
这是一个代码块
这是一个代码块
请记住，Markdown 的一些扩展，例如 GitHub Flavored Markdown，支持编程语言选择和语法高亮。原始的 Markdown 不支持这些样式。
立即注册 Baklib，开始你的 14 天免费试用
参考样式链接
在你的 Markdown 写作生涯中，可能会遇到需要包含参考样式链接的情况。这种格式不是将 URL 直接内联在链接文本旁边，而是将链接列在 Markdown 文件的其他地方（通常是在包含该链接的段落下方，或者文档末尾）。以这种方式格式化链接可以使你的 Markdown 内容更易于阅读。
要格式化参考样式链接，请将链接文本放在方括号中，然后在另一对方括号中加上你的标签。该标签充当锚点。
你的文本应如下所示：
[这是链接文本][这是一个标签]
链接的第二部分（放置在段落末尾或文件底部）使用三个属性进行格式化。
1. 你的标签放在方括号中，后跟冒号和至少一个空格
2. 你的链接 URL
3. 一个可选的链接标题，用双引号、单引号或括号括起来
你的文本将如下所示：
[这是一个标签]: 这是一个 URL “这是一个链接标题”
大多数人会按照文件中引用的顺序列出他们的链接。
转义
在 Markdown 中，你经常需要在文本中包含一些可能是 Markdown 语法一部分的字符（例如，星号）。你需要“转义”这些字符，这样你的 Markdown 应用就不会将这些字符解读为格式指令。
在 Markdown 中，你可以在字符前使用反斜杠来转义它，中间不要有空格。
你的文本应该像这样：
\*
你可以转义以下任何字符：
\ 反斜杠
` 反引号
* 星号
_ 下划线
{} 花括号
[] 方括号
() 圆括号
# 井号
+ 加号
– 减号（连字符）
. 点
! 感叹号
在块引用中的列表
有时，你可能想在 Markdown 中插入一个包含其他元素（如无序列表）的块引用。你需要将列表格式嵌套在块引用格式之内。
使用大于号（>）后跟一个空格来格式化你的块引用，包括在块引用的每一行前都要有这个符号。在你的大于号后面紧接着添加你的列表格式（*）。
你的文本应该像这样：
> 这是一个块引用
> * 这是一个块引用内的列表项
> * 这是一个块引用内的列表项
> * 这是一个块引用内的列表项
你可以直接在 Markdown 文件中插入 HTML 元素。例如，你可能想包含一个按钮。插入 HTML 的方式与在任何其他 HTML 文档中完全相同。
你的文本应该像这样：这是一个按钮
这种格式也适用于你的其他 Markdown 语法，例如强调。不使用
此元素为粗体
，你可以用 HTML 格式将其写为 此元素为粗体。
8. Markdown 编辑器
Markdown 得到了各种不同系统的支持，从结合静态网站生成器的文本编辑器到专门的 Markdown 网络应用程序。
一些编辑器内置了基本的 Markdown 功能，即使它们并非专门为 Markdown 设计。另一些则旨在扩展 Markdown 语法，例如 Ghost。
有针对不同操作系统（MacOS、Linux 或 Windows）的 Markdown 编辑器，或者你也可以使用基于网络的应用程序。
以下是一些最流行的 Markdown 编辑器的汇编，按系统分类：
MacOS
Windows
- iA Writer
- ghostwriter
- Markdown Monster
- Joplin
Linux
iOS/Android
Web
- Blot.im – 博客平台
- Smallvictori.es – 利用 DropBox 创建网站的平台
- StackEdit – 支持多种 Markdown 变体的浏览器内 Markdown 编辑器
- Dillinger – 基于浏览器的 Markdown 编辑器
- Ghost – 基于浏览器的博客平台
静态网站生成器
- Jekyll
- Hugo
-
Docusaurus
我们还想推荐我们自己的 Baklib 知识库软件，它提供了一个 Markdown 编辑器，用于格式化您的文档。
最后的话
使用 Markdown，您的工作有无限可能，从简单的笔记记录开始，到撰写博客，再到专业的文档创作。
通过掌握Markdown的基础知识，您将为更流畅的格式化和发布打开大门。支持Markdown的应用程序数量持续增长，使其成为您文档工作的绝佳选择。
为何不试试Baklib来管理您的文档呢？它内置了强大的Markdown编辑器。
可下载速查表
-
元素：标题
Markdown语法：# 标题 1
## 标题 2
### 标题 3
#### 标题 4
##### 标题 5
###### 标题 6 -
元素：段落
Markdown语法：段落1
段落2 -
元素：换行
Markdown语法：行1
行2 -
元素：强调
Markdown语法：*斜体*
粗体
*粗斜体
* -
元素：行内链接
Markdown语法：[链接文本](链接URL "链接标题") -
元素：图片
Markdown语法： -
元素：无序列表
Markdown语法：* 列表项
* 列表项
* 列表项 -
元素：有序列表
Markdown语法：1. 列表项
2. 列表项
3. 列表项 -
元素：引用块
Markdown语法：> 引用内容
