Markdown 是一种轻量级的标记语言（lightweight markup language），由约翰·格鲁伯（John Gruber）于 2004 年创建。它的核心理念是让写作者能够使用纯文本格式编写文档，同时通过简单的符号（如 #、*、- 等）来指示文本的结构和样式，最终这些纯文本可以被转换为结构化的 HTML 页面。简单来说，你只需要学会几个简单的符号，就能写出格式美观的文档。
为什么我们需要学习 Markdown？想象一下你正在用 Word 写文档：加粗需要选中文字再点击工具栏按钮，排版时需要在菜单中寻找对应功能，文件传输到别人的电脑上格式可能就乱了。Markdown 完全避免了这些问题——你只需要在文字旁边加上一个小小的符号，格式就定义好了。文件本身就是纯文本，任何电脑、任何系统都能打开，永远不会出现打不开或者格式错乱的情况。
对比其他文档工具，Markdown 的优势非常明显。与 Word 这类"所见即所得"编辑器相比，Markdown 是纯文本，文件体积小，版本控制非常方便，你可以用 Git 跟踪每一处修改。与 HTML 相比，Markdown 的语法极其简洁，学习成本几乎为零，而不需要记住那些复杂的标签对。HTML 写一个标题需要 <h1>标题</h1>，而 Markdown 只需要 # 标题。
Markdown 已经成为开发者文档的事实标准。全球最大的开源代码托管平台 GitHub 上的所有项目几乎都有一个 README.md 文件，这个 .md 后缀就是 Markdown 文件。几乎所有的技术博客、开源项目文档、API 说明、学习笔记都在使用 Markdown。即使你完全不懂编程，只要你会写文字，就能在几分钟内学会 Markdown。
Claude Code 也广泛使用 Markdown。我们每次与 Claude Code 对话时，它的所有输出都是 Markdown 格式的——代码块使用三个反引号包裹，列表使用短横线标记，表格使用管道符对齐。CLAUDE.md 文件（Claude Code 的项目配置文件）本身就是 Markdown 文件。对话中的技能配置、输出格式，全都建立在对 Markdown 的理解之上。可以说，掌握了 Markdown，就能更好地使用 Claude Code。
"标记语言"是一种在文本中嵌入特殊符号或标签的系统，用于指示文本的结构和呈现方式。它不是编程语言——你不需要学习变量、循环、函数等编程概念。打个比方：就像你在纸上的手写笔记中，会在标题下面画横线、在重点词周围画圈一样，Markdown 就是用 #、* 这样的符号来做同样的事。标记语言有很多种，比如 HTML 是一种标记语言，Markdown 也是一种标记语言，只是 Markdown 比 HTML 简单得多。
一句话总结：Markdown 就是用最简单的符号来给纯文本"化妆"——让你在不打开任何复杂软件的情况下，写出结构清晰、格式美观的文档。它是学习 Claude Code 和几乎所有开发者工具的第一块敲门砖。
Markdown 使用井号 # 来标记标题层级，从一级到六级共六个级别。一级标题用一个 #，二级用两个 ##，以此类推，六级标题用六个 ######。这对应 HTML 中的 <h1> 到 <h6> 标签。
使用标题时需要注意一个重要规则：井号后面必须有一个空格，否则不会被识别为标题。比如 #标题 是无效的，必须写成 # 标题。在同一个文档中，一般建议只使用一个一级标题作为文档主标题，二级到四级标题作为章节标题。尽量不要跳级使用，比如从二级标题直接跳到五级标题，这会让文档结构显得混乱。
在常见的 Markdown 编辑器中（比如 VS Code 或 GitHub），编辑器侧边栏会自动生成文档的标题大纲。如果你的文档标题层级结构清晰，这个大纲可以帮助你快速跳转到文档的任何位置，这在大文档中特别有用。建议平时写文档只用四级以内的标题就足够了，写得越深说明文档组织越需要重新梳理。
在 Markdown 中，段落之间使用空行分隔。也就是说，你在两段文字之间留一个空行，Markdown 就会知道这是两个不同的段落，并在渲染时给它们之间添加间距。如果你只是简单地在一行末尾按了回车，但在下一行继续写文字，Markdown 会认为这是同一个段落，只是换了一行显示而已，并不会产生新的段落。
有时候你希望在段落内部强制换行，而不是另起一个段落。为了实现这一点，你需要在上一行的末尾添加两个空格，然后再按回车。这在有些 Markdown 编辑器中也被称为"软换行"。不过请注意，不同平台对软换行的支持程度不同，在 GitHub 等平台上，你也可以直接使用空行来换行。
这是第一段文字。前后有空行，所以自成一段。这仍然是第一段（同一段落内换行）。
这是第二段文字。注意前面有一个空行。
这一行末尾有两个空格
看到效果了吗？这行紧接上一行（软换行）。
Markdown 提供了多种方式来强调文本，包括斜体、粗体、粗斜体和删除线。斜体使用单个星号 *文字* 或下划线 _文字_ 包围；粗体使用两个星号 **文字** 或两个下划线 __文字__；粗斜体则使用三个星号 ***文字***。删除线使用两个波浪线 ~~文字~~，这在 GitHub 等平台上是支持的。
在实际使用中，推荐使用星号而非下划线，因为星号的兼容性更好。特别注意，星号和文字之间不能有空格，否则不会被识别为强调。比如 * 文字 * 是无效的，而 *文字* 是有效的。在同一个文档中，你可以根据需要组合使用这些强调符号，比如 **这是粗体中的*斜体***。
这是 斜体 文字效果
这是 粗体 文字效果
这是 粗斜体 文字效果
这是 删除线 文字效果
Markdown 支持无序列表和有序列表两种基本列表类型。无序列表使用短横线 -、星号 * 或加号 + 开头，其中短横线是最常用的写法。有序列表直接用数字加点号，如 1.、2.、3. 等。有趣的是，在渲染时，有序列表的数字不一定要按顺序排列——你全部写 1. 也可以得到正确的编号，Markdown 会自动帮你排序。
列表还可以嵌套使用。要创建一个嵌套列表，你只需要在子列表项前面缩进两个空格（或者一个 Tab 键）。嵌套可以有多层，只要每层都正确缩进即可。列表中的每一项不仅可以包含文字，还可以包含多个段落、代码块甚至引用块，只需要在子内容前额外缩进四个空格即可。
无序列表：
有序列表：
嵌套列表：
Markdown 提供了两种代码展示方式。在段落中提及代码或命令时，使用行内代码（inline code），用反引号 `code` 包围。需要展示多行代码或代码块时，使用代码块（fenced code block），用三个反引号 ``` 包围代码内容。在代码块的开始三个反引号后面，你还可以指定编程语言名称来实现语法高亮，比如 ```python 或 ```javascript。
语法高亮是一个非常有用的功能。当你指定了语言名称后，Markdown 渲染器会使用对应语言的语法规则为代码中的关键字、字符串、注释、函数名等元素着色。这不仅让代码看起来更专业，更重要的是提高了代码的可读性。注意反引号必须是英文半角符号，而不是中文的引号。
行内代码：请执行 npm install 命令安装依赖。
代码块：
如果你只是想在文档中展示一个文件路径或一个简单的命令名称，使用行内代码就够了。如果要展示一段可执行的代码或命令行输出，使用代码块。代码块指定语言后，在很多编辑器和平台上会自动添加一个"复制代码"按钮，方便读者一键复制。建议在 Claude Code 中与 AI 对话时，把要执行的命令放在代码块中，这样 Claude Code 可以准确识别。
Markdown 的链接语法非常直观，格式为 [显示文本](URL)。方括号中是你要显示的链接文字，圆括号中是实际的跳转地址。链接的目标可以是一个完整的网页 URL（如 https://github.com），也可以是本地文件（相对路径，比如 [其他笔记](other.md)），还可以是文档内部的锚点（如 [跳转到概述](#概述)）。
除了基本链接外，Markdown 还支持快捷引用链接，这在引用多个链接时特别有用。你可以先在所有引用的地方用 [显示文本][标识符] 格式编写，然后在文档的某个地方统一定义 [标识符]: URL。这样你的正文内容就不会被长长的 URL 打断，文档更清晰。还有一种更简洁的用法，就是直接把 URL 作为标识符：[链接]，然后在文档末尾定义 [链接]: https://example.com。
Markdown 插入图片的语法与链接非常相似，只是在前面多了一个英文感叹号 !。格式为 。替代文本（alt text）是当图片加载失败时显示的文字，同时对于使用屏幕阅读器的用户也很重要，所以不要省略它。图片的 URL 可以是网络地址，也可以是本地文件的相对路径。
与链接一样，图片也支持引用式语法，并且可以在图片 URL 后面添加标题（tooltip），当鼠标悬停在图片上时显示。需要注意的是，Markdown 本身不支持调整图片尺寸。如果需要设置图片大小，可以使用 HTML 的 <img> 标签，这在 Markdown 中是允许的。
图片语法本身不可见，渲染后显示为图片元素。使用 <img> 标签可以精确控制宽度。
Markdown 使用右尖括号 > 来表示引用块。引用的内容通常是一段他人说的话、书籍中的摘录或需要特别强调的引用文字。只需要在每行或段落开头加上 > 和一个空格，Markdown 就会将其渲染为一个突出的引用块。引用块中的文字通常会有左侧的竖线标识和灰色背景，与正文明显区分。
引用块还可以嵌套使用，使用两个 >> 创建嵌套引用。在引用块内部，你也可以使用其他 Markdown 语法，比如标题、列表、代码块等。这使得引用块非常灵活——你可以在回答他人问题时，先用引用块把对方的话引用出来，然后在下方用普通段落回复。
Markdown 是一个轻量级标记语言。它让写作者专注于内容而不是格式。
第一层引用
第二层嵌套引用
分割线（Horizontal Rule）用于分隔文档中不同的大段内容，在视觉上创建一条横线。在 Markdown 中，你可以使用三个或更多的短横线 ---、星号 *** 或下划线 ___ 来创建分割线。最常用的是三个短横线。
使用分割线时需要特别注意，如果分割线前面有文字，在文字和分割线之间必须有一个空行，否则 Markdown 可能会把文字解析为标题（因为 文字--- 可能被解析为标题格式）。保险的做法是：始终在分割线前后各留一个空行。
第一部分内容
第二部分内容
第三部分内容
有时候你需要在文档中显示 Markdown 语法符号本身而不是它的效果，比如你想在文档中写一段文字展示 Markdown 语法本身。这时就需要使用反斜杠 \ 来进行转义。在特殊符号前面加上反斜杠，Markdown 就会把它当作普通字符显示。
常见的需要转义的符号包括：反斜杠本身 \\、反引号 \`、星号 \*、方括号 \[ 和 \]、圆括号 \( 和 \)、井号 \#、加号 \+、减号 \-、点号 \.、感叹号 \!、尖括号 \< 等。记住这个规则：如果你在写文档时发现某个符号产生了意想不到的格式效果，就在它前面加一个反斜杠。
不转义时：这是 粗体 文字
转义后：这是 **粗体** 语法
Markdown 的基础语法只有 10 个左右的符号规则，大多数人在 30 分钟内就能掌握。记住最常用的几个：# 做标题、** 加粗、- 做列表、` 标记代码、[文字](链接) 插入链接。实际写文档时，80% 以上的场景只需要用到这些基础语法。当你熟练掌握基础语法后，看任何 Markdown 文档都能一眼理解它的结构和格式。
基础 Markdown 语法足以应付日常的文档写作，但不同的平台（如 GitHub、GitLab、各种笔记软件）在基础 Markdown 之上添加了许多扩展功能，让 Markdown 变得更加强大。这些扩展语法虽然在不同平台上的支持程度可能有所差异，但掌握它们可以让你的文档表现力大大提升。
Markdown 使用管道符 | 和短横线 - 来创建表格。第一行是表头，第二行使用短横线分隔表头和表格内容，第三行开始是表格数据。在第二行的分隔行中，你还可以通过冒号 : 的位置来控制列的对齐方式：:--- 表示左对齐，:--: 表示居中对齐，---: 表示右对齐。
表格的列数由管道符分隔的单元格数量决定，每一行的列数应当保持一致。虽然 Markdown 不要求各行的管道符严格对齐，但为了表格源文件的可读性，建议使用编辑器自带的表格格式化功能进行对齐。手动对齐比较繁琐，你可以使用在线表格生成工具，或者在 VS Code 中安装 Markdown 表格插件。
| 功能 | 语法 | 渲染效果 | 兼容性 |
|---|---|---|---|
| 标题 | # 标题 | 大号加粗文字 | 全部 |
| 粗体 | **文字** | 加粗文字 | 全部 |
| 代码块 | ```代码``` | 带背景代码区域 | 全部 |
| 表格 | |列1|列2| | 结构化表格 | 部分 |
任务列表（Task List / Checkbox）是一种非常实用的扩展语法，被 GitHub Flavored Markdown（GFM）广泛支持。它的写法是在普通列表项的基础上，在方括号中填入空格或字母 x：- [ ] 表示未完成，- [x] 表示已完成。渲染后，这些列表项会变成可勾选的复选框。
任务列表适用于各种 TODO 清单、项目进度跟踪、学习计划管理等场景。在 GitHub 的 Issue 和 Pull Request 中，任务列表还可以被自动汇总，显示出已完成和未完成的数量比例。笔记软件如 Notion、Obsidian 也支持任务列表，可以用它来做日常待办事项管理。
今日学习计划：
2/5 已完成 (40%)
脚注（Footnote）用于在文档中添加补充说明或引用来源，而不会打断正文的阅读流程。在正文中需要添加脚注的位置使用 [^标识符] 标记，然后在文档的任意位置（通常在末尾）定义 [^标识符]: 脚注内容。渲染后，正文中的脚注标记会显示为上标数字，点击它可以跳转到页面底部的脚注内容区。
不同的 Markdown 渲染器对脚注的支持程度不同。Pandoc 和一些静态网站生成器原生支持脚注，GitHub 目前不支持脚注语法（需要用其他方式替代）。在 VS Code 的 Markdown 预览中，脚注通常也能正常工作。如果你需要在所有平台上都可用，可以考虑使用链接替代脚注功能。
Markdown 由 John Gruber 创建[1]。它在开发者社区中广泛使用[2]。
[1] John Gruber 是 Daring Fireball 博客的作者。
[2] 包括 GitHub、GitLab、Stack Overflow 等平台。
定义列表（Definition List）用于展示术语及其定义，类似于字典的形式。Markdown 核心语法不支持定义列表，但一些扩展（如 PHP Markdown Extra、Kramdown、Pandoc 等）提供了支持。通常的写法是：第一行写术语，第二行以冒号开头写定义。
定义列表在技术文档中非常有用，特别是在描述 API 参数、配置项、术语表等场景。比如你在写一份配置文件说明时，可以用定义列表来清晰地展示每个配置项的名称和含义。不过需要注意，由于不是所有平台都支持定义列表，在需要广泛兼容的文档中建议使用标题或表格来代替。
许多 Markdown 渲染器通过集成 MathJax 或 KaTeX 库来支持 LaTeX 数学公式语法。行内公式使用单个美元符号 $公式$，块级公式使用双美元符号 $$公式$$。注意美元符号与公式内容之间不要有空格。
这种功能在学术写作、技术文档和数据分析报告中特别有用。Obsidian、Typora、Jupyter Notebook 等工具都原生支持数学公式。GitHub 的 Markdown 渲染器在 2022 年之后也开始支持 LaTeX 数学公式了（使用 $$ 语法）。如果你需要写包含数学公式的文档，选择支持 LaTeX 的编辑器非常重要。
行内公式：爱因斯坦的质能方程 E = mc² 非常著名。
块级公式：
Mermaid 是一种基于文本的图表绘制工具，使用类似 Markdown 的语法来定义流程图、时序图、甘特图、类图等各种图表。在支持 Mermaid 的 Markdown 渲染器中，你只需要使用 ```mermaid 代码块，然后在其中编写图表定义，渲染器就会自动生成可视化的图表。GitHub 在 2022 年开始支持在 Markdown 中嵌入 Mermaid 图表。
使用 Mermaid 的最大好处是图表可以像代码一样进行版本控制。传统画图工具生成的图表是二进制文件，无法用 Git 追踪变更。而 Mermaid 的图表定义是纯文本，每次修改都可以清晰地在 diff 中看到，这对于团队协作来说非常方便。目前支持 Mermaid 的平台包括 GitHub、GitLab、Notion（部分支持）、Obsidian（需插件）等。
GitHub Flavored Markdown（GFM）支持使用表情符号简码（emoji shortcodes）来插入表情符号。格式为 :表情名称:，比如 :smile: 显示为笑脸，:+1: 显示为竖大拇指。GitHub 和 GitLab 等平台都支持这种语法，但在其他平台上可能不兼容。
使用 emoji 可以让文档更加生动有趣，特别适合在 README 文件、项目公告、写作笔记中使用。但需要注意适度使用，过多的 emoji 会分散读者注意力，影响文档的专业性。在正式的技术文档中，建议只在需要表达情绪或强调的位置使用 emoji。
😄 表示开心 | 👍 表示赞同 | 🚀 表示发布或开始 | 📖 表示文档或学习 | ⚠️ 表示警告
扩展语法让 Markdown 的功能大大增强。表格适合展示结构化数据，任务列表适合做待办管理，脚注适合添加补充说明，数学公式适合学术写作，Mermaid 图表适合可视化流程，emoji 则让文档更生动。这些扩展语法虽然并非所有平台都支持，但掌握它们后，你在支持的平台上就能写出表现力极强的文档。遇到不支持的平台时，回退到基础语法即可。
Markdown 的优势之一是纯文本，任何文本编辑器（甚至记事本）都可以编辑 Markdown 文件。但使用专门的 Markdown 编辑器可以大幅提升写作体验——你可以在编辑的同时实时预览渲染效果，使用快捷键快速插入语法，以及利用各种插件扩展功能。下面介绍几种常用且好用的 Markdown 编辑器。
在线编辑器的最大好处是无需安装任何软件，打开浏览器就能使用。StackEdit 是一款功能丰富的在线 Markdown 编辑器，支持实时预览、同步到 Google Drive 和 GitHub、数学公式渲染等特性。HackMD（现在叫 Hedgedoc）是一款协作式 Markdown 编辑器，支持多人实时编辑，非常适合团队协作写文档。Markdown 在线预览工具（如 dillinger.io）则适合快速测试和转换 Markdown 内容。不过在线编辑器需要网络连接，且隐私性不如本地编辑器。
Typora 是一款广受好评的所见即所得 Markdown 编辑器。它的特点是编辑和预览完全合一——你输入的 Markdown 语法会实时渲染为格式化文本，而不是像其他编辑器那样分屏显示源码和预览。Typora 支持主题切换、图片拖拽、表格编辑、数学公式、导出为 PDF/HTML/Word 等多种格式，界面简洁优雅，对新手非常友好。
VS Code 是微软推出的免费代码编辑器，内置了对 Markdown 的出色支持。它使用分屏模式——左侧编辑源码，右侧实时预览。VS Code 的 Markdown 功能包括：Ctrl+Shift+V 打开预览、大纲视图快速导航、自动补全、丰富的扩展生态（如 Markdown All in One、markdownlint 等）。对于开发者来说，VS Code 是最理想的 Markdown 编辑器，因为你可以在同一个软件中写代码和文档。
Obsidian 是一款基于 Markdown 的知识管理软件，近年来在知识工作者中非常流行。它不仅是一个 Markdown 编辑器，更是一个双向链接的知识库。Obsidian 支持图谱视图、插件系统、标签管理、模板等功能，非常适合用于做个人知识管理、学习笔记和长期写作。它的核心文件就是本地的 Markdown 文件，所以即使不用 Obsidian，你也可以用其他编辑器打开编辑，不会被锁定在特定平台。
VS Code 是学习和使用 Markdown 的最佳起点之一。它内置了 Markdown 语言支持，无需安装任何插件就可以开始编辑。按下 Ctrl+Shift+V（Windows/Linux）或 Cmd+Shift+V（Mac）即可打开实时预览窗口。这个预览窗口和编辑区是同步滚动的，你编辑到哪里，预览就跟到哪里。VS Code 还提供了几个方便的快捷键：Ctrl+B 快速加粗、Ctrl+I 快速斜体。
如果你需要更强大的 Markdown 编辑体验，可以安装以下插件：Markdown All in One 提供了自动补全、表格格式化、目录生成、列表编辑快捷键等实用功能；markdownlint 可以检查你的 Markdown 语法是否符合规范，并在不合规的地方给出警告和建议；Markdown Preview Enhanced 增强了预览功能，支持数学公式、Mermaid 图表、导出为 PDF 等高级特性。VS Code 的资源管理器中的大纲视图也会自动展示 Markdown 文档的标题结构，方便长文档导航。
Pandoc 是文档格式转换的瑞士军刀，被称为"文档转换界的万能工具"。它可以实现 Markdown 与数十种文档格式之间的相互转换，包括 HTML、PDF、Word（docx）、LaTeX、EPUB、ReStructuredText、AsciiDoc 等。使用命令 pandoc input.md -o output.html 就可以将 Markdown 转换为 HTML。Pandoc 支持丰富的自定义选项，包括 CSS 样式、模板、目录生成等。
除了 Pandoc，还有一些专门的工具可以将 Markdown 转换为 PDF。md-to-pdf 是一个基于 Node.js 的工具，可以将 Markdown 文件直接转换为美观的 PDF 文档。Typora 和 VS Code 的 Markdown Preview Enhanced 插件也内置了导出 PDF 的功能。对于需要批量转换的场景，Pandoc 是最稳定的选择。
编辑器选择建议：如果你只是想简单写写笔记，从 Typora 开始最友好（所见即所得）；如果你是开发者，VS Code 是最全能的选择（代码+文档一站搞定）；如果你有长期知识管理的需求，Obsidian 最合适（双向链接+图谱）。对于快速测试和临时编辑，用在线编辑器就够了。无论选择哪个，核心文件都是标准 Markdown 格式，切换工具不会有任何成本。
选择合适的 Markdown 编辑器可以显著提升写作效率。在线编辑器方便快捷适合临时使用，Typora 的所见即所得模式对新手友好，VS Code 是开发者的全能选择，Obsidian 则适合构建个人知识库。配合 Pandoc 等转换工具，Markdown 文档可以轻松转换为各种其他格式。建议初学者先选一个编辑器开始写，等熟悉后再探索更多工具和插件。
在软件开发领域，Markdown 几乎无处不在。无论是开源项目的文档编写、团队内部的技术分享，还是个人博客的写作，Markdown 都是首选的文档格式。它的纯文本特性与 Git 版本控制天然契合，让文档可以像代码一样被跟踪、审查和协作。下面介绍 Markdown 在开发中的几个主要应用场景。
每个 GitHub/GitLab 仓库中最醒目的文件就是 README.md，它是项目的门面。一个优秀的 README.md 通常包含项目介绍（这个项目是做什么的）、安装说明（如何安装和配置）、使用指南（基本用法和示例）、API 文档（核心接口说明）、贡献指南（如何参与项目）、许可证信息等内容。GitHub 会自动渲染 README.md 并显示在仓库首页，好的 README 可以极大地降低项目的上手门槛。
README.md 的写作有一些最佳实践：使用清晰的标题层级来组织信息；在前面放一个项目 Logo 或简短介绍；安装步骤要一步步写清楚、配以代码块；如果项目有截图，用图片语法展示；贡献指南和许可证放在最后。一个项目是否专业，很多时候从 README.md 的质量就能看出来。
CLAUDE.md 是 Claude Code 的项目配置文件，位于项目根目录，使用 Markdown 格式编写。这个文件定义了项目的上下文、规则和指令，每次与 Claude Code 对话时都会自动加载。CLAUDE.md 中通常包含：项目的基本描述、文件结构说明、编码规范、测试要求、构建命令、部署流程等。通过精心编写 CLAUDE.md，你可以让 Claude Code 更好地理解你的项目，提供更准确的帮助。
CLAUDE.md 的内容质量直接影响 Claude Code 的辅助效果。比如你可以在 CLAUDE.md 中写"项目使用 TypeScript 编写，遵循 ESLint 配置"，每次对话 Claude Code 就会自动采用对应的代码风格。写好 CLAUDE.md 是高效使用 Claude Code 的关键一步。注意到本节笔记就是依据 CLAUDE.md 中的标准化流程生成的。
许多现代化的文档网站生成工具都使用 Markdown 作为内容源文件。Docusaurus 是 Facebook 开源的文档网站框架，使用 Markdown 编写文档内容，可以生成带有搜索、版本管理、国际化等功能的美观文档网站。MkDocs 是 Python 生态中的文档生成器，配置简单，支持 Material Design 主题。VitePress 是 Vue.js 生态中的静态网站生成器，性能优秀，适合生成技术文档和博客。
这些工具的核心理念是"内容与展示分离"：你用 Markdown 专注于写内容，工具负责把 Markdown 渲染成漂亮的网页。这意味着你不需要了解前端的知识，就可以创建出专业级别的文档网站。很多知名项目的文档网站（如 Vue.js、React、Python 等）都是基于这些工具构建的。
静态博客生成器（如 Hexo、Hugo、Jekyll）广泛使用 Markdown 作为文章格式。你只需要用 Markdown 写好文章内容，通过一条命令就能生成完整的静态博客网站，可以部署到 GitHub Pages 或自己的服务器上。Hexo 基于 Node.js，主题丰富；Hugo 基于 Go，构建速度极快；Jekyll 基于 Ruby，与 GitHub Pages 原生集成。这些工具让写博客变得像写代码一样简单高效。
在知识管理领域，Obsidian 和 Notion 是两大主流工具。Obsidian 完全基于本地 Markdown 文件，支持双向链接和知识图谱，适合长期的知识积累。Notion 虽然使用自己的块编辑器，但也支持 Markdown 导入导出。无论使用哪种工具，理解 Markdown 都能让你更灵活地管理和迁移你的知识库。
GitHub 在整个平台中深度集成了 Markdown。在 Issue 中，你可以使用 Markdown 来格式化问题描述、添加任务列表、贴代码片段。Pull Request 的描述同样使用 Markdown，可以包含变更列表、测试说明、截图等。GitHub Wiki 完全使用 Markdown 编写，适合作为项目的扩展文档。GitHub Pages 支持 Jekyll，可以用 Markdown 直接生成个人网站或项目网站。
GitHub Flavored Markdown（GFM）是 GitHub 对标准 Markdown 的扩展，增加了一些特定功能：任务列表、表格、删除线、emoji、自动链接、代码块语法高亮等。在 GitHub 中写 Issue、PR 或 Wiki 时，这些 GFM 扩展都是可用的。了解 GFM 的特性能让你在 GitHub 上的协作更加高效。
Markdown 是开发文档的通用语言。从 README.md 到 CLAUDE.md，从文档网站到个人博客，从 GitHub Issue 到项目 Wiki，Markdown 贯穿了整个软件开发周期。掌握 Markdown，不仅是学会了一种文档格式，更是融入了现代开发者协作文化的一部分。每一个开发者都应该熟练掌握 Markdown 的编写。
Claude Code 是 Anthropic 推出的 AI 编程助手，在终端的对话界面中使用。你可能已经注意到，Claude Code 的所有输出格式、配置文件、对话内容都与 Markdown 密不可分。理解 Markdown 不仅能帮你更好地使用 Claude Code，还能让你通过正确编写配置文件来提升 Claude Code 的辅助效果。本章将详细介绍 Markdown 在 Claude Code 中的各种应用场景。
CLAUDE.md 是位于项目根目录的 Markdown 文件，它是 Claude Code 了解项目的入口。每次你开始一个新的对话时，Claude Code 会自动读取这个文件，获取项目的上下文信息。这是一个普通文本文件，使用你最熟悉的 Markdown 格式编写，任何人都可以轻松编辑。CLAUDE.md 的内容质量直接决定了 Claude Code 对你的项目理解得有多深。
一个精心编写的 CLAUDE.md 应该包含：项目的基本介绍（一句话描述项目是做什么的）、技术栈信息（使用什么语言和框架）、项目结构说明（各个目录的用途）、代码风格规范（缩进、命名、注释等要求）、构建和测试命令（让 Claude Code 知道如何操作）、部署流程（上线步骤）等内容。比如你可以在 CLAUDE.md 中写"本项目使用 React + TypeScript，遵循 Airbnb 代码规范，使用 pnpm 包管理器，通过 Vitest 运行测试"——这样 Claude Code 生成的代码就会自动符合这些规范。
当你与 Claude Code 对话时，它的所有输出都是 Markdown 格式的。你会看到代码被包裹在三个反引号中并带语法高亮，要点和步骤用有序列表清晰列出，对比信息用表格呈现，文件路径和命令用行内代码标记。这意味着即使你不编辑 Markdown 文件，只是在终端中与 Claude Code 交互，你也在接收 Markdown 格式的信息。了解 Markdown 能让你更高效地阅读和理解这些输出。
具体来说，Claude Code 输出的代码块会自动检测语言并添加语法高亮，这让代码中的关键字、字符串、注释一目了然。当 Claude Code 列出多个选项或步骤时，会使用有序列表组织信息。对比不同方案时，表格是最常用的格式。命令和文件路径会使用行内代码格式突出显示。这些 Markdown 格式的细节让信息更加清晰易读。
你正在阅读的本篇学习笔记，就是基于 Markdown 思维和标准流程生成的。在 Claude Code 的学习笔记生成系统中，模板文件（template.html）定义了基本的 HTML 结构和 CSS 样式，而内容组织方式——章节划分、标题层级、列表结构、代码示例——都是 Markdown 的思维方式。每篇笔记的标题使用一级标题，主要章节使用二级标题，子章节使用三级标题，内容中的列表、代码块、引用块都是 Markdown 语法在 HTML 中的对应呈现。
这个笔记系统的核心流程就是：读取原始文本 → 使用 Markdown 结构组织内容 → 填充到 HTML 模板 → 生成最终页面。可以说，格式化的输出最终一定要求助于 Markdown 的思路。学习 Markdown 不仅是为了写文档，更是为了理解 Claude Code 如何处理和组织信息。
Claude Code 的技能（Skills）是一组预定义的指令和能力，可以通过插件系统安装和配置。技能的描述文件、触发规则和配置选项都使用 Markdown 格式编写。当你调用一个技能时，技能定义的 Markdown 内容会作为系统提示的一部分，指导 Claude Code 的行为。理解 Markdown 可以帮助你编写更有效的技能配置。
比如 skills 的定义文件中，描述部分使用 Markdown 格式的列表、标题、代码块等来详细说明技能的用途和触发条件。如果你的技能需要展示结构化的输出，熟悉 Markdown 的表格、列表、代码块语法就特别重要。简而言之，想要自定义或扩展 Claude Code 的能力，对 Markdown 的深入理解是必不可少的。
在与 Claude Code 或其他 AI 助手交互时，提示词（Prompt）的质量决定了回答的质量。而有效的提示词往往使用 Markdown 来结构化地组织信息。通过使用标题分隔话题、用列表罗列要求、用代码块提供上下文、用表格对比选项，你可以让提示词更加清晰、完整、有条理。AI 模型在处理结构化的 Markdown 输入时，也更容易准确理解你的意图。
举例来说，一个结构化的提示词可能这样组织："## 背景"（用一段话描述项目背景）、"## 需求"（用列表列出具体需求）、"## 约束条件"（用列表说明技术限制）、"## 示例输出"（用代码块展示期望的输出格式）。这种结构化的提示词比一段混乱的文字要有效得多。掌握 Markdown 的标题、列表、代码块语法，就是掌握了写好提示词的基本功。
关键洞察：Markdown 是 Claude Code 的"母语"。从配置文件的编写、对话输出的呈现、学习笔记的生成，到技能系统的配置和提示词的组织，Markdown 贯穿了 Claude Code 的各个环节。学习 Markdown 不是为了一个孤立的技能，而是为了更好地理解和使用 Claude Code 这个强大的工具。两者是相辅相成的关系。
Markdown 和 Claude Code 密不可分。CLAUDE.md 文件定义了项目上下文，对话输出使用 Markdown 格式化展示，学习笔记系统基于 Markdown 思维构建，技能配置依赖 Markdown 格式，而结构化提示词更是 Markdown 的实际应用。可以说，掌握了 Markdown，你就真正掌握了与 Claude Code 高效沟通的方式。
学习了 Markdown 的语法和应用场景之后，你可能已经跃跃欲试想要开始写 Markdown 文档了。为了更好地发挥 Markdown 的优势，避免踩坑，这里总结了一些经过实践检验的最佳实践建议。遵循这些原则，你的 Markdown 文档会更加清晰、易读、易维护。
原则一：保持简单，不要过度使用复杂语法。Markdown 的核心优势是简单。仅仅为了炫技而在文档中使用过于复杂的嵌套语法（比如在表格中插入代码块、在列表中嵌套多层引用），可能会让 Markdown 源码变得难以阅读，且在不同平台上的渲染效果不一致。能用简单语法解决的问题，就不要用复杂语法。记住"易读易写"是 Markdown 的核心理念。
原则二：注意兼容性，了解不同平台的渲染差异。标准 Markdown 语法在所有平台上都能正常渲染，但扩展语法（表格、任务列表、脚注、数学公式等）在不同平台上的支持程度不同。在写文档之前，先了解你的目标平台支持哪些语法。如果你的文档需要同时在 GitHub、公司内网、移动端 App 等多个平台显示，尽量使用标准语法，避免使用非标准扩展。如果必须使用扩展语法，在文档中注明所需的渲染环境。
原则三：合理使用标题层级，不要跳级。标题是文档的骨架，清晰的标题层级让文档结构一目了然。一个文档通常只有一个一级标题（文档标题），二级标题是主要章节，三级标题是子章节，四级及以下尽量少用。不要从二级标题直接跳到五级标题，这会让文档结构混乱。在编辑器中打开大纲视图查看标题层级是否合理——如果大纲看起来结构清晰，文档通常也不会差。
原则四：代码块务必指定语言名称。在代码块的起始反引号后面加上语言名称（如 ```python、```javascript、```bash），可以激活语法高亮，极大地提高代码的可读性。大多数平台上，指定语言后还会显示语言标签，方便读者识别。如果不确定用什么语言名称，常用的有：python、javascript、typescript、bash、json、html、css、sql、yaml 等。
原则五：表格保持整洁，用在线工具生成复杂表格。在源码中手工对齐表格管道符非常繁琐，而且容易出错。对于简单的表格（3-4列、几行数据），手写没问题。对于复杂表格，建议使用在线 Markdown 表格生成器（如 tableconvert.com、tablesgenerator.com），输入数据后自动生成格式化的 Markdown 表格代码。在 VS Code 中，Markdown All in One 插件的表格格式化功能也可以帮助对齐表格。
原则六：链接使用描述性文字，不要用"点击这里"。链接的可读性对文档质量影响很大。不要把链接写成"请点击这里获取更多信息"，而是写成"请在 GitHub 帮助文档 中查看更多信息"。前者的链接文字没有提供任何信息，后者则在链接文字中说明了链接的目标内容。这对于屏幕阅读器用户来说尤其重要。同时，内链与外链分开管理，相关的链接可以分组放在文档末尾（引用式链接）。
原则七：定期预览，确保渲染效果符合预期。在写完文档后，一定要在目标平台上预览最终的渲染效果。因为不同平台对 Markdown 的解析存在细微差异，你可能在本地编辑器中看到的效果和在 GitHub 上看到的并不完全一致。特别需要检查的内容包括：表格是否完整显示、代码块是否正常高亮、图片是否能正常加载、链接是否跳转到正确位置、列表的层级是否正确等。
原则八：善用版本控制，发挥 Markdown 纯文本优势。Markdown 文件是纯文本，天然适合 Git 版本控制。每次对 Markdown 文件进行修改后，Git 会精确记录每一处变化——你添加了什么、删除了什么、修改了什么。这使得 Markdown 文档非常适合团队协作和长期维护。建议：每个 Markdown 文件添加一个"最后更新日期"元信息；在文件头部用注释或元信息块记录文档的版本历史；重要的文档在 Git commit message 中记录修改原因。
| 用途 | 推荐语法 | 不推荐的做法 | 原因 |
|---|---|---|---|
| 标题 | # 到 #### | 跳到 ##### 或 ###### | 层级太深说明需要重构 |
| 强调 | **粗体**、*斜体* | __粗体__、_斜体_ | 星号兼容性更好，更醒目 |
| 列表 | - 无序列表 | * 或 + 开头 | 短横线最通用，不容易误解 |
| 代码块 | ``` + 语言名 | 不指定语言的 ``` | 语法高亮提升可读性 |
| 链接 | [描述性文字](URL) | [点击这里](URL) | 描述文字帮助读者理解链接目标 |
| 分割线 | --- | *** 或 ___ | 短横线最常用，不易混淆 |
写好 Markdown 的核心原则是"内容为王，格式为辅"。目录结构要清晰（标题不能跳级）、可读性要高（代码块标明语言、链接写描述文字）、兼容性要好（了解目标平台的支持范围）、可维护性要强（版本控制、更新记录）。遵循这些原则，你的 Markdown 文档无论过多久、无论谁来看，都能保持高质量。记住，最好的 Markdown 文档是你写完后几乎不需要考虑"格式"问题的文档——因为格式已经融入了写作的自然流程中。
经过七个章节的详细学习，我们已经全面掌握了 Markdown 标记语言。在最后这一章，让我们回顾一下需要记住的核心要点，以及这些知识如何在日常工作和学习中实际应用。无论你是刚刚开始接触 Markdown，还是已经有一些使用经验，这些要点都是最值得记住和掌握的内容。
Markdown 的核心价值是"易读易写"。它使用简单的符号（# * - ` [] >）来格式化纯文本，让写作者可以专注于内容本身，而不是排版。与 Word 相比，Markdown 文件是纯文本，体积小、跨平台、适合版本控制。与 HTML 相比，Markdown 语法极其简洁，学习成本几乎为零。Markdown 是开发者文档的事实标准，也是学习 Claude Code 的必备前置知识。
Markdown 的基础语法包括：标题（# 1-6级）、段落与换行（空行分隔/行尾两空格）、强调（*斜体* **粗体** ~~删除线~~）、列表（-无序 1.有序 嵌套缩进）、代码（`行内` ```代码块 ```）、链接 [文字](URL)、图片 、引用（> 嵌套 >>）、分割线（---）和转义（\）。这些基础语法覆盖了日常写作 80% 以上的场景，是所有 Markdown 应用的基石。
在基础语法之上，扩展语法（表格、任务列表、脚注、定义列表、数学公式、Mermaid 图表、emoji）大大增强了 Markdown 的表现力。表格适合组织和对比数据，任务列表适合做待办管理，数学公式适合学术写作，Mermaid 图表可以可视化流程图和架构图。需要注意的是，不同的 Markdown 渲染器对扩展语法的支持程度不同，在跨平台使用时需要做兼容性检查。
Markdown 的纯文本特性意味着任何文本编辑器都可以处理，但选择对的编辑器可以显著提升效率。新手建议从 Typora（所见即所得）开始；开发者首选 VS Code（集成度高，扩展丰富）；知识管理者可以选择 Obsidian（双向链接、知识图谱）。无论选择哪个工具，核心文件都是标准的 Markdown 格式，不存在平台锁定问题。配合 Pandoc 等转换工具，Markdown 可以转换为 PDF、HTML、Word 等多种格式。
在软件开发领域，Markdown 几乎无处不在：项目的 README.md 文件、CLAUDE.md 项目配置、Docusaurus/MkDocs/VitePress 文档网站、Hexo/Hugo/Jekyll 静态博客、GitHub Issue/PR/Wiki 等全部使用 Markdown。掌握 Markdown 不仅是学会一种文档格式，更是融入现代开发者协作文化的基础。每一个开发者都应该熟练使用 Markdown。
Claude Code 的各个环节都与 Markdown 紧密相关：CLAUDE.md 使用 Markdown 定义项目上下文；对话输出使用 Markdown 格式化（代码块、列表、表格）；学习笔记系统基于 Markdown 思维构建；技能配置依赖 Markdown 格式；结构化提示词本质上是 Markdown 的组织方式。学习 Markdown 是为了更好地使用 Claude Code，两者相辅相成。
写 Markdown 文档时，遵循以下原则可以显著提升文档质量：保持简单、注意兼容性、标题不跳级、代码块标语言、表格用工具生成、链接写描述文字、定期预览渲染效果、善用版本控制。最好的 Markdown 文档让读者感觉不到"格式"的存在——因为内容本身就足够清晰，格式只是锦上添花。始终记住，Markdown 是为内容服务的工具，内容永远比格式重要。
理论知识学得再好，也不如动手写一次印象深刻。建议你现在就打开编辑器，创建一个 test.md 文件，从写一个简单的标题和段落开始，逐步尝试列表、代码块、链接、表格等语法。把你正在读的这篇笔记的要点用 Markdown 写下来，或者把自己的日常笔记转成 Markdown 格式。写得越多，你就会越熟练，最终 Markdown 会成为你自然而然的写作方式。
Markdown 的语法虽然简单，但应用场景非常广泛。建议你按照以下路径持续学习和实践：第一周，掌握基础语法（标题、列表、链接、代码、引用），每天写一篇 Markdown 笔记。第二周，学习扩展语法（表格、任务列表），尝试用 Markdown 做一个 TODO 清单。第三周，将 Markdown 应用到实际工作中——给你的项目写一个 README.md，或者在 GitHub 上用 Markdown 提交 Issue。一个月后，Markdown 会成为你的第二本能。到那时，你会发现自己在任何需要写文字的地方，都会自然地想到如何用 Markdown 来组织内容。
总复习：Markdown = 简单符号 + 纯文本 = 易读易写的文档。九大基础语法（标题、段落、强调、列表、代码、链接、图片、引用、分割线） + 七大扩展语法（表格、任务列表、脚注、定义列表、数学公式、Mermaid、Emoji） + 合适的编辑器（Typora/VS Code/Obsidian）= 完整掌握 Markdown。当你能熟练使用 Markdown 写 README、CLAUDE.md、结构化提示词时，你就已经超过了 90% 的文档写作者。