Markdown入门教程：从零开始

Markdown 是一种纯文本格式化语法，通过输入符号把文字变成结构化文档，核心语法大约10分钟就能学会。 John Gruber 于2004年3月发布了 Markdown，Aaron Swartz 参与了设计。22年后的今天，它被用来编写 GitHub 上的 README 文件、Obsidian 里的笔记，以及 Reddit 上的帖子。整套系统只有两个部分：一个以 .md 为扩展名保存的文本文件，以及一个把该文本转换成 HTML 的处理器。下面的全部内容都建立在这两个部分之上。

Markdown是什么？

Markdown 是一种诞生于2004年的轻量级标记语言，它通过 #、*、> 这类可见字符为纯文本添加格式指令。 行首的一个 # 会生成标题。单词两侧的两个星号会把它加粗。一个连字符会开始一个列表项。最初的版本只是一个 Perl 脚本 Markdown.pl，发布在 Gruber 的 Daring Fireball 网站上。

更重量级的标记语言（例如 HTML 和 LaTeX）会用标签和命令包裹内容，让源文件变得杂乱。Markdown 走了相反的路线。Gruber 围绕一个目标设计了这套语法：Markdown 文件在任何转换发生之前，就应当作为纯文本清晰可读。哪怕从未听说过 Markdown 的人，也能一眼看出 ## Pricing 这一行是个标题。正是这种可读性，让这种格式从2004年的博客圈，扩散到2008年的 GitHub、2010年的 Stack Overflow，并在2010年代进入 Obsidian、Joplin 等笔记应用。

Markdown 与所见即所得编辑器的区别

Microsoft Word、Google 文档这类所见即所得（WYSIWYG）编辑器通过工具栏按钮应用格式并把指令隐藏起来；Markdown 则把每条指令都以字符形式保留在文件里。 WYSIWYG 的意思是"所见即所得"。在 Word 里，你选中一段文字并点击加粗按钮，这个决定会被存进你永远看不到的二进制 XML。在 Markdown 里，你输入 **launch date**，那两对星号本身就是格式。

差别在保存文件时显现出来。一个 .docx 文件只能在少数几个程序里正常打开，主要是 Word、LibreOffice 和 Pages。而一个 Markdown 文件可以在1970年代以来发布的任何文本编辑器里打开，从记事本到 vim 再到 VS Code。许多 Markdown 编辑器用分屏实时预览弥补了视觉差距：左侧窗格是原始语法，右侧窗格是渲染结果，每敲一个键都会更新。你既得到了 Word 式的即时反馈，又保留了纯文本的透明。

为什么人们使用 Markdown

写作者选择 Markdown 有四个实际理由：可移植、跨平台、面向未来、覆盖面广。 每一条都源自纯文本这个根基。

• 可移植。 Markdown 文件在应用之间流转不需要任何转换。在 iA Writer 里起草，在 VS Code 里修改，再通过 Ghost 发布，文件形态始终不变。而 .docx、.pages 这类专有格式会把内容锁进单一厂商的生态。
• 跨平台。 Markdown 在 Windows 11、macOS、Linux、iOS 和 Android 上表现完全一致。文件就是 UTF-8 文本，2026年在手机上敲下的一条笔记，在电脑上打开时逐字节完全相同。
• 面向未来。 软件会消亡，文本文件会留存。WordPerfect 在1990年统治文字处理市场，如今它的旧文件成了数据恢复项目。而一份2004年的 Markdown 文件至今不到一秒就能打开，这对需要保存20年的论文、合同和书稿至关重要。
• 覆盖面广。 GitHub、GitLab、Reddit、Discord、Notion、Slack 等平台都接受 Markdown 输入。语法只需学一次，在所有平台都用得上。

Markdown 的处理流程

Markdown 变成排版文档要经过4个步骤：你编写一个 .md 文件，处理器解析它，处理器输出 HTML，浏览器再渲染这份 HTML。 处理器也叫解析器或实现，是每个 Markdown 应用内部的引擎。常见的处理器包括 markdown-it、marked、cmark 和 Pandoc，其中 cmark 转换一份普通文档用时不到10毫秒。

不同工具暴露这条流程的程度不同。带实时预览的在线编辑器会在每次按键时悄悄执行第2步到第4步。Hugo 这类静态网站生成器则用一条构建命令对几百个文件跑同一条流程。流程本身从不改变，输出的 HTML 可以搭配任何 CSS 样式表，也可以通过 Pandoc 之类的工具继续转换为 PDF、EPUB 或 .docx。

Markdown 能用来做什么？

Markdown 能胜任七类常见工作：网站、笔记、文档、书籍、演示文稿、电子邮件和技术文档。 同一套10分钟就能学会的语法覆盖全部七类。

网站

