Markdown 从入门到实战：纯文本写作、格式转换与高效工作流

1. Markdown到底是什么，为什么技术圈都在用它

先说一个最直观的感受：你肯定遇到过这种场景——在微信、Word、公众号后台里排格式，加粗要选文字再点按钮，标题要一级一级手动调，换个平台粘贴过去格式全乱，图片还经常跑到莫名其妙的位置。这个过程浪费的时间，加起来可能比写内容本身还多。

Markdown解决的就是这个问题。它本质上是一套纯文本排版约定，你在写内容的时候，直接在文字里插入一些简单的符号（比如#、*、>），就能表示标题、加粗、引用、列表这些格式。文件保存下来就是一个.md结尾的纯文本文件，任何电脑、任何编辑器都能打开。真正渲染成漂亮的排版，是在发布或导出时由工具自动完成的。

这个思路的厉害之处在于：写作和排版彻底分开了。你只需要专注内容，格式是"顺手"标出来的，不需要停下来点鼠标。而且纯文本的特性，让它天然适合版本管理、协作编辑、跨平台传播——程序员写技术文档、开源项目的 README、GitHub 上的说明页，几乎全是用 Markdown 写的。

我最早接触 Markdown 是写技术博客的时候。那时在富文本编辑器里贴代码，缩进经常被吃掉，各个平台转来转去还会把标签直接显示出来，特别崩溃。后来换到 Markdown，一篇博文一份纯文本，首发在个人博客，再帖到公众号、知乎、掘金，排版几乎不重做。这个"写一次，到处发布"的体验，用过之后就再也回不去纯富文本了。

如果你是刚开始接触 Markdown 的纯新手，或者只会用编辑器的可视按钮、想突破一下效率瓶颈，这篇文章就是为你准备的。我会从最基本的标题写法讲起，一路到表格、代码块、图片、数学公式这些高频功能，每一步都有我自己踩过的坑和经验教训。全部内容都非常基础，但都是能直接上手的干货。

注意：Markdown 只是"约定俗成的纯文本格式"加上"解析器"，并不存在唯一的官方标准。市面上主流实现（GitHub Flavored Markdown、CommonMark、各编辑器的扩展）在绝大多数功能上是一致的，本文按照最通用的写法来讲，同时会注明哪些功能依赖具体编辑器或平台。

2. 先从标题、段落、换行这几个最基础的写起

2.1 标题的写法和层级逻辑

标题是 Markdown 里最常用的元素，写法就是在行首加#，#的个数对应标题层级。#是一级标题，##是二级标题，###三级，以此类推，最多支持六级。

# 这是一级标题 ## 这是二级标题 ### 这是三级标题 #### 这是四级标题 ##### 这是五级标题 ###### 这是六级标题

有个关键细节：#和标题文字之间必须有一个空格。写成#标题在很多解析器里会被识别成普通文本，而不是标题。我见过太多新手在这个地方卡住，明明写了井号，渲染出来却什么都没变。不同编辑器对这种写法的兼容程度不一样，但在 Typora、VS Code、GitHub 上，标准写法都是# 空格 文字。

另一个重要原则是标题层级不要乱跳。比如你用##开了个二级标题，下面直接接####四级标题，跳过了三级，虽然渲染不会报错，但文档结构会显得非常混乱，目录生成也会不规整。正确的做法是像大纲一样逐级下钻：一级下面跟二级，二级下面跟三级。我自己的习惯是，核心的一级标题很少用，文章标题单独放，正文里用##开始分章节，###和####逐层细化。

2.2 段落、换行与空行的正确打开方式

段落非常简单：一个或多个连续的文本行组成一个段落，段落之间用一个空行分隔。空行是 Markdown 里特别重要的存在——很多人以为换行只要回车就行，结果渲染出来的文字全都挤在一起，这就是没搞懂"段落"和"换行"的区别。

先说结论：

• 想在渲染结果中真正开始一个新段落，上一段和下一段之间必须空一行。
• 想要"段内换行"（仍是同一段落，只是视觉上换了一行），标准 Markdown 的做法是在上一行末尾加两个空格再回车。

