Markdown 参考指南

什么是 Markdown？

Markdown 是一种轻量级的标记语言，可用于向纯文本文档添加格式化元素。它由 John Gruber 于 2004 年创建，现已成为全球最流行的标记语言之一。

使用 Markdown 与使用 WYSIWYG 编辑器不同。在诸如 Microsoft Word 的应用程序中，您通过点击按钮来格式化文字和短语，更改会立即显示。Markdown 则不同。创建 Markdown 格式的文件时，需在文本中添加 Markdown 语法以指示哪些单词和短语应看起来有所不同。

例如，要表示一个标题，您在其前添加井号（如# 一级标题）。或者要使短语加粗，您在其前后各添加两个星号（如**这段文字加粗**）。如果您习惯于使用 WYSIWYG 应用程序，可能需要一段时间来适应在文本中看到 Markdown 语法。下图展示了一个在 Visual Studio Code 文本编辑器中显示的 Markdown 文件。

您可以使用文本编辑器应用程序向纯文本文件添加 Markdown 格式化元素。或者，您可以使用针对 macOS、Windows、Linux、iOS 和 Android 操作系统设计的众多 Markdown 应用程序之一。还有几个专为 Markdown 写作设计的基于 Web 的应用程序。

根据所使用的应用程序，您可能无法实时预览格式化后的文档。但这没关系。根据 Gruber 的说法，Markdown 的格式语法旨在使其尽可能易于阅读，不显眼，因此即使未呈现，Markdown 文件中的文本仍可阅读。

Markdown 格式语法的首要设计目标是使其可读性尽可能强。其理念是 Markdown 格式的文档应该能够直接发布为纯文本，看起来不像是被标记了标签或格式指令。

为什么使用 Markdown？

你或许会好奇为何人们选择 Markdown 而非 WYSIWYG 编辑器。当可以在界面中按下按钮格式化文本时，为何还要使用 Markdown 进行写作？实际上，人们偏爱 Markdown 而非 WYSIWYG 编辑器有以下几个原因。

Markdown 万能。人们利用它创建网站、文档、笔记、书籍、演示文稿、电子邮件以及技术文档。
Markdown 具有高度可移植性。含有 Markdown 格式文本的文件几乎可以用任何应用打开。如果你不再喜欢当前使用的 Markdown 应用，可以将 Markdown 文件导入到另一个 Markdown 应用中。这与像 Microsoft Word 这样的文字处理应用形成鲜明对比，后者将你的内容锁定在专属文件格式中。
Markdown 不受平台限制。你可以在运行任何操作系统的设备上创建 Markdown 格式的文本。
Markdown 经久不衰。即便将来你使用的应用停止工作，你仍然可以通过文本编辑应用阅读 Markdown 格式的文本。这对于需要永久保存的书籍、大学毕业论文和其他里程碑文档来说，是一个重要的考虑因素。
Markdown 无处不在。像 Reddit 和 GitHub 这样的网站支持 Markdown，还有很多桌面和基于 Web 的应用也支持它。

初试牛刀

开始使用 Markdown 的最佳方式就是实践。多亏了各种免费工具，这变得比以往任何时候都容易。

你甚至不需要下载任何东西。有几个在线 Markdown 编辑器可以让你尝试用 Markdown 写作。Dillinger 是最佳的在线 Markdown 编辑器之一。只需打开网站，在左侧窗格开始输入。右侧窗格会即时显示文档的预览效果。

在阅读本指南的过程中，你可能会希望保持 Dillinger 网站处于打开状态。这样，你可以边学边尝试语法。熟悉 Markdown 后，你也许想使用可安装在桌面电脑或移动设备上的 Markdown 应用。

它是如何工作的？

Dillinger 让 Markdown 写作变得简单，因为它隐藏了后台发生的细节，但了解这一过程的一般原理还是值得的。

当你使用 Markdown 写作时，文本会被存储在一个扩展名为 .md 或 .markdown 的纯文本文件中。然后呢？你的 Markdown 格式文件是如何转换成 HTML 或打印就绪文档的？

简短的回答是你需要一个 Markdown 应用 来处理 Markdown 文件。有许多可用的应用程序——从简单的脚本到外观类似 Microsoft Word 的桌面应用。尽管它们在视觉上有所不同，所有应用都做着同样的事情。像 Dillinger 一样，它们都将 Markdown 格式的文本转换为 HTML，以便在网页浏览器中显示。

