写技术文档这几年我几乎每天都在跟 Markdown 打交道。无论是写项目说明、整理笔记、发博客还是给团队写内部协作文档Markdown 都是我首选的写作格式。它看似简单——几个符号、几行标记却能解决内容排版里最烦人的那批问题字号不统一、样式复制失败、换个平台格式就乱。我见过不少刚接触的人的第一反应是这玩意儿不就是几个 # 和 * 吗有什么好学的。但实际用上一段时间就会发现越基础的东西越值得把细节抠清楚。这一篇我不打算写教科书式的条目汇编而是以一个日常使用者的角度把 Markdown 基础语法里最常用的那部分讲透顺便聊聊哪些地方容易踩坑、为什么这么写、以及怎么根据自己的习惯搭一套顺手的写作流程。如果你正在学 Markdown或者已经用了一段时间但总感觉有些地方不顺手这篇文章会很适合你。内容会覆盖设计思路、核心语法、实操中的各种细节、常见问题排查、还有不同平台的兼容性差异。我不保证讲完全部冷门用法但我可以保证读完你会对标注、嵌套、表格、代码块这些常用操作心里有底写起来不再犹豫。1. 从设计思路说起Markdown 为什么是纯文本聊语法之前我想先说说 Markdown 的底层逻辑。很多人直接上手学符号学会了却总在奇怪的地方卡壳本质上就是没搞懂它为什么要做成现在这个样子。1.1 极简标记专注内容本身Markdown 的核心思想其实特别朴素我写的是一份带标记的纯文本文件而不是一份“排版好的文档”。传统编辑器的做法是你一边输入内容一边定义它的格式——选中文字、点按钮、调字体、改颜色。听起来很直观但实际带来的问题是你的注意力一直被格式牵引真正的内容反而不那么连贯了。Markdown 反过来它把排版需要的信息用几个字符直接写进文本里。想写个大标题就在行首放一个#想让某个词加粗就用两个星号把它包起来。这样做的第一个好处是写作的时候手不需要离开键盘不需要去点任何菜单思路不会被打断。第二个好处更加实际因为它是纯文本你根本不用担心格式会丢。不管把这个文件拿到什么编辑器、什么系统、什么设备上打开内容本身永远都是完整的。1.2 一次编写处处转换我记得最早接触 Markdown 的时候有个疑问光写纯文本怎么转成那种排版精美的页面后来才明白Markdown 的渲染思路其实是“中间层”。你写的是带标记的源文件外面套一层转换引擎就能把它变成 HTML、PDF、Word、微信公众号格式等各种各样的输出。这种思路很像写代码的人常说的一句话数据与展示分离。你用统一的标记语言写好数据展示层可以随时换皮肤。同一个 Markdown 文件放在代码托管平台上是带高亮的源码风格放在笔记软件里是清爽干净的阅读风格放到博客系统里又是完全不一样的主题样式。如果换作传统编辑器输出的文档你得为每个平台重新排版一遍操心字体大小、图片位置、行间距这些工作本身和内容创作毫无关系纯粹是消耗精力。1.3 通用性带来长期价值让我真正坚定用 Markdown 的是它的通用性。我这些年积攒下来的笔记和文档有几百篇中间换过好几款笔记软件、博客平台、协作工具但从来没有遇到过内容迁移的问题。原因很简单Markdown 是纯文本只要有文本编辑器就能打开它有统一的基本约定几乎所有平台都支持解析。而这些约定简单到不可能彻底失效。这其实也解释了为什么很多简历、开源项目说明、技术博客、甚至书的初稿都在用 Markdown。它不是某个独立软件创造出来的私有格式而是一种事实标准用户的选择成本很低转移的代价也极低。所以我建议每个刚开始写作的人不管写的是技术文章还是日常生活记录都可以从 Markdown 入手。它给你的不是一套排版方案而是一种稳定、可靠、能长期跟着你走的写作方式。2. 基础语法拆解每个标记都学明白这一节会进入实用层面。我不打算把语法一条条列完就收工那样的话网上随便找张速查表就够用了。我想在讲每个标记的同时把背后容易忽略的细节、常见误区一并说出来这样你学习的时候能少走一些弯路。2.1 标题注意空格别吞字标题是最高频的语法之一写法是行首加#从一级到六级依次对应 1 到 6 个井号。但这里有个很多人一开始就忽略的点#和标题文字之间要加一个空格。比如# 一级标题 ## 二级标题 ### 三级标题加了空格之后渲染器才明确知道井号是标记符号而不是标题内容的一部分。如果你写#核心功能在部分平台里它可能被识别成标题也可能把#直接当成文字输出表现不一致。这种不一致一旦出现在你交付的文档里结果很难看。标题的层级逻辑也需要提前想清楚。一级标题在一个页面里最好只有一个类似文章总题二级标题是章节三级、四级往下依次细分。不要跳过层级比如从二级直接跳到四级渲染效果虽然不会报错但阅读结构会很乱尤其在生成目录时跳级会导致目录结构断裂。实操里我的习惯是正文常驻二级标题章节内部用三级遇到特殊情况才用四级。这个习惯能保证整篇文档的结构清楚、不过度嵌套。另外标题下面建议空一行再接正文即使不空也能渲染但空一行对 Markdown 源码的可读性非常有帮助尤其是别人拿到你的源文件时一眼能分清结构。2.2 强调语法星号与下划线的差别强调包括加粗、斜体和删除线它们是行内文字排版最常见的需求。加粗是一对双星号或双下划线**加粗文字** __也可以加粗__斜体是单星号或单下划线*斜体文字* _也可以斜体_删除线是用两个波浪号包起来~~删除内容~~这里有一个非常值得说的细节同一种效果星号和下划线几乎是等效的但我的实际推荐是尽量统一使用星号。原因是下划线在英文里有时会和单词本身混淆比如_hello_world_这种形式有些渲染器会把它理解成斜体标记而更多情况下阅读源码时会觉得奇怪。星号没有这种困扰。强调符号里还有一个常见误区符号和文字之间不能有空格。比如** 加粗 **在不少平台上渲染不出来因为前后多了空格解析器会按字面空格看待。正确写法是符号与文字紧贴不加空格。另外嵌套强调时要注意配对顺序比如加粗里面嵌斜体可以写**这是加粗里的 *斜体* 文字**星号的配对是逐层的写反了会漏掉一部分效果。2.3 列表有序和无序的差异与嵌套列表是整理信息的利器分无序列表和有序列表两种。无序列表只要在行首加-、*或后面跟一个空格再接内容例如- 第一项 - 第二项 - 第三项有序列表是数字加英文句点加空格1. 第一步 2. 第二步 3. 第三步这里容易出问题的是两个地方。第一有序列表的数字不需要连续正确。你可以全部写1.渲染时它会自动按顺序递增。这其实是个很实用的技巧因为你在调整条目顺序时不需要手动改序号只要保证条目顺序对就行渲染出来始终是 1、2、3、4。第二列表嵌套需要缩进。子列表要在父列表项下面另起一行并且缩进两个或四个空格具体看平台。嵌套例子- 分类一 - 子项 A - 子项 B - 分类二如果缩进不对子列表会被拍平变成平级条目整个结构的层级感就没了。我踩过不少次这个坑后来养成了一个习惯凡写嵌套列表都会在源码里刻意检查缩进是否整齐。你可能会问为什么非要在源码层面较真因为 Markdown 源码的整洁度决定了后期维护的难度现在嫌检查麻烦以后改结构时更麻烦。2.4 引用多层次嵌套与实用场景引用在 Markdown 里用右尖括号表示通常用于转述他人观点、引用文献片段、或者突出强调某段重要说明。基本写法 这是一个引用块引用块可以嵌套引用块内部再写一个就能嵌套二级引用这在逐层追溯信息来源时非常好用 外层引用 内层引用引用块还可以包含其他元素比如标题、列表、代码块。它们只需要在引用内部按普通 Markdown 语法编写即可。比如 ## 引用内的标题 - 列表条目一 - 列表条目二 这是正文。写引用时要注意每个引用行最好都以开头哪怕中间有空行也要写成空行的形式。有些平台允许“懒写法”即只要段落第一行有后续几行不写也算引用内但换来换去容易出错。我个人的习惯是每行都带一劳永逸。引用还有一个思路上的应用很多人会忽略写教程或提示信息时拿引用块装“注意事项”比用普通段落醒目得多。尤其在一个较长文档里读者快速扫视时眼睛会优先注意到引用块的颜色变化这其实是阅读体验上的一种引导技巧。2.5 链接与图片路径和尺寸都要上心链接的基本语法是[显示文字](目标地址)例如[我的博客](https://example.com)链接可以分为外部链接和相对链接。外部链接指向完整的网址相对链接指向本地文件在写项目说明时非常常用。比如你在文档里引用同目录下的另一份文档可以写[开发指南](docs/guide.md)这样点击时可以直接跳转到该文件。图片语法只比链接多一个感叹号这里我特别想提醒三件事第一替代文字不是随便写的。它用于图片加载失败时显示的文字也是无障碍阅读和搜索引擎识别图片内容的依据。认真的文档里替代文字应当简明描述图片内容像“登录页面截图”“架构图”这样而不是空着或写一串乱码。第二相对路径的写法要非常小心。如果你用 Markdown 写项目文档并存放图片推荐在项目里建一个assets或images文件夹文中引用时使用相对路径比如。如果直接用绝对路径文档从一台电脑拷到另一台电脑时图片就全部失效。你也不能依赖网络图床链接外部链接一旦失效文档里就是一堆碎图。第三Markdown 原生的图片语法不支持设置宽度、高度、居中。想调图片尺寸常用的方案是直接使用 HTML 的img标签像这样img srcassets/screenshot.png width60% /几乎所有的 Markdown 渲染器都允许混入 HTML。这个特性在普通文本里用得少但在写正式文档时用处不小我们后面还会专门聊。2.6 表格注意管道符与对齐表格是 Markdown 基础语法里最“有脾气”的一部分。它用管道符|分隔列用一行短横线作为表头与内容的分隔行。基础写法| 功能 | 快捷键 | 适用场景 | | ---- | :---: | -------: | | 加粗 | CtrlB | 强调重点 | | 斜体 | CtrlI | 引入名词 | | 删除线 | ~~ | 标记废弃 |第二行| ---- |是分隔行它还承担着对齐方式的任务。冒号在左边表示左对齐两边都有冒号表示居中冒号在右边表示右对齐。上面的示例里“功能”没有冒号即默认左对齐“快捷键”是居中“适用场景”是右对齐。表格最容易踩的坑是管道符周围的空格。Markdown 解析表格时依赖管道符来区分列所以每一行管道符数量必须相同。如果你某一行少了一个管道符整个表格就会渲染异常有时甚至会导致后续内容全部变成表格的一部分乱成一团。我见过不少人为了美观把表格里的内容用大量空格对齐。这种美化其实完全没有必要因为渲染出来看的是最终表格源码里的空格只是辅助解析的渲染器会自动忽略多余的空白。与其花时间对齐源码不如保证每一行管道符数量一致内容紧贴管道符即可。2.7 分割线三个符号的安全写法分割线用三个或以上的-、*、_独行书写即可--- *** ___这里有一个老手才知道的坑---不光是分割线它还有可能是二级标题的另一种写法。在 Markdown 里任何一段文字下面紧跟一行---都会被解析成二级标题。比如我的标题 ---这样写的后果是“我的标题”会被渲染成二级标题而不是正文上方的分割线。想避免这种歧义可以在分割线上下都保留空行并且尽量让分割线前后不要紧贴着正文段落。最稳妥的做法是分割线单独成段和上下文都隔一个空行。很多编辑器在你写---后会自动补出空行就是在规避这个问题。3. 代码与代码块写技术内容的必备姿势如果一定要我选出 Markdown 语法里最值钱的一部分我可能会把票投给代码相关的语法。它让 Markdown 成了写技术文档的标准语言。3.1 行内代码反引号的配对魔法行内代码用于在普通句子中提到变量名、函数名、命令等。用单个反引号包住内容即可这里需要执行 git commit 命令。行内代码的样式通常是等宽字体加底色和正文有明显区分。它和普通文字最大的区别是内部的符号不会被当作 Markdown 语法解析。比如你想在文章里写*不重要*如果直接放在正文里会把文字变成斜体如果放在反引号里就能原样输出星号和文字。但反引号本身也有一个坑如果内容里恰好需要用到反引号怎么办比如你想在文章里写“使用 符号表示行内代码”这时候外层包裹的反引号会和内层反引号冲突。解决办法是加长边界反引号用两个反引号包裹一个反引号例如 这个是反引号同理内容里如果有两个连续反引号外层就可以用三个。理解了边界加长的思路这部分就不难了。3.2 围栏代码块别忘记标注语言多行代码块使用三个反引号包裹也可以使用三个波浪号。前一种写法更常见也是我的首选。围栏代码块最大的优势是可以指定编程语言让渲染器做语法高亮function hello() { console.log(Hello, Markdown!); }围栏代码块是一把双刃剑高度灵活但也容易出错。最常见的错误是忘记关闭三个反引号结果后面的所有内容全部被当成了代码直到下一个三个反引号出现代码块才结束。这种错误的特征是排版突然变成等宽字体、所有 Markdown 标记全部失效。排查时只要上下找找漏掉的那行围栏就行。另一个常见问题是语言标注写错。不写语言标注并不影响渲染但会失去高亮阅读体验差一截。标注语言时用规范的小写名称比如javascript、python、bash、json不同平台支持的语法高亮器略有差异但通用名基本都能识别。3.3 缩进代码块老式写法的优缺点除了围栏代码块还有一种更原始的方式每行前缩进四个空格或一个制表符。这是一个缩进代码块 内容放在四个空格之后 第二行也在缩进里这种写法的优点是简洁缺点也很明显无法指定语言高亮在列表里很难控制缩进层级。如果你在列表项里需要再放代码块缩进会变得层层叠叠极易出错。所以现在的主流平台几乎都不再推荐这种写法了但你在阅读老文档时还是可能会遇到需要知道它是什么。我的原则很简单能用围栏代码块就不用缩进代码块尤其是写正式文档时可读性和高亮效果都明显更好。4. 搭建日常写作流程编辑、渲染与管理学会了标记语法之后真正决定效率的是工作流。不会用工具语法学得再熟也白搭。这一节我会讲讲怎么围绕 Markdown 搭建一套顺手的工作流包括编辑器选择、图片管理、目录生成和版本沉淀。4.1 编辑器选择思路市面上的 Markdown 编辑器很多各有偏向但选择时主要看三条编辑体验、渲染预览、扩展能力。如果你追求所见即所得可以选那些“实时渲染”型的编辑器左侧是源码右侧是渲染预览也有的编辑器直接输入即渲染光标所在行显示源码其他行显示效果。这类编辑器对新手很友好犯错时会立刻看到异常效果调试起来快。如果你更喜欢代码风格可以考虑用代码编辑器加 Markdown 插件的方式。这样做的优势是你只需要熟悉一个编辑器就够不用在多个工具之间切来切去而且代码编辑器里的 Git 集成、文件树、全局搜索等能力都很成熟对管理一大套文档非常顺手。如果你是重度笔记用户那就直接选一款笔记软件。它们通常自带云同步、全文检索、标签体系这些功能对写零散知识记录很有帮助。不管选哪类我都建议你一定试一下它的导出能力有的工具导出 PDF 时样式混乱有的导出图片会丢相对路径这些问题在选定工作流之前发现比等到交付文档时才措手不及要好得多。4.2 图片文件管理方案图片是文档里最容易出问题的一环。我早期写文档时喜欢直接把图片拖进编辑器编辑器会自动生成一份本地文件但目录结构一团糟图片名字也是随机生成的根本看不出哪张图对应哪段内容。后来我固定了一套方案每个项目建立独立的目录如assets/图片命名要有语义比如login-dialog-error.png文中引用一律使用相对路径如同一项目内所有相对路径以项目根目录为基准文件夹移动时同步调整这套办法看起来很简单但它解决了一个真实痛点项目变多以后你不需要打开图片看内容光看文件名和引用位置就能知道文档在说什么。对协同伙伴来讲也友好他们拿到整个项目文件夹打开文档时所有图片都能正常显示不需要额外问路径。4.3 生成目录和锚点跳转有些写作场景要求开头有个目录结构尤其是长文档。Markdown 生成目录有两种方式自动和手动。自动目录由渲染器提供一般在文档中插入一个占位标记渲染时自动扫描所有标题生成目录。这种方式适合平台和工具支持能力强的场景改标题后目录会跟着更新几乎不用维护。手动目录是手写的链接列表指向各标题的锚点。Markdown 渲染 HTML 时标题会自带锚点链接到锚点的方法在 2.5 节提过[文字](#链接目标)。不过不同平台对中文锚点的处理策略不同有的自动转拼音有的保留中文有的忽略大小写和空格。手写锚点时最稳的做法是先去预览页面里复制实际生成的锚点地址拿来直接用不要凭想象写。我个人更倾向于自动生成目录。原因很直白文档经常要改标题手写目录表同步更新很容易遗漏而自动目录不会出这种问题。维护成本低出错率低长期看一定更划算。4.4 配合版本管理沉淀资产最后想提一下版本管理。如果你写的是项目文档强烈建议把 Markdown 文档目录一起纳入版本管理。这样每次改动都有记录时间久了可以回溯也可以对比不同版本之间内容的变化。Markdown 是纯文本差异对比非常清晰哪个词被改了、哪一段被删了都历历在目。这个习惯在合作场景下价值更大。几个人同时维护一份文档版本合并的冲突提示非常直观Markdown 不像二进制文件那样需要专业工具才能解析直接用文本对比工具就能解决大部分冲突。我讲一个真实的体会曾经有一次合作者改完文档后不小心删掉了一整节内容但因为文档在版本管理里几分钟就找回了旧版本避免了返工。5. 常见问题与排查技巧实录很多人学完语法就开始写但写着写着会遇到各种奇怪的现象感觉好像哪儿都不对。这一节我把实际使用里最常遇到的问题和排查思路整理成速查式的列表你遇到类似情况时可以直接对照。5.1 换行不生效这是被问得最多的问题。很多新手在 Markdown 里写完一段后直接按一次回车渲染出来发现和上一段挤在一起。原因在于Markdown 中单个换行符在大多数平台上会被当作普通空格处理只有空一行才能表示段落换行。这是一个历史遗留约定但今天几乎所有主流渲染器都会这样处理。解决办法有三个段落之间空一行在行尾加两个空格再换行或者直接使用 HTML 的br标签。我最推荐的是空一行它语义最清晰源码也更整洁。行尾加空格是个隐藏技巧肉眼几乎看不出来在编辑文档时容易造成误解。br适合不想分段、只想强制断行的情况但尽量少用因为它会破坏纯文本的可读性。5.2 表格错乱表格渲染异常十有八九是管道符数量不统一。当你看到表格几行单元格错位、多出一列或者直接漏掉内容时先逐行数管道符。管道符数量一致是对齐的底线。另一个坑是表头分隔行缺失。没有第二行| --- |渲染器就不会把后续内容当表格而是当普通段落文字处理。有些新手以为只要用管道符分隔了内容就能自动生成表格其实不对表头分隔行才是触发表格渲染的开关。5.3 列表里嵌代码块失效在列表项里放代码块缩进层级是一个大坑。列表项后面的内容要缩进到和列表内容相同的层级否则会被拍平成列表外的内容。最典型的场景- 第一项 python print(hello)这里的代码块前面直接缩进两个空格是配合列表项内容对齐的。如果你把代码块顶格写渲染时代码块会直接跳出列表位置错乱。我的建议是遇到复杂列表内嵌代码的情况优先考虑把代码块和列表拆开各自独立成块。形式上的嵌套好看但维护起来很容易出问题。文档的第一要务是内容清晰而不是源码精美。 ### 5.4 图片要么不变大要么不居中 图片占不满宽度、没法居中是另一个高频问题。原生 Markdown 图片语法不提供尺寸和位置控制这在写正式文档时尤为头疼。多数平台的渲染器会保留图片原始尺寸除非你在图片地址后跟了尺寸设置但不同平台的扩展语法格式不一通用性很差。 我的做法是直接用 HTML 的 img 标签代替。虽然它带一点样式味道但几乎所有接近完整的渲染引擎都支持。写正式文档时图片宽度设置为 100% 是相当常见的处理方式它能保证图片在不同屏幕宽度下自适应不会被原始分辨率限制。 另外要注意HTML 标签在 Markdown 里只写一行前后不要有多余空行否则某些严格模式下的渲染器会把 HTML 标签单独识别为段落块导致布局出现意外空白。 ### 5.5 不同平台显示效果不一样 同一个 Markdown 文件在编辑器和博客平台上的渲染效果可能天差地别。原因在于并不存在一个官方权威的 Markdown 规范各家实现都是在一个共同子集上做扩展。兼容性问题的根源在这里。 我的经验是优先写“通用子集”语法也就是绝大多数渲染器都能正确解析的那部分。遇到漂亮的扩展语法时先想清楚这份文档只在当前平台看还是以后可能迁移如果要迁移扩展语法能不用就不用。进阶用法在交付外部文档时尤其要克制。 还有一个很实用的小技巧发布前在至少两款不同的渲染器里预览一遍。如果两款都能正常渲染基本就不会出大问题。如果只有一款正常赶紧找出问题源头的语法不要等到读者反馈才发现。 ## 6. 用 Markdown 写作的长期习惯 写了这么久我对 Markdown 最深的体会是它没有绑定任何一家公司的生态也没有特定的软件限制。它的形态极其简单以至于几乎不可能被淘汰。我刚接触时觉得这不过是给技术人员准备的排版工具后来慢慢发现它其实在改变写作习惯本身——你开始把注意力放在结构和内容上而不是让格式牵着鼻子走。 如果现在让我给刚开始用 Markdown 的人提一个建议我不会推荐某款编辑器也不会上来就布置一堆高级语法任务而是建议从今天开始找一篇你最近要写的文档强迫自己用 Markdown 写完整。第一次肯定会不习惯会频繁查看语法会忘记空行会把表格写散架。这些都是正常的写两三篇之后就会顺畅起来。到那时候你再回头看传统排版工具会很自然地明白为什么这么多人离不开它。 至于进阶方向等你基础牢固了可以试试模板化写作、主题样式定制、甚至自己写一个小脚本批量转换文档。但这些都是后话。先把 # 和 * 这些最基础的符号用顺比什么技巧都重要。