这是第一个段落。 这里我敲了回车，但没有空行，渲染后它是跟在上一行后面的。 如果上一行结尾有两个空格，这里就会是真正的换行。 这是第二个段落，因为它前面有空行。

如果你用的是 Typora 这类"所见即所得"的 Markdown 编辑器，Enter键直接就是生成新段落，Shift + Enter是段内换行，完全不用手打两个空格。但如果你在 GitHub、知乎这类平台写 Markdown，两个空格的技巧就很有用了。我个人强烈建议：能用空行分段就别用空格换行。空格换行在不同平台上渲染差异极大，比如在某些系统里两个空格不会被识别为换行，最后出来的排版和你预想完全不同。写文档时，结构清晰优先，段内换行能少用就少用。

2.3 分割线与基础文本样式

分割线通常用来分隔不同章节或话题。写法是独立一行，内容为三个或以上的星号***、减号---或下划线___。

--- *** ___

这三种写法在主流实现里都能正确渲染成横线。但有一个特别容易踩的坑：---在有些场合会被识别成二级标题的语法。比如你在正文里写一行---，前面没有空行，Markdown 解析器可能认为这是##的另一种写法，导致意外出现了一个标题。解决办法就是写分割线时前后都要留空行，或者干脆用***更稳妥。

基础文本样式是 Markdown 里使用频次最高的功能，语法要背熟：

• 加粗：**文字**或__文字__，渲染为加粗文字。
• 斜体：*文字*或_文字_，渲染为斜体文字。
• 删除线：~~文字~~，渲染为~~删除线文字~~。

在这三种样式里，加粗是最常用的，建议一律使用双星号**加粗**，因为星号在所有键盘布局上都容易输入，而且视觉上比下划线明显。斜体在下划线写法中和普通文本容易混淆，也建议统一用单星号。要注意删除线的~~是两个波浪号字符，不是两个减号。

嵌套使用也是可以的，比如加粗斜体：***同时加粗和斜体***。不过我不太建议在正文里叠太多样式——Markdown 的哲学是让文本保持简洁，你可以用加粗强调关键词，用斜体补充说明信息，但一段话里到处是星号，阅读体验其实很糟糕。

3. 列表、引用、代码：支撑技术文档的三根柱子

3.1 无序列表和有序列表的写法与坑

列表是技术文档里最常出现的结构。无序列表的写法是在行首用-、*或+加一个空格，然后写内容：

- 第一项 - 第二项 - 第三项

有序列表用数字加英文句号加空格：

1. 第一步 2. 第二步 3. 第三步

这里有个很多人不知道的技巧：有序列表的数字可以全部写成1.，Markdown 会自动按顺序编号。这样做的好处是你在调整列表顺序时，不需要手动改每一行的数字。我自己写步骤时就经常全部用1.，最后渲染效果和 1、2、3 完全一样，省去很多维护成本。

列表可以嵌套，但要记住：嵌套列表要缩进，通常一级列表下面再缩进两个或四个空格。具体缩进多少取决于编辑器，但关键点是下一级列表的第一层缩进必须和上一级文字起始位置对齐。不同解析器对空格数量的要求略有差异，我的建议是统一用 4 个空格完成嵌套缩进，兼容性最好。

嵌套示例：

- 一级列表项 - 二级列表项 - 二级列表项 - 三级列表项

容易踩的坑：列表项之间如果插入空行，有的解析器会把列表拆分成两组，导致样式错乱；直接回车，续行内容如果顶格写，也可能从列表变成普通文本。想要在列表项内多写几行文字，子行要跟着列表项的缩进走。

3.2 引用块及其多层嵌套用法

引用块用于引用他人的话、重要提示或需要强调的段落。写法是行首加>和空格：

> 这是一条引用内容。

引用块内可以直接包含多个段落，只要每段前面都加上>即可。多段引用示例：

> 这是引用的第一段。 > > 这是引用的第二段。