Markdown 应用使用称为 Markdown 处理器 （通常也被称为 “解析器” 或 “实现”）的东西，将 Markdown 格式的文本输出为 HTML 格式。此时，你的文档可以在网页浏览器中查看，或与样式表结合后打印。你可以在下面的图表中看到这一过程的直观展示。注意： Markdown 应用和处理器是两个独立的组件。为了简洁起见，我在下图中将它们合并为一个元素（"Markdown 应用"）。

总结一下，这是一个四步过程：

使用文本编辑器或专用 Markdown 应用创建 Markdown 文件。文件应具有 .md 或 .markdown 扩展名。
在 Markdown 应用中打开 Markdown 文件。
使用 Markdown 应用将 Markdown 文件转换为 HTML 文档。
在网页浏览器中查看 HTML 文件，或使用 Markdown 应用将其转换为其他文件格式，如 PDF。

根据你使用的应用，这个过程从你的视角来看会有所差异。例如，Dillinger 实质上将步骤 1 至 3 合并为一个无缝界面——你只需在左侧窗格输入，渲染好的输出就会神奇地出现在右侧窗格。但如果你使用其他工具，比如带有静态网站生成器的文本编辑器，你会发现这个过程更为明显。

Markdown 适合做什么？

Markdown 是一种快速且简单的方式，用于记笔记、创建网站内容及制作打印就绪文档。

学习 Markdown 语法并不需要很长时间，一旦掌握了它，几乎在任何地方都可以使用 Markdown 进行写作。大多数人用 Markdown 来创建网络内容，但实际上，从电子邮件到购物清单，Markdown 都能很好地进行格式化处理。

以下是一些 Markdown 功能的示例用法。

网站

Markdown 为网络而设计，因此，有许多专门用于创建网站内容的应用程序也就不足为奇了。

如果你寻找创建网站最简便的方法，只需 Markdown 文件，可以看看 blot.im。注册 Blot 后，它会在你的电脑上创建一个 Dropbox 文件夹。只需将 Markdown 文件拖放到这个文件夹里——嗖！——它们就出现在你的网站上了。再简单不过了。

如果你熟悉 HTML、CSS 和版本控制，可以试试 Jekyll，这是一个流行的静态站点生成器，它接收 Markdown 文件并构建出 HTML 网站。

注意： 我用 Jekyll 创建了这个 Markdown 指南网站。你可以在 GitHub 上查看源代码。

文档

Markdown 尽管没有 Microsoft Word 那些花里胡哨的文字处理器，但对于基本的文档如作业和信函已经足够。你可以用 Markdown 文档编辑应用创建并导出 Markdown 格式化的文档为 PDF 或 HTML 格式。PDF 部分很关键，因为一旦有了 PDF 文档，你就可以做任何事——打印、电邮递、传网站。

以下是我推荐的 Markdown 文档编辑应用：

Mac：MacDown、iA Writer 或者 Marked2
iOS：iA Writer
Windows: ghost、Markdown Monster
Linux： ReText、ghostwriter
Web: Dillinger 或 StackEdit

提示：ia Writer 提供预览、打印 Markdown 格式文档的模板和导出。比如“学术风格”模板”加双倍行距。

笔记

Markdown 几乎理想的笔记。遗憾地，Evernote和OneNote，两个流行的笔记应用不支持 Markdown。好消息是其他几款应用支持：

Obsidian 功能丰富的 Markdown 笔记应用
Simplenote 简骨笔记应用跨平台
Notable 平台
Bear 是一款适用于 Mac 和 iOS 设备的类似 Evernote 应用程序。它默认并不完全使用 Markdown，但你可以启用 Markdown 兼式以实现兼容模式。
Joplin 是一个尊重您隐私的笔记应用程序，适用于每个平台。
Boostnote 标榜自己为“专为程序员设计的开源笔记应用程序”。

如果您离不开 Evernote，可以试试 Marxico，这是一款基于订阅的 Markdown 编辑器，或者直接在 Evernote 网站上使用 Markdown

书籍

想自行出版小说吗？试试 Leanpub，这项服务能接收你的 Markdown 格式文件，并将其转化为电子书。Leanpub 可以将你的书籍输出为 PDF、EPUB 和 MOBI 格式。如果你还希望制作纸质版的书籍，可以将 PDF 文件上传到另一个服务，比如 Kindle Direct Publishing。

演示文稿

