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 或 yamlAPI 返回数据用 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 的主力功能比如对比参数、整理清单、列时间计划都靠它。表格语法由表头、分隔行和数据行组成功能名称语法示例适用场景加粗文字强调关键词斜体文字补充说明删除线~~文字~~标注废弃内容关键点 - 分隔行是由 - 组成的那一行必须有它把表头和数据区分开。 - 每一列之间用 | 分隔表头和数据行的列数要对应。 - 左右两侧的 | 可以省略但视觉上容易乱建议都写上这样结构更清晰。 - 表格中单元格内文本默认左对齐。如果想指定对齐方式可以在分隔行里写冒号--- 左对齐:---: 居中---: 右对齐。 对齐示例左对齐居中右对齐123表格里的坑主要在竖线字符本身如果单元格内容里需要显示 |必须用 \| 转义否则表格会多出一列。比如管道符转义写法竖线|另一个常见问题是有些编辑器里表格前后需要留空行否则表格会粘进段落导致渲染异常。写表格时我会习惯性地前后各空一行这样在几乎任何解析器里都不会出问题。 ### 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_{i0}^{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 解决的绝不用 HTMLMarkdown 解决不了比如精确控图再动手写 HTML。还有一个提醒在代码块里写 HTML代码块的原样特性会让它不参与 Markdown 解析所以如果你想展示 HTML 语法本身记得把示例放进反引号代码块里。6. 编辑器选择与工作流搭建6.1 主流 Markdown 编辑器怎么选市面上的 Markdown 编辑器很多我按使用场景简单分个类编辑器特点适合场景Typora所见即所得输入符号后立即渲染界面极简本地写作、博客初稿、适合新手VS Code Markdown 插件功能强大插件生态丰富实时预览程序员、技术文档、和代码库共库管理Obsidian双链笔记本地 Markdown 存储知识管理、个人笔记、长文写作语雀 / 飞书文档在线协作Markdown 粘贴支持良好团队协作、在线文档GitHub / GitLab内置 Markdown 渲染天然适合 README 和 Issue开源项目、代码托管平台如果是零基础我最推荐先试 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 最值得学的地方。 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 或 yamlAPI 返回数据用 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 的主力功能比如对比参数、整理清单、列时间计划都靠它。表格语法由表头、分隔行和数据行组成功能名称语法示例适用场景加粗文字强调关键词斜体文字补充说明删除线~~文字~~标注废弃内容关键点 - 分隔行是由 - 组成的那一行必须有它把表头和数据区分开。 - 每一列之间用 | 分隔表头和数据行的列数要对应。 - 左右两侧的 | 可以省略但视觉上容易乱建议都写上这样结构更清晰。 - 表格中单元格内文本默认左对齐。如果想指定对齐方式可以在分隔行里写冒号--- 左对齐:---: 居中---: 右对齐。 对齐示例左对齐居中右对齐123表格里的坑主要在竖线字符本身如果单元格内容里需要显示 |必须用 \| 转义否则表格会多出一列。比如管道符转义写法竖线|另一个常见问题是有些编辑器里表格前后需要留空行否则表格会粘进段落导致渲染异常。写表格时我会习惯性地前后各空一行这样在几乎任何解析器里都不会出问题。 ### 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_{i0}^{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 解决的绝不用 HTMLMarkdown 解决不了比如精确控图再动手写 HTML。还有一个提醒在代码块里写 HTML代码块的原样特性会让它不参与 Markdown 解析所以如果你想展示 HTML 语法本身记得把示例放进反引号代码块里。6. 编辑器选择与工作流搭建6.1 主流 Markdown 编辑器怎么选市面上的 Markdown 编辑器很多我按使用场景简单分个类编辑器特点适合场景Typora所见即所得输入符号后立即渲染界面极简本地写作、博客初稿、适合新手VS Code Markdown 插件功能强大插件生态丰富实时预览程序员、技术文档、和代码库共库管理Obsidian双链笔记本地 Markdown 存储知识管理、个人笔记、长文写作语雀 / 飞书文档在线协作Markdown 粘贴支持良好团队协作、在线文档GitHub / GitLab内置 Markdown 渲染天然适合 README 和 Issue开源项目、代码托管平台如果是零基础我最推荐先试 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 最值得学的地方。