引用块也可以嵌套：>套>>，渲染出嵌套效果。这在写"注意事项"或"补充说明"时非常好用。比如我经常这样写：

> 核心结论：这一部分用引用来强调。 > > > 更深一层的解释：这是嵌套引用，相当于引用中的引用。

我还特别喜欢在引用块里结合列表和加粗，一条条列要点，视觉效果一下就很清晰。代码风格的引用块加粗，在个人博客或公众号里尤其醒目，读者一眼就能抓住重点。

注意：引用块在有些编辑器中会使用灰底或竖线样式，视觉效果很好；但不要滥用，满篇全是引用会让正文失去层次感。一般情况下，引用适合做提示、结论、风险说明，不适合整段整段地引用。

3.3 代码块和行内代码，写技术文档的刚需

代码在 Markdown 中有三种表达方式：行内代码、缩进代码块、栅栏式代码块。

行内代码用反引号包裹，用于在文字中插入变量名、命令、函数名等：

请执行 `pip install requests` 这个命令。

这里注意，反引号是英文键盘左上角的那个字符（通常在1键的左边），不是单引号。中英文切换时很容易打错，打错以后渲染不出代码样式，看起来就是普通文字。

整段代码则需要代码块。栅栏式代码块是最推荐的写法：用三个反引号包裹，并且在开头三个反引号后面可以标语言类型，这样渲染时会自动做语法高亮：

```python def hello(): print("Hello, Markdown!")

语言标识根据实际使用来填，常见的有 `python`、`javascript`、`bash`、`json`、`sql`、`c`、`cpp`、`java` 等。如果实在不确定用什么标识，也可以不写，只是少了高亮。 缩进代码块是另一种旧式写法：把代码整段缩进 4 个空格或一个 Tab。这种写法在嵌入列表等复杂结构中很容易出问题，我一般只用栅栏式。再说一个细节：**代码块中的内容是原样显示的**，Markdown 符号不会被解析，所以你可以放心在代码块里写 `#`、`*`、`>` 这些符号。 写技术文档时的实用习惯：命令行操作示例用 `bash` 标识，配置文件用 `ini` 或 `yaml`，API 返回数据用 `json`。不同语言的高亮效果不同，选对了阅读体验提升非常明显。 ## 4. 链接、图片、表格：让文档真正完整起来的实用功能 ### 4.1 链接的写法和相对路径技巧 链接的语法是 `[链接文字](链接地址)`。行内式写法：

百度

如果想给链接加个悬停提示，可以在地址后面加空格和引号写标题：

百度

还有参考式写法，适合文档中同一个链接被多次引用的情况。把链接地址提炼到文档末尾：

大家可以访问 百度 和 知乎 。

这种写法最大的好处是：正文干净，链接集中管理，文档更新很轻松。不过如果只是偶尔引用一次，直接用行内式就够了，不用搞得过于复杂。 链接地址支持相对路径，这在本地写文档时特别重要。比如你有个项目文件夹，里面放了 `docs/index.md` 和 `images/logo.png`，想在文档里引用图片，可以写相对路径 `images/logo.png`，这样整个文件夹打包带走或传到 GitHub，链接都不会失效。我见过有些小白把本地图片路径写成 `C:\Users\...` 这种绝对路径，传到线上之后图片全部裂开，这就是没用相对路径的典型后果。 ### 4.2 图片语法：唯一比链接多一个感叹号的地方 图片语法和链接几乎一样，只是开头多一个 `!`：

如果图片加载失败，替代文字会显示出来，所以别随便乱写，尽量填能描述图片内容的话，比如：