信不信由你，你可以从 Markdown 格式的文件生成演示文稿。起初使用 Markdown 制作演示文稿可能需要一点时间适应，但一旦上手，你会发现这比使用 PowerPoint 或 Keynote 等应用程序要快速和简单得多。Remark（GitHub 项目）、Cleaver（GitHub 项目）以及 Marp（GitHub 项目）都是流行的基于浏览器的 Markdown 幻灯片工具。如果你是 Mac 用户，并且更倾向于使用应用程序，可以看看 Deckset 或 Hyperdeck。

电子邮件

如果你经常发送邮件，并且厌倦了大多数邮件服务商网站提供的格式化选项，你会很高兴了解到有一种简便的方法可以使用 Markdown 来撰写邮件。Markdown Here 是一款免费且开源的浏览器扩展，它可以将 Markdown 格式的文本转换成可以直接发送的 HTML。

协作

协作和团队消息应用是在工作和家庭中与同事朋友交流的流行方式。这些应用并未充分利用 Markdown 的所有特性，但它们所提供的功能相当实用。例如，无需使用所见即所得界面就能加粗和斜体文本非常方便。Slack、Discord、Wiki.js 和 Mattermost 都是优秀的协作应用。

文档

Markdown 特别适合技术文档编写。像 GitHub 这样的公司越来越多地转向使用 Markdown 来编写文档——请参阅他们的博客文章，了解他们如何将 Markdown 格式的文档迁移到 Jekyll。如果你为产品或服务编写文档，请看看这些实用工具：

Read the Docs 可根据你的开源 Markdown 文件生成文档网站。只需将你的 GitHub 仓库连接到其服务并推送——Read the Docs 会完成其余部分。他们也为商业实体提供了服务。
MkDocs 是一个快速简单的静态站点生成器，专为构建项目文档设计。文档源文件使用 Markdown 编写，并通过单一的 YAML 配置文件配置。MkDocs 提供了几种内置主题，包括一个为与 MkDocs 一起使用而移植的 Read the Docs 文档主题。最新的主题之一是 MkDocs Material。
Docusaurus 是一个专门为创建文档网站设计的静态站点生成器，支持翻译、搜索和版本控制。
VuePress 是一个由 Vue 驱动的静态站点生成器，专门优化了技术文档的编写。
Jekyll 在前面的网站部分已经提及，但它同样是从 Markdown 文件生成文档网站的好选择。如果选择这条路，一定要查看 Jekyll 的文档主题。

Markdown 的变体

使用 Markdown 最令人困惑的一个方面是，几乎每个 Markdown 应用程序都实现了一个略微不同的 Markdown 版本。这些 Markdown 的变种通常被称为“风味”(flavors)。你需要掌握你的应用程序所实现的 Markdown 风格。

为了理解 Markdown 风格的概念，可以将其想象为语言方言。纽约人和伦敦人都说英语，但两个城市使用的方言之间存在显著差异。使用不同 Markdown 应用的人也是如此。使用 Dillinger 编写 Markdown 与使用 Ulysses 是截然不同的体验。

实际上，这意味着当一家公司说他们支持“Markdown”时，你永远不会确切知道他们指的是什么。他们是指仅基本语法元素，还是指基本和扩展语法元素的组合，或是某些任意的语法元素组合？除非你阅读文档或开始使用该应用，否则不会知道。

如果你刚刚起步，我能给你的最好建议是选择一个对 Markdown 支持良好的应用。这将大大有助于保持你的 Markdown 文件的可移植性。你可能希望在其他应用中存储和使用你的 Markdown 文件，要做到这一点，你需要从一个提供良好支持的应用开始。你可以使用工具目录来寻找符合需求的应用。

其他学习资源

有许多资源可以帮助你学习 Markdown。这里还有一些其他的入门资源：

John Gruber 的 Markdown 文档。这是 Markdown 创始人编写的原始指南。
Markdown 教程。一个开源网站，允许你在网页浏览器中直接尝试 Markdown。
Awesome Markdown。Markdown 工具及学习资源的汇总列表。
Typesetting Markdown。这是一个多部分系列文章，介绍如何使用 pandoc 和 ConTeXt 构建一个用于排版 Markdown 文档的生态系统。

以上资源覆盖了从基础学习到进阶使用的多个方面，无论你是 Markdown 的初学者还是寻求提升的专业人士，都能从中找到合适的内容来深化理解和技能。通过实践和参考这些资源，你可以更高效地利用 Markdown 来编写文档、创建网站内容和优化团队协作。