Hugo、Jekyll、Eleventy 这类静态网站生成器可以用一个个装满 Markdown 文件的文件夹搭建整个网站。 Jekyll 发布于2008年，是 GitHub Pages 及其免费托管的底层引擎。内容平台同样接受 Markdown：Ghost 自带原生 Markdown 编辑器，WordPress 通过区块编辑器支持 Markdown。一篇博客文章就是一个 .md 文件，Git 这样的版本控制系统会记录对它的每一次修改。

笔记与文档

Obsidian、Joplin、Bear、Simplenote 等笔记应用把每条笔记都存成 Markdown。 仅 Obsidian 一家，就把每个仓库保存为你本地磁盘上的一个 .md 文件夹，因此一个包含5000条笔记的收藏依然可以用标准工具检索。至于信件、会议纪要、作业这类一次性文档，Markdown 编辑器可以直接导出为 PDF 或 HTML，PDF 可以打印、作为邮件附件发送或上传到任何地方。

书籍与演示文稿

Leanpub 能把一个 Markdown 文件夹变成 PDF 和 EPUB 格式的成品电子书，Pandoc 在命令行里也能做到同样的事。 已经有作者用这种方式出版了完整的长篇小说和300页的技术书。做幻灯片时，Marp、Remark 这类工具可以把一个 Markdown 文件转换成演示文稿，每张幻灯片用一个 --- 分隔，比修改一份有40张手工排版幻灯片的 PowerPoint 文件快得多。

电子邮件与技术文档

Markdown Here 这类浏览器扩展可以在 Gmail 及其他网页邮箱里把 Markdown 转换成排版好的 HTML 邮件。 技术文档是 Markdown 的主场：GitHub 会在每个仓库顶部渲染 README.md，而 MkDocs、Docusaurus、Read the Docs 等生成器能用 .md 源文件构建完整的文档站点。Docusaurus 由 Meta 于2017年发布，在纯 Markdown 页面之上增加了版本管理和搜索。

Markdown 方言：CommonMark 与 GFM

Markdown 方言指语法的特定变体，其中最重要的两个是2014年定稿的 CommonMark 和2017年定稿的 GitHub Flavored Markdown。 Gruber 2004年发布的版本留下了不少未定义的边界情况，比如嵌套列表如何缩进，导致早期处理器的输出各不相同。同一个文件在不同工具里渲染结果不一样。

CommonMark 解决了这个问题。该规范于2014年9月由一个包括 John MacFarlane 和 Jeff Atwood 在内的工作组发布，用超过600个测试用例把每一条解析规则钉死。Stack Overflow 于2020年6月把渲染切换到了 CommonMark。

GitHub Flavored Markdown（简称 GFM）是 CommonMark 的严格超集，GitHub 于2017年3月将其正式规范化。它增加了五个扩展：表格、任务列表、删除线、自动链接，以及带语言标注的围栏代码块。当某个产品页面声称"支持 Markdown"时，要确认它指的是哪种方言，因为 GFM 表格在只支持 CommonMark 的工具里会渲染成一排竖线字符。在2026年，GFM 是最稳妥的默认选择，也是本站编辑器所渲染的方言。

如何从今天开始写 Markdown

打开一个浏览器端的 Markdown 编辑器，输入一个 # 再加上标题，你就写出了自己的第一段 Markdown；不需要安装任何东西，也不需要注册账号。 分屏编辑器会在你输入的同时显示渲染结果，这是学习语法最快的反馈循环。

从使用频率最高的五个元素开始：# 表示标题，**bold** 表示加粗，*italic* 表示斜体，- 表示列表，[text](url) 表示链接。这五个元素大约覆盖日常排版的90%。练习方法是改写一份真实的内容，比如一条会议记录或一份待办清单，然后把结果保存为 .md 文件。之后，基础语法指南会讲解全部9个核心元素，扩展语法指南再补充 GFM 表格、脚注和任务列表。

常见问题

写 Markdown 需要安装软件吗？

有浏览器就够了；在线 Markdown 编辑器可以完成编写、预览和导出，零安装。 等你需要离线访问和本地文件管理时，再考虑 Obsidian、iA Writer、VS Code 这类桌面应用。

Markdown 文件用什么扩展名？

Markdown 文件使用 .md 扩展名，.markdown 是较少见的替代写法。 两者保存的纯文本完全相同，从 cmark 到 Pandoc，每个 Markdown 处理器都接受这两种扩展名。

学会 Markdown 需要多长时间？

五个核心元素大约需要10分钟，包含9个元素的完整基础语法一次就能学完。 表格、任务列表等 GFM 扩展再花15分钟。相比之下，LaTeX 要达到熟练排版往往需要数周。

CommonMark 和 GFM 有什么区别？

CommonMark 是2014年的基础规范，统一了 Markdown 的核心解析规则；GFM 是 GitHub 2017年推出的超集，增加了表格、任务列表、删除线、自动链接和围栏代码块。 每一份合法的 CommonMark 文档同时也是合法的 GFM 文档，所以按 GFM 来写是最实用的选择。