图片和链接一样支持相对路径。有些平台还支持 `width` 属性控制大小，但这个不是标准 Markdown，不同编辑器支持程度不同，比如在某些静态站点生成器里就需要用 HTML 的 `<img>` 标签来设置宽高。我的建议是：如果对排版没有特殊要求就用标准写法，如果需要调整大小，再看你用的编辑器支持哪种扩展语法。 我自己写博客时，图片通常统一放在 `images/` 文件夹下，文件名用英文小写加连字符（比如 `markdown-logo.png`），避免中文或空格导致的路径兼容问题——这在 Windows 本地编、Linux 服务器部署的场景下尤其重要。 ### 4.3 表格：写法简单，但细节很容易翻车 表格是很多人用 Markdown 的主力功能，比如对比参数、整理清单、列时间计划都靠它。表格语法由表头、分隔行和数据行组成：

关键点： - 分隔行是由 `-` 组成的那一行，必须有，它把表头和数据区分开。 - 每一列之间用 `|` 分隔，表头和数据行的列数要对应。 - 左右两侧的 `|` 可以省略，但视觉上容易乱，建议都写上，这样结构更清晰。 - 表格中单元格内文本默认左对齐。如果想指定对齐方式，可以在分隔行里写冒号：`---` 左对齐，`:---:` 居中，`---:` 右对齐。 对齐示例：

表格里的坑主要在竖线字符本身：如果单元格内容里需要显示 `|`，必须用 `\|` 转义，否则表格会多出一列。比如：

另一个常见问题是：有些编辑器里表格前后需要留空行，否则表格会粘进段落导致渲染异常。写表格时我会习惯性地前后各空一行，这样在几乎任何解析器里都不会出问题。 ### 4.4 表格转 Excel 的便捷思路 在热搜词里出现了"markdown表格转换excel"，这确实是 Markdown 表格的一个高频用途。比如你在 Typora 里排版好了一张表格，老板说"把这个给我导出到 Excel"，最省事的方式不是重新在 Excel 里敲一遍，而是直接复制渲染后的表格，粘贴到 Excel 里——大部分情况下，Markdown 渲染后的 HTML 表格已经携带了结构信息，Excel 会智能识别列和行。 如果粘贴后 Excel 没自动拆分，还可以用 Excel 的"文本分列"功能：粘贴后选中列，找到"数据 -> 分列"，按"分隔符号"，勾选"制表符"或"自定义"并填 `|`，即可拆出多列。这个方法虽然不是纯 Markdown 操作，但配合使用非常实用。 要是你经常需要 Markdown 和 Excel 互相转换，也可以搜索一些在线工具或 VS Code 插件（比如 "Markdown Table Prettifier" 配合复制粘贴）。工具层面选择很多，核心思路都是一样的：**让结构化的 Markdown 表格变成结构化的行列数据**。 ## 5. 进阶功能：任务列表、数学公式、HTML 混排 ### 5.1 任务列表：项目管理的一把好手 任务列表（Task List）是在普通列表项里加一个复选框标记 `[ ]`（未完成）或 `[x]`（已完成）：

• [ ] 待办事项一
• [x] 已完成事项
• [ ] 待办事项三

这在写计划、追踪项目进度时非常直观。要注意的是，任务列表依赖具体平台的扩展支持：GitHub、Typora、VS Code 里都支持得很好，但在某些老旧的 Markdown 解析器里可能不会渲染成复选框。所以如果你要在某个平台发布含任务列表的内容，先确认平台支持情况。 我个人的习惯是：项目文档里的 TODO 清单、需求拆分、测试用例列表都优先用任务列表，它比普通列表多一个状态维度，复查进度时一眼就能看清还剩什么。 ### 5.2 数学公式：用 LaTeX 符号写优雅的表达式 Markdown 原生不支持复杂的数学公式，但很多 Markdown 编辑器（Typora、Obsidian）和静态站点生成器都支持通过 LaTeX 语法渲染公式。行内公式用单个美元符号包裹，独立展示的公式块用两个美元符号包裹：

行内公式：$x^2 + y^2 = z^2$

公式块： $$ f(x) = \sum_{i=0}^{n} \frac{x_i}{n} $$

