Markdown 入门教程
Markdown 用少量符号记录文档结构和格式。它既可以写日常笔记,也适合 README、技术文档和静态网站内容。本页先带你完成一篇可使用的文档,再解释背后的概念。
10 分钟快速上手
先复制下面的完整示例到 在线编辑器。左侧是纯文本源文件,右侧是渲染结果;修改内容即可观察每种语法的作用。
# 我的阅读清单
> 用 Markdown 记录阅读进度和想法。
## 本周计划
- [x] 选择一本书
- [ ] 阅读第一章
- [ ] 整理三条笔记
## 阅读记录
| 书名 | 状态 | 评分 |
| --- | --- | --- |
| 《认知觉醒》 | 阅读中 | 待评分 |
**重点**:先记录问题,再摘录答案。
访问 [Markdown 教程](https://markdown.com.cn/) 复习语法。
- 观察结构:
#创建标题,>创建引用,列表和表格分别组织步骤与结构化信息。 - 动手修改:替换书名、添加一行任务,或把“阅读中”改成“已完成”。
- 保存文件:在本地写作时,将文件保存为 UTF-8 编码的
.md文件;在在线编辑器中可点击“下载 Markdown”。
第一次练习只需掌握五个符号:#(标题)、**(粗体)、-(列表)、>(引用)、[]()(链接)。图片语法是在链接前加 !,例如 。
表格和任务列表属于常见的扩展语法,并非每个平台都默认启用。若显示不正确,请先查看目标平台的 语法支持情况。
Markdown 是什么?
Markdown 是一种轻量级标记语言,用于描述文本排版格式。它由John Gruber于 2004 年推出,如今已是全球最流行的标记语言之一。
- 专注于文字内容;
- 纯文本,易读易写,可以方便地纳入版本控制;
- 语法简单,没有什么学习成本,能轻松在码字的同时做出美观大方的排版。
使用 Markdown 与使用 Word 类编辑器不同。在 Word 之类的应用程序中,单击按钮以设置单词和短语的格式,并且,更改立即可见。而 Markdown 与此不同,当你创建 Markdown 格式的文件时,可以在文本中添加 Markdown 语法,以指示哪些单词和短语看起来应该有所不同。
例如,要表示标题,只须在短语前面添加一个井号即可(例如, # Heading One)。或者要加粗一个短语,只须在短语前后各加两个星号即可(例如,**this text is bold**)。可能需要一段时间才能习惯在文本中看到 Markdown 语法,尤其是如果你已习惯了所见即所得的应用程序。以下截图展示了 Markdown 文件在 Notepad++ 文本编辑器中显示的效果。

你可以使用文本编辑器为纯文本文件添加 Markdown 格式的元素。或者,你也可以安装针对 macOS、Windows、Linux、iOS 和 Android 操作系统的 Markdown 应用程序。或者还可以使用一些基于 Web 的应用程序用于 Markdown 编写。
依赖于你所使用的应用程序,你可能无法实时预览格式化的文档。但是没关系。根据 Gruber 的说法,Markdown 的语法被设计为可读性强且不显眼,因此即使 Markdown 文件中的文本未经过渲染也易于阅读。
Markdown 语法的首要设计目标是尽可能易读。基于这个目标,Markdown 格式的文档能够以纯文本形式原样发布,而不会看起来像被填满了标签或格式化指令。
为什么要使用 Markdown?
当你可以通过按下界面中的按钮来设置文本格式时,为什么还要使用 Markdown 来书写呢?使用 Markdown 而不是 Word 类编辑器的原因有:
-
Markdown 应用广泛。GitHub、GitLab、Gitee 等代码托管平台使用 Markdown 编写 README、Issue、讨论和 Wiki;许多笔记软件、文档系统与静态网站生成器也支持它。掌握一次基础语法,就能在多种工作流中复用。
-
Markdown 是纯文本,便于迁移和版本管理。几乎任何文本编辑器都能打开
.md文件,也可以使用 Git 比较修改历史。不过,复杂排版、附件和扩展语法的迁移效果仍取决于目标应用,重要文档应定期测试导出结果。 -
Markdown 是独立于平台的。你可以在运行任何操作系统的任何设备上创建 Markdown 格式的文本。
-
Markdown 能适应未来的变化。即使你正在使用的应用程序将来会在某个时候不能使用了,你仍然可以使用文本编辑器读取 Markdown 格式的文本。当涉及需要无限期保存的书籍、大学论文和其他里程碑式的文件时,这是一个重要的考虑因素。
选择工具,边学边练
Markdown 入门的最佳方式就是多使用它。由于有大量免费工具的存在,上手 Markdown 是很方便的。比较遗憾的一点是各平台可能采用不同语言实现的 Markdown 解析引擎,或采用同一解析引擎的不同版本,而且可能有不同程度的定制与扩展,这导致在不同平台上使用 Markdown 写作时体验并不完全一致。不过幸好对于大家公认的一些标准语法,各家都是支持的。
你甚至都不需要下载任何程序,就可以使用在线 Markdown 编辑器 来编写 Markdown。进入其站点就可以开始在左侧窗格中书写了。渲染后的文档在右侧窗格预览。
阅读本指南时,你可以打开 在线 Markdown 编辑器 。这样,你就可以一边学习 Markdown 语法一边练习了。熟悉 Markdown 之后,再选择一个顺手的 Markdown 的应用程序。
Markdown 的工作原理
在使用 Markdown 格式书写时,文本内容存储在带有 .md 或 .markdown 扩展名的纯文本文件中。那然后呢?你的 Markdown 格式的文件如何转换为 HTML 或可打印的文档呢?
简单来说,你需要一个能够处理 Markdown 文件的 Markdown 应用程序。有许多应用程序可供选择,从简单的脚本到类似于 Microsoft Word 的桌面应用程序。尽管它们在视觉上有所不同,但所有应用程序都执行相同的操作。像 在线 Markdown 编辑器 一样,它们都是将 Markdown 格式的文本转换为 HTML,以便可以在 Web 浏览器中显示。
Markdown 应用程序使用一种称为 Markdown 处理器(也通常称为“解析器”或“实现”)的东西将获取到的 Markdown 格式的文本输出为 HTML 格式。此时,可以在 Web 浏览器中查看你的文档,或者将其与样式表组合并打印。你可以在下图看到此过程的直观表示。
注意: Markdown 应用程序和处理器是两个单独的组件。为了简洁起见,在下图中,我将它们组合为一个元素(即 “Markdown应用程序”)。

总而言之,这是一个四步的过程:
- 使用文本编辑器或 Markdown 专用的应用程序创建 Markdown 文件。该文件应带有
.md或.markdown扩展名。 - 在 Markdown 应用程序中打开 Markdown 文件。
- 使用 Markdown 应用程序将 Markdown 文件转换为 HTML 文档。
- 在 web 浏览器中查看 HTML 文件,或使用 Markdown 应用程序将其转换为其他文件格式,例如 PDF。
从你的角度来看,该过程将根据你使用的应用程序的不同而有所不同。例如,在线 Markdown 编辑器 本质上将第 1-3 步组合到一个单一、无缝的界面中,你要做的就是在左窗格中键入内容,然后转换结果就在右窗格中就神奇地出现了。但是,如果你使用的是其他工具(例如带有静态网站生成器的文本编辑器),则会发现该过程更为明显。
Markdown 有什么用?
Markdown 是做笔记、为网站创建内容以及生成可打印文档的快速、简便的方法。
学习 Markdown 语法并不需要很长时间,一旦你知道如何使用它,你就可以在几乎所有地方使用 Markdown 进行书写了。大多数人使用 Markdown 来为网站创建内容,但是 Markdown 也可以很好地格式化从电子邮件到购物清单的所有内容。
下面是一些你可以使用 Markdown 的场景。
网站
Markdown 是为 web 而设计的,因此,市面上有很多专门用于创建网站内容的应用程序就不足为奇了。
如果你熟悉 HTML、CSS 和版本管理,可以使用 Jekyll、MkDocs 或 Docusaurus 将 Markdown 构建为 HTML 网站。GitHub Pages 等托管服务可以发布静态站点。选择生成器时,应确认其 Markdown 方言、主题维护状态和构建环境。
如果你是 WordPress 博主,你可以使用 Jetpack 插件实现对 Markdown 的支持。
文件资料
Markdown 并不具备像 Microsoft Word 这样的文字处理程序的所有功能,但是对于创建基本文件(例如作业和信件)来说已经足够了。你可以使用 Markdown 文档创作工具来创建 Markdown 格式的文档并将其导出为 PDF 或 HTML 格式。PDF 格式是关键,因为一旦有了 PDF 文档,您就可以使用它进行任何操作:打印、通过电子邮件发送或将其上传到网站。
如果只是练习,直接使用本站的在线 Markdown 编辑器即可。长期写作则可根据场景选择:VS Code 适合代码与技术文档,Obsidian 适合本地知识库,Joplin 适合跨设备笔记,Pandoc 适合格式转换。平台、价格、同步方式和扩展支持各不相同,详见 Markdown 工具选择指南。
笔记
Markdown 很适合记录可检索、可迁移的笔记。Obsidian、Joplin 等工具可以直接使用或管理 Markdown 内容,但“支持 Markdown”可能指编辑源文件、输入快捷格式、导入导出中的任意一种。选择前应确认:能否批量导出原始 .md 文件、图片附件如何保存、双链和标签等专有功能在导出后是否仍可使用。
书籍
Markdown 便于维护长篇内容的纯文本源稿。Pandoc 可以将 Markdown 转换为 HTML、PDF、EPUB 等格式;Leanpub 提供面向作者的写作与出版工作流。正式出版前仍需检查目录、字体、图片、分页和引用等版式,不能只依赖语法转换。
演示文稿
Marp、Slidev 和 reveal.js 可以把结构化文本制作成演示文稿。这类工具适合内容稳定、需要版本管理或包含大量代码的演示;复杂动画和精细视觉设计仍可能需要专门的演示软件。
邮件
部分邮件客户端和浏览器扩展可以把 Markdown 转为邮件 HTML。发送前应测试标题、列表、链接和图片在不同客户端中的显示效果,并保留一份纯文本版本;不要把 Markdown 源码直接当作所有收件人都能识别的格式。
文档
Markdown 很适合需要审阅、版本管理和持续发布的技术文档。常见选择包括:
- MkDocs:使用 Markdown 和 YAML 配置生成项目文档,配合 Material for MkDocs 可构建完整的文档站点。
- Docusaurus:适合需要版本化、国际化、搜索和 React 组件扩展的产品文档。
- Read the Docs:连接代码仓库后自动构建并托管文档,可与 MkDocs 等工具配合。
- Jekyll:适合结构较简单的静态网站和博客。
选择文档系统时,除了语法,还要考虑搜索、导航、版本化、权限、构建部署和长期维护成本。
标准、方言与兼容性
不同应用可能实现不同的 Markdown 语法,这些变体通常称为 flavors(方言)。同一个标记在一个平台上可能生成表格,在另一个平台上却只显示普通文本。
CommonMark 为原始 Markdown 中含义不明确的部分提供了严格规范;GitHub Flavored Markdown(GFM) 在 CommonMark 基础上增加表格、任务列表、删除线、自动链接等常用能力。GFM 也不是所有应用的默认标准,公式、脚注、目录和图表等功能的写法仍可能不同。
提高文档可移植性的做法:先确定主要发布平台;核心内容优先使用基本语法;扩展语法选用目标平台明确支持的写法;避免依赖某个工具专有的双链、嵌入和属性;迁移前用真实文档测试图片、链接、代码块与表格。
你可以在 扩展语法可用性 中继续了解兼容性问题,在 工具选择指南 中比较具体应用。
下一步学什么?
- 按顺序阅读 标题、段落、强调、列表 和 链接,建立稳定的基础。
- 根据实际需要学习 表格、围栏代码块 和 任务列表,不必一次记住所有扩展。
- 把 速查表 加入书签,在真实写作中查阅;每周整理一篇自己的笔记或文档,比反复阅读更容易形成长期记忆。
权威资源
需要核对规则或深入实现时,优先参考以下原始文档与规范:
- John Gruber 的 Markdown 原始文档:了解设计目标和最初语法。
- CommonMark 规范:核对标准语法及边界情况。
- GitHub Flavored Markdown 规范:查看表格、任务列表等 GFM 扩展的精确定义。
- Pandoc’s Markdown:了解面向文档转换的丰富扩展。
- Awesome Markdown:发现更多工具与学习资源。