我这里写 LaTeX 符号只用了最基础的形式，真实的复杂公式还可以写积分、矩阵、分式，但用法和 LaTeX 写作一致，需要单独学习。给非理工科读者的建议：如果平时不用数学公式，这一节可以跳过；写理工类笔记或论文相关内容的，很值得花点时间把基础 LaTeX 符号熟悉一下，因为这是一个"学会一次、随处渲染"的技能。 要注意的是，不同解析器对数学公式的支持差别很大：Typora 开箱即用，GitHub 需要用特殊标记开启（在 GitHub 的 Markdown 里，公式块是用 `$$` 包起来的特殊写法），微信公众号是不支持的。所以如果你写的内容要发布到不支持公式的平台，标题提到的"markdown 数学符号"就只能在本地编辑器里欣赏了，发布时还是要转成图片或截图。 ### 5.3 在 Markdown 里嵌入 HTML Markdown 标准允许直接写 HTML 标签，解析器会把 HTML 原样通过，不做额外处理。这意味着你可以用 HTML 实现 Markdown 覆盖不到的功能，比如自定义对齐、图片大小控制、彩色文本等：

HTML 混排是很多进阶用户离不开的技巧，但也要克制使用。一支文档里偶尔用一次<center>或自定义图片宽高没问题，到处塞 HTML 标签会让 Markdown 失去"纯文本简洁"的核心价值。我的原则是：能用 Markdown 解决的绝不用 HTML，Markdown 解决不了（比如精确控图）再动手写 HTML。

还有一个提醒：在代码块里写 HTML，代码块的原样特性会让它不参与 Markdown 解析，所以如果你想展示 HTML 语法本身，记得把示例放进反引号代码块里。

6. 编辑器选择与工作流搭建

6.1 主流 Markdown 编辑器怎么选

市面上的 Markdown 编辑器很多，我按使用场景简单分个类：

如果是零基础，我最推荐先试 Typora。它最大的优点是"所见即所得"，你不用记所有语法，一输入符号立刻看到效果，学习成本几乎为零。等熟练之后，如果想在文章里插代码、配合 Git 管理版本，再用 VS Code 也不迟。

6.2 图片粘贴与路径管理

"markdown图片路径"这个热搜词很多人搜，因为图片管理是 Markdown 使用中非常容易翻车的一环。我的建议是分两步解决：

第一，编辑器中设置好图片保存规则。比如 Typora 里可以配置"复制图片到 ./images 文件夹"并自动重命名，这样每次粘贴截图，图片都会自动保存到文章所在目录下的images文件夹，正文里自动插入相对路径。

第二，图片统一命名规范。我在 4.2 节提到过，英文小写加连字符是最稳妥的。这样整个文档文件夹传到 GitHub 或部署到服务器，所有图片路径都不会因为大小写和空格出问题。

如果发现路径引用错了，最常见的是相对路径算错层级。比如docs/sub/page.md要引用根目录下的images/logo.png，正确写法是../../images/logo.png。这个../表示"上一层目录"，很多人在嵌套目录里拼路径时容易数错层次。我的技巧是：先在浏览器或文件管理器里确认图片和 md 文件的相对位置，再写路径，不要凭感觉猜。

6.3 从 Markdown 到 Word 和 PDF

标题相关的热搜词里有"markdown 转 word"和"markdown 转 word 工作流"。工作中有时候必须交付 Word 文档，Markdown 无法直接替代，转换就不可避免。

最简单的方案是：在 Typora 里直接导出 Word（.docx）或 PDF。Typora 的导出基于内置模板，样式已经处理得很好，普通文档导出后基本不需要大改。如果你想做更精细的样式控制，Pandoc 是更专业的工具，它几乎可以在任意文档格式之间转换，包括 Markdown 转 Word、Markdown 转 PDF 等等。

再结合"dify markdown 转 word 中序号自动编号"这个热词，现实中转换 Word 后常见的问题是：标题层级和自动编号容易乱，因为 Markdown 没有 Word 里"多级列表编号"这种概念。如果你遇到这种情况，只能在 Word 里手动调整多级标题的编号方案，或者使用 Pandoc 配合自定义模板来尽量控制。老实说，这一步想要"完全自动化且完美"很难，我在实际项目中也是导出后用 Word 微调一遍样式，接受一定的"转换损耗"。

7. 我常用的几条实用技巧与常见问题

7.1 统一符号规范，减少低级错误

学了所有语法之后，最容易犯的错误反而是"写法不一致"。比如有人加粗喜欢用**，偶尔又用__；列表偶尔用-偶尔用*；标题有时顶格写有时又缩进。这些写法在多数编辑器里都能渲染，但当你更换平台或使用不同解析器时，可能就会产生奇怪的问题。

我的经验是：一套配置用到底。我自己固定的规范是：

• 标题始终用#，并且#后加空格。
• 列表统一用-。
• 加粗统一用**，斜体统一用*。
• 分割线统一用---，但前后必留空行。
• 代码块一律用栅栏式，标明语言。

这样规范的好处是肌肉记忆，写久了不用想，也不会因为混用出现奇怪的边界情况。很多 Markdown 容器还支持格式化工具（如 Prettier 的 markdown 插件），能自动统一这类风格，配合 CI 检查是团队协作的利器。

7.2 在 AI 对话中使用 Markdown 会更高效吗

热搜词里有"对 deepseek 提问是使用自然语言还是 markdown 更容易让 AI 明白指令"，这个问题我确实有体会。对 AI 提问，用 Markdown 来组织复杂指令，效果通常比一大段自然语言更好。

原因很简单：Markdown 能帮你把指令结构化。如果你要 AI 完成一项多步骤任务，用列表列出步骤；如果你要它按固定格式输出，在代码块里给出模板；如果你要和 AI 分享一段代码，正确的做法是放进代码块而不是直接粘贴。Markdown 不是让 AI"更聪明"，而是让它在接收输入时，信息更清晰、歧义更少。

我实际测试过的结果是：给 AI 一段有标题分节、有列表步骤、有代码块的 prompt，它理解任务的速度和准确率明显好于同样内容的一整段自然语言。所以哪怕你只学会 Markdown 的一小部分，用来组织 prompt 都算得上了很实用的进阶用法。

7.3 从 Markdown 到 HTML 的转换思路

有些平台不支持 Markdown 渲染，但支持 HTML。比如微信公众号的编辑器，粘贴 Markdown 源码进去只显示字符，不渲染样式。常见的解决方法是：在 Typora 里把 Markdown 内容导出为 HTML，然后在公众号后台用"富文本粘贴"粘进去，格式基本保留。很多技术写作的人都是这个流程。

有些静态博客系统（如 Hexo、Hugo、VuePress）也自带 Markdown 转 HTML 的引擎，你只管写.md文件，构建时自动生成页面。这也是 Markdown 在个人博客领域如此流行的原因：内容源是简单的纯文本，展示层交给框架处理。理解了这个流程，你就明白为什么 Markdown 不是"过时的格式"，而是目前写作和发布生态中的一个核心枢纽。

8. 从 Markdown 新手到达人的一条学习路径

我花了大量篇幅介绍语法、表格、代码块、进阶功能和编辑器，但如果只记住一句话，那就是：Markdown 的语法本身十分钟就能学完，真正的价值在于用它搭建一套高效的写作工作流。

我给新手的建议路径大概是这样的：先用 Typora 把常用语法过一遍，具体包括标题、加粗斜体、列表、引用、代码块、链接、图片、表格这八大件；然后拿一篇真实文档练手，比如把自己的简历、笔记或项目 README 用 Markdown 重写一遍；接着尝试在不同平台（GitHub、语雀、公众号）发布同一份 Markdown 内容，体会换渲染器的差异；最后再根据自己的工作流，学一点 Pandoc 转换、VS Code 插件、静态博客框架这类周边工具。

在这条路径中，你不需要一开始就记所有语法，用到什么查什么就行。我自己的经验是，基础做多以后，根本不会刻意去"回忆某个语法"，只会条件反射式地打出##表示标题、打出**表示加粗，速度比用鼠标点按钮快非常多。这就是 Markdown 最值得学的地方。