说实话，我每次收到别人发来的 Markdown 文件，基本上扫一眼的前十秒，心里就已经给这个人定了性：文档是随手写的，还是认真整理过的。Markdown 的门槛低到近乎没有门槛，但正因为人人都能上手，它排出来的版式才最能暴露一个人的工作习惯。你可以在 Typora 里看到一个高亮得五彩斑斓、标题层级乱跳、表格列宽挤成一团的文档，也可以在 GitHub 上遇到一个只用纯文本就让人读得行云流水的 README。这个差距根本不在于有没有天赋，而在于有没有把排版这件事当成工程来做。
这篇东西我不想讲枯燥的语法手册，那些官方文档和教程里有的是。我想聊的是“Markdown 排版该有的样子”——一个我在无数项目文档、技术博客、团队 Wiki 和个人笔记里反复琢磨之后，真正沉淀下来的判断标准与实操套路：什么时候用标题、表格怎么写才不会裂、图片路径怎么设计才能经得起换电脑和换仓库、导出 PDF 和 Word 时怎么保排版不崩、以及和 AI 协作生成内容时怎么让它别把格式搞得乱七八糟。这篇适合所有想把文档写出“高级感”的人，无论你是刚开始接触 Markdown 的纯新手，还是写了多年文档但总觉得哪里不对的老手，都能从这里找到一些可以直接抄作业的东西。
1. 排版先想明白：Markdown 的体面来自语义，不来自样式
先说一个我观察到的普遍误区：很多人一提到排版，第一反应就是“我要让标题变成红色”“我要把这段字放大加粗”。这是典型的用 Word 思维去写 Markdown。Markdown 从设计之初就是一个“面向语义”的轻量标记语言——它让你标记的是“这段文字是什么”，而不是“这段文字长什么样”。所以 Markdown 排版该有的样子，第一条就是要克制住调字体、调颜色的冲动。
1.1 不要用 HTML 思维写 Markdown：字体、颜色不是排版核心
确实，Markdown 兼容内联 HTML，你可以在文档里写<font color="red">警告</font>，也可以塞一个<div style="...">进去。从语法上讲，它们没有错，渲染器也会乖乖执行。但从排版上讲，这是最不应该养成的习惯。原因有三个：
第一，可移植性被毁掉了。你的文档今天在 Typora 里打开，明天可能被扔进 GitHub、语雀、Notion、Hugo 静态站或者某个 CI 工具里渲染成网页。每个平台的 HTML 过滤规则都不一样，<font color>这种标签在有些渲染器里直接被忽略，在某些在线编辑器里甚至会触发安全拦截。今天你在自己电脑上看到的“红色警告”，换一个平台就成了纯文本或者干脆消失。
第二，维护成本变高。一份 5000 字的文档里如果加了 80 处手动调色，哪一天你想统一把“警告”改成别的颜色，就得全局搜索替换，而 Markdown 的语义标记解决方案比这种方案优雅得多——用引用块>标记警告，用加粗**标记关键词，渲染出来的样式由主题统一决定。你要换主题，全局变样，不用改正文。
第三，它掩盖了真正的结构问题。当有人忍不住去调字体字号的时候，通常意味着他内心清楚“这段内容在层级上说不清楚”，但选择了用视觉样式去硬拗。好的排版不是这样解决问题的，而是回头去看：这个地方是不是该拆成二级标题？是不是该单独拉出一个列表？是不是该转换角色变成引用块？
1.2 标题即骨架：正确的层级比什么都重要
一个 Markdown 文档的排版气质，80% 由标题层级决定。我看过太多文档有这种问题：##和###层级含义完全随缘，同一层级的章节长度差出十倍，#的编号全靠手写，一插队后面的数字全部要改。这些毛病的根子在于，写的时候没有把标题当成内容结构的映射工具，只把它当成“这一段的字号大一点”的手段。
一个我认为值得长期坚持的规范是：一级标题只出现一次，它就是文档标题；二级标题是核心章节；三级及以下才是子章节。层级深度控制到三级就够了，四层五层的标题阅读体验极差，如果发现自己写到####停不下来，大概率不是内容太复杂，而是某个章节没有拆成独立文档。每级标题缩进数量与信息层级的一致性，才是 Markdown 排版的“骨架美感”。
另外必须提一个很多人忽略的问题：自动编号。不要自己手写“1.1”“2.3”这种前缀。GitHub、VSCode 插件、Typora 的外置主题、静态站工具大多支持通过 CSS 或插件为标题自动编号。手写编号的最大问题在于改动成本：你在第二章后面插入一个新的一级章节，后面所有章节编号全部要推倒重来。用自动编号，你只负责调整标题层级，编号永远不出错。我自己大概在两年前彻底戒掉了手写编号的习惯，那之后文档改结构的心理负担小了很多。
1.3 列表、引用、代码块：什么时候用，比怎么用更值得想
很多人的排版混乱，不是语法不会，而是“语义边界”不清。具体表现包括：把并列关系的事实写成一坨长段落，把需要强调的单一重点用列表列出来，把流程步骤写成无序列表，把一次性说明的事件又用有序列表编号——全都是只有形式、没有逻辑的排布。
我的实操经验是建立这样一套默认判断契约：
- 无序列表：罗列不需要强调先后顺序的东西，比如功能清单、支持平台、注意事项。它的阅读节奏是“扫读”，每项应该尽量短。
- 有序列表：强顺序的动作序列，比如“第一步……第二步……第三步”。注意，如果步骤超过 10 步，就该考虑拆成多个分环节的二级标题，而不是继续拉长列表。
- 引用块：专门用来放次要信息、注脚式解释、警示语。引用块内部不需要再嵌套列表，嵌套之后渲染效果九成是乱的。
- 代码块：只放代码、配置、命令输出。一个常见灾难是把命令执行结果也扔进代码块，然后又想在结果里做高亮，搞出了一堆行内
**加粗，渲染出来满屏都是星号，非常难看。
Mermaid 图表我也提一嘴。现在很多 Markdown 渲染器支持 Mermaid 画流程图和时序图，这确实好用。但请记住：Mermaid 代码块仍然属于代码块，你要标注语言类型```mermaid，并且不要在里面做过于复杂的节点嵌套，否则换一个渲染器，图就罢工了。
1.4 链接与图片的“礼仪”：来源可见、路径可靠
链接的排版礼仪有三条。第一，优先写带文字描述的链接，不要直接甩一个超长 URL 糊在正文里，既难看又干扰阅读节奏。第二，重复出现的链接可以用 Markdown 的引用式链接语法，在文末统一维护 URL，正文保持清爽。第三，外部链接要有预期交代——告诉读者点出去会发生什么，是官方文档、维基百科还是别人的博客。
图片的排版规则更严格：正文里每一个图片都要有相对路径意识，这个放到第二章详细说。这里只说一条：一张图如果在文档中被反复引用，尽量把它和文档放在同一个相对路径体系下，不要用C:\Users\xxx\Desktop\这种绝对路径，不然文档换台机器就瘫了。你写的不是备忘录，是可以被复现、被传播的 Markdown 资产。
2. 最影响观感的四个细节：换行、表格、图片路径、数学公式
如果标题层级决定文档的骨架，那么换行、表格、图片和公式就是文档的皮肉。这四个细节恰恰是“Markdown 排版该有的样子”里最容易被忽略、却最肉眼可见的部分。我一个个来说，都是亲眼见过无数人反复踩的坑。
2.1 换行这门“玄学”：为什么搜索引擎天天有人问
“markdown 换行”能长期霸占热搜，核心原因就是：普通人的直觉在这里不成立。在绝大多数文本编辑器里，你按一次回车，视觉上确实另起了一行，但 Markdown 渲染后会把它当成同一个段落里的软换行——很多渲染器里它显示为空格甚至被忽略。要让渲染结果真正另起一段，必须按两次回车，在源码里留下一个空行。
这个规矩为什么坑人？因为本地编辑器的所见即所得模式太“贴心”了：Typora 编辑态下你按一次回车，它渲染出来的就是换行，于是你以为没问题，结果同一份文件推到 GitHub 上，所有换行全黏在一起，段落挤成一大块，瞬间崩溃。这是“编辑器渲染结果”和“标准 Markdown 语义”之间的认知错位，几乎每个月都会有人因此发帖求助。
我的建议是：默认就按两次回车分段，一次回车的软换行只在特殊场景使用，比如地址格式、诗歌、中英文混排需要强制断行的表格单元格内。想用软换行的标准写法是行尾加两个空格再回车，但很多人在输出时看不到空格，容易漏，所以我一般直接建议用空行法，简单粗暴不容易错。如果你用 VSCode，可以装一个显示空格和回车的插件，源码里有没有多余空格一目了然，比事后猜靠谱得多。
2.2 表格：对齐的是语义，转义的是竖线
Markdown 表格是很多人爱用但用不好的东西。它语法简单，写出来却最容易曝光排版功力。先说最基础的正确姿势：管道符|两侧要不要空格，其实不同渲染器表现略有差异，但为了兼容性和美观，我统一在内容两侧留一个空格。表头分隔行写成| --- | --- |，可以加冒号控制对齐方式，:---表示左对齐，---:表示右对齐，:---:表示居中。分隔行必须和表头列数完全一致，少一列，整张表格直接渲染失败。
第二个坑是单元格内容里的竖线。比如你在表格里写“快捷键Ctrl + |”，这个竖线会被解析成列分隔符，表格当场裂开。正确做法是用转义符：在前面加反斜杠，写成\|。更麻烦的情况是单元格里要放代码或小片段，建议把内容里的竖线统一转义，再用行内代码包起来，这样渲染最稳定。
第三个坑是长文本表格。Excel 表格天然适合宽数据，但 Markdown 表格遇到大段文字时展示效果很差：列宽、自动换行全看渲染器心情。很多人在文档里塞一个“字段说明”表，最后一列全是两百字的长描述，渲染出来像一堵墙。我的经验是，单格内容超过 30 个字，就该考虑把内容拆出来，只用表格做索引，长描述放到表格下方的段落或列表里。这比硬凹表格要体面得多。
还有网友常问“markdown 表格复制”或者“markdown 表格转换 excel”。如果你要把表格搬进 Excel，直接用 Pandoc 转成 .xlsx 是最稳的（第三章会细说），但如果是临时应付，可以先把表格渲染成 HTML，再用浏览器打开复制进 Excel，保留结构的同时也能减少格式错乱。反过来，从 Excel 复制表格进 Markdown，网上有现成的在线转换工具，但务必检查列数和转义，Excel 里的换行符进入 Markdown 表格后非常容易破坏结构，这是转换后第一要检查的东西。
2.3 图片路径：本地能用、换台电脑就裂
图片可以说是 Markdown 排版里的“重灾区”。最常见的对话场景是这样的：A 同事用 Typora 写文档，拖拽图片进来，Typora 自动生成了类似的绝对路径，看起来一切正常。文档发到群里，B 同事打开一看，图片全挂着裂开的图标，因为 B 的电脑上根本没有C:\Users\A\Pictures这个目录。
所以路径设计的核心原则是：文档里所有资源都能跟着文档走。我的标准做法是：在主文档同级目录建立一个assets或images文件夹，所有图片放进这个文件夹，文档里统一用相对路径引用，比如。这样整个文档目录打包，发给谁都一样能看；推到 Git 仓库里，别人 clone 下来图也不会挂。如果文档目录层级较深，每级标题一个资源子目录，如docs/chapter2/assets/，这样还能避免大量图片堆在一个文件夹里分不清谁是谁。
还有一个细节很多人不知道：GitHub 渲染 Markdown 图片时对路径大小写敏感。你在 Windows 本地文件名是Architecture.PNG，但文档里写的是architecture.png，Windows 下 Typora 能显示，推到 GitHub 上就裂了。所以我现在的习惯是图片文件全部小写命名，用连字符分隔多个单词，比如project-architecture.png。这算是“排版该有的样子”里很小但很专业的细节。
图片尺寸也是排版的一部分。Markdown 原生语法不支持指定宽高，但很多渲染器支持{: width="600px"}这类扩展写法，或者直接使用 HTML 的<img width="600" src="...">。我的建议是：正文里的插图尽量控制宽度，不要让一张 4000px 的截图把版面撑爆。如果是截长图，先裁剪一下再放进来，这对整体排版观感有着立竿见影的提升。
2.4 数学公式：行内还是块级，取决于渲染器
如果你写的是技术文档、AI 相关笔记或者学术类内容，数学公式几乎逃不掉。Markdown 社区对数学公式的默认约定是 LaTeX 语法：行内公式用$...$，块级公式用$$...$$。但请小心，这个约定并不是所有 Markdown 渲染器的默认行为。
比如 GitHub 的 Markdown 引擎已经原生支持数学公式渲染，但很多老旧的本地编辑器和在线工具还需要额外开启扩展选项，或者压根不支持。我在 VSCode 里写公式时，通常要确认 Markdown 插件的“数学公式”开关已经打开，否则$x^2$到编译后就是一段普通文本，满屏美元符号，非常影响阅读。
排版上更讲究的是公式缩进和编号。块级公式最好单独占一个段落，前后留空行，不要跟正文挤在一起。如果公式需要编号，优先使用$$ e^{i\pi} + 1 = 0 \tag{1} $$这种内嵌编号写法，而不是手动在公式后面打一个(1)，因为手动编号在渲染器里对不齐，看着很业余。公式内如果需要换取行，用\\，但要注意并非所有渲染器都支持这一点，写完公式务必在目标平台跑一遍。
3. 从写好到交付：编辑器选型、PDF 导出与格式转换的完整链路
Markdown 排版这件事，不止取决于你在编辑器里看到的那个画面，更取决于文档交付出去时的样子。我见过太多人兴奋地写完 Markdown，然后倒在了导出 PDF 和转换 Word 的路上。这一章我把整条链路讲清楚。
3.1 编辑器不是越贵越好：Typora、VSCode 与开源替代怎么选
“markdown 下载”和“typora下载 安装教程”长期是热搜词，说明编辑器选型确实是新手第一道坎。我个人的判断框架是这样：先看你的核心场景，再看编辑器特性，最后才决定用哪款。
如果你只想要所见即所得的书写体验，Typora 确实是最舒服的选项之一，界面干净、图片拖拽即用、中英文排版渲染也漂亮。但它现在已经是付费软件，我不建议去找什么破解版——风险太大，而且没必要，因为开源免费领域的替代品已经做得相当好，比如 Mark Text 和 Obsidian。Obsidian 更是支持双向链接和知识库管理，适合长期积累笔记的人。
如果你是开发者，或者经常要和 Git、代码一起工作，那 VSCode 几乎是绕不开的选择。VSCode 里写 Markdown 的体验和 Typora 完全不同：它默认显示源码，排版的美感要靠预览面板来确认，但换来的是极强扩展性和与 Git 的无缝整合。我的日常组合是 VSCode 加 Markdown Preview Enhanced 插件，这个插件支持预览、导出、画图等多种功能，基本能满足我八成的文档工作。
我的建议是不要在一个编辑器上吊死。写博客、写论文类文档我倾向 Typora 或 Obsidian，写技术方案、项目说明我肯定用 VSCode。编辑器是排版链路的第一环，你选哪把“刀”，直接影响后面能不能切出漂亮的菜。
3.2 VSCode 导 PDF 的原理：为什么总提到 PrinceXML
每次有人问“VSCode 如何把 Markdown 导出为 PDF”，就会有人回答“需要下载 PrinceXML”，然后新手就懵了：我导出个 PDF 为什么要装这么个东西？其实这不是某个插件的奇葩依赖，而是把 Markdown 转 PDF 的基本架构决定的。
Markdown 本身不是排版语言，渲染器通常是先把 Markdown 解析成 HTML，再把 HTML 打印成 PDF。浏览器的打印功能可以做这件事，但控制力不够——页眉页脚、页边距、字体嵌入、分页规则都很难精细管理。PrinceXML 就是专门干这个的一个 HTML/CSS 转 PDF 引擎，很多 Markdown 预览插件（比如 Markdown Preview Enhanced）把它作为后端来调用，从而实现“所见即所得”质量极高的 PDF 输出。
所以在 VSCode 里导 PDF 的完整链路是：Markdown → 渲染成 HTML → 套用 CSS 排版样式 → 调用 PrinceXML 等引擎 → 生成带样式的 PDF。如果只是临时导出，不装 PrinceXML 也能用，但你会发现样式丢失、中文支持差、代码块换行乱等问题，那时候就明白为什么要装它了。安装之后的路径配置也是个坑：插件默认查找系统 PATH，如果你装的是 Windows 便携版，可能需要在插件配置里手动指定可执行文件路径。
导出 PDF 时的排版细节同样重要。我一般会在文档开头用 YAML front matter 写title和author，这样导出的 PDF 会自动带上标题信息。代码块建议设置line-numbers以便阅读，长代码块一定要确认自动换行已开启，否则横向滚动条会毁掉整体排版的平衡感。
3.3 Pandoc 一条命令：Markdown 和 Word、PDF 之间的体面往返
Pandoc 是我在所有 Markdown 工具里最敬重的一个。它自称“文档转换瑞士军刀”，实际上比瑞士军刀还猛：Markdown 转 Word、PDF、HTML、EPUB、LaTeX，以及反方向从 Word/PDF 等格式提取内容，它都支持得很不错。而“Markdown 转 Word 工作流”之所以是热搜词，核心原因就是大家想用一个可靠的方法打通 Markdown 和 Word 这两套生态。
转换 Word 的基本命令我很常用：
pandoc input.md -o output.docx听起来简单，但要让转出来的 Word 有排版的样子，你得用引用文档。Pandoc 允许你先通过-o custom-reference.docx生成一个参考文档，然后在 Word 里把它改造成你想要的样式——设置标题字体、正文字号、页边距等——再用这个改造后的 docx 作为后续转换的模板：
pandoc input.md --reference-doc=custom-reference.docx -o output.docx这样出来的 Word 文档基本能省掉大半后期手工调格式的时间。表格会转成 Word 原生表格，图片会导入到对应位置，标题层级和样式也一一对应。这已经是我目前主力使用的文档交付方案：源码写 Markdown，发布给协作方时转成 Word。
拿 Pandoc 从 Markdown 转 PDF 则更复杂一些，因为默认支持 LaTeX 引擎，而中文用户经常栽在中文支持上。我的经验是用 XeLaTeX 加中文字体设置，或者走“Markdown → HTML → PDF”路线，后者用 CSS 控制样式更直观。两条路都需要预装工具链，建议拿到一台新电脑时先把 Pandoc、PrinceXML、基础字体这三件套安装好配好，后面就不用再折腾了。
3.4 反方向转换：PDF、Word 回 Markdown，开源方案走到哪一步了
转换不止是单向的。这几年“任何格式转换为 markdown 开源项目”的呼声特别高，原因就是大家想把历史积累的 Word 和 PDF 文档统一转入 Markdown 工作流管理。反方向转换比正向难不少，因为要解决“布局识别”和“结构化重建”两个核心问题。
Pandoc 可以处理 Word 转 Markdown，效果尚可：标题、列表、表格能基本还原，但前提是源 Word 排版规整。遇到各种手动空格、文本框、缩进奇葩的 Word 文档，输出就会比较碎。
PDF 转 Markdown 是更难的问题，传统工具里pdftotext只能提取纯文本，排版信息几乎全丢。现在开源领域的两条技术路线值得关注：一类是基于规则和视觉模型结合的转换工具（比如 Marker，它能识别标题、表格、公式在页面上的位置，输出结构较完整的 Markdown），另一类是大语言模型方案，让模型读 PDF 截图或文本后直接输出 Markdown。后者的优势是理解能力强，但速度慢，且长文档容易丢失信息。我实测下来，扫描版 PDF 必须走 OCR 路线，纯文字版 PDF 用传统规则工具更快，表格密集的 PDF 则适合视觉模型类方案。
提醒一句：无论哪个开源项目，转完之后的审校都必不可少。公式的上下标、表格里被压掉的多余字符、代码块中的缩进，都是转换中最容易出错的点。把“转换后必须人工校对”当成工作流的一环，才算真正把格式转换这件事用稳了。
3.5 AI 翻译保持排版：为什么 Markdown 这么适合机器处理
“AI 翻译保持原有排版的原理”这个话题在热词里出现得挺妙。如果你见过 AI 翻译带排版的文档，会发现好的工具会把标题、列表、代码块、表格结构全部保留，只翻译正文文本。而有些翻译工具翻译完后标题层级乱掉、代码块被翻译成自然语言、链接文字变成一长串，原因就是它把 Markdown 标记符号也当成了普通文本一起喂给了模型。
原理其实不复杂：Markdown 是一种纯文本的语义标记语言，标记符号（#、*、|、````等）和内容文本天然分离。AI 在处理时，可以先做词法分析把标记符号抽离保护起来，只对文本部分做翻译，再把标记符号回填回去。成熟的方案甚至会把代码块片段单独隔离出来，明确告知模型“这些内容不要翻译”，确保 API 调用示例、配置文件不被改写成目标语言。
真正难的是语义排版的保持。比如中文和英文的行内代码后空格习惯不同，直接翻译会导致中文标点和英文代码之间没有空格，视觉上挤成一团。所以当你在工作流里让 AI 翻译 Markdown 文档时，一定要在提示词（或者系统设定）里明确：保留所有 Markdown 符号、保留代码块内容不译、保留所有标题层级、表格单元格不拆分。下一步我用 Coze 这类工具做 Markdown 转 Word 工作流的时候，就会把这一步的检查加入自动化规则，避免 AI 输出把排版弄翻车。
4. 放进真实项目里：排版规范怎么沉淀成团队习惯
前面讲了非常多“怎么写”，但说实话，一个人在编辑器里怎么折腾都影响有限。真正的分水岭在于：当你的 Markdown 文档进入多人协作、长期维护、版本迭代的阶段，排版还能不能稳住。很多项目仓库里，文档越到后期越乱，就是因为每个人的 Markdown 品味和习惯都不一样，没人定规矩。
4.1 用 CONTRIBUTING.md 把“该有的样子”写下来
我参与和发起过的所有开源项目、团队项目，我都会推动做一件事：在仓库里放一个文档规范说明，命名为CONTRIBUTING.md或DOC_STYLE.md。这个文件不需要长篇大论，但必须把排版约定钉死。我建议至少包含这几条：
- 标题层级规范：一级标题唯一；二级标题对应核心章节；不出现跳级（有
##直接到####的情况视为错误）。 - 换行规范：段落之间使用空行；行尾不保留多余空格；每个 Markdown 文件末尾保留一个换行。
- 代码块规范：所有代码块必须声明语言类型；行内代码用于短代码和变量名，代码块用于多行代码和命令。
- 图片规范：一律使用相对路径，图片放入
assets目录；文件命名小写，用连字符分隔；图片展示前先控制宽度。 - 表格和列表规范：表格列数必须一致，单元格里不要放超过 30 字的长文本；有顺序的动作用有序列表，无顺序的罗列用无序列表。
- 链接规范：引用式链接统一放在文末，链接文字要能说清楚链接内容。
这份文件本身就是 Markdown 排版的一个范本。它既是规范，又是活例子：新来的贡献者看一遍这个文件，基本就知道在这个仓库里文档要怎么写了。
不要担心条条框框太多，排版规范的核心价值恰恰是“减少选择”。当每个人不用每次都纠结“这里该用列表还是段落”“图片路径该怎么写”，文档工作流自然会变得顺畅。现在很多团队做 AI 辅助编程，这些规范文件还能被喂给大模型，让它生成的内容从一开始就符合你的排版约定，这部分我 4.4 会展开。
4.2 markdownlint 与 Prettier：让机器替人盯排版规范
光写规范文件还不够，因为人总是会忘的。更高效的做法是引入 Lint 工具和格式化工具，让提交代码前自动检查 Markdown 格式。这就像写代码有了 ESLint 和 Prettier 一样，把“排版品味”变成了可执行的规则。
我常用的工具组合是 markdownlint 加 Prettier。markdownlint 负责检查语法层面的问题：标题层级是否跳级、列表标记是否统一、行尾是否有空格、表格分隔行是否正确、代码块语言标注是否存在。Prettier 则负责统一排版风格：它会自动把表格对齐、调整缩进、统一换行方式。你可以在 Git 的 pre-commit 钩子里跑这两个工具，或者通过 GitHub Actions 在 PR 的时候检查，不合规的文档直接标记为失败，逼着提交者改。
有人会觉得这样太重了，“我写个文档还得装一堆工具？”但我可以负责任地说：一旦文档量超过 50 篇，没有 lint 工具的人工排版必然失控。而且 markdownlint 的很多规则是可配置的，你可以先只开最核心的几条（比如标题层级、表格列数、行尾空格、代码块语言标注），跑一段时间之后再根据团队反馈逐步增加规则。渐进式引入，团队阻力会小很多。
4.3 长文档的组织方式：拆分、目录与链接
Markdown 最理想的应用场景是短小精悍的文档，而不是几千行的大杂烩。我见过很多人的个人笔记或项目文档是一篇 8000 行、把什么都往里塞的巨型 Markdown——开起来卡、检索麻烦、维护难度直接爆表。排版该有的样子，也包括“该拆就拆”。
我的组织原则是：一个文档只讲一件事。项目文档如果需要讲多个模块，一律采用目录结构，每个模块一个文件夹，里面一个README.md做索引，各模块的详细文档放在子目录里相互链接。顶层索引只用表格或列表把链接列清楚，比如：
## 模块导航 | 模块 | 说明 | 文档 | | --- | --- | --- | | 登录认证 | 登录流程、Token 刷新机制 | [auth.md](./auth/) | | 支付系统 | 支付流程、对账说明 | [payment.md](./payment/) |这样的好处是文档之间可以独立演进，读取时也只需要打开自己关心的模块。Git 合作时 diff 也不会因为别人改了文档后半部分而影响到你自己在改的前半部分。
长文档里目录（TOC）是必不可少的。很多渲染器支持自动生成目录，比如 GitHub 上可以用<details>配合 anchor 链接手写一个折叠目录。如果你的文档是最终交付给读者阅读的，我会额外生成一个“阅读指引”，告诉读者先看哪几节、哪些章节可跳过——这才是把排版用于“读者的体验设计”，而非单纯的视觉排布。
4.4 当 AI 参与写作：怎么让它别把排版搞坏
现在很多人已经用 AI 辅助写文档了，但 AI 输出的 Markdown 经常带着一股“格式异味”：H1 后面直接跳 H3、引用块里套列表、列表前空行不对、表格列不对齐、代码块语言标注丢失。原因是 AI 模型懂得 Markdown 语法，但没有内化排版规范。
我的经验是给 AI 一个明确的“排版约束块”。无论你在哪个工具里使用 AI，先把规则塞进系统提示词或项目规则里：
- 只能使用
#到###三级标题，且不允许跳级。 - 段落之间用空行分隔，不使用行尾两个空格换行。
- 代码块必须标注语言类型，代码内容与原语言保持一致，不进行翻译。
- 所有图片一律使用相对路径占位，不要在输出中塞绝对路径。
- 表格中每个单元格不超过 50 个字，超过则拆成段落。
- 引用块只用于警示、注脚和次要说明，不承载主体内容。
试过你就知道，这些显式约束对 AI 非常有效。模型就像一个很聪明但不太懂行规的新同事，你给了 checklist，它就能交出符合你团队风格的初稿；你不给，它就自由发挥，你得花更多时间返工。
还有一个实用技巧：让 AI 生成内容之后，自己先跑一遍 markdownlint。如果规则检查没问题，基本可以放心发布；如果还有 error，很容易定位是哪一类排版问题，再回头修改提示词里的对应约束。这套“AI 生成 → Lint 检查 → 规范迭代”的工作流，等于把团队的排版经验固化成了机器可执行的规则，随着使用次数增多，AI 的排版错误会越来越少。
5. 我踩过的坑和最后想提醒的事
写到这里，我想把过去几年真正踩过的坑集中倒一倒。这些坑都不是什么原理性大问题，但每一个都真实地浪费过我的时间，也让我一步步理解了“Markdown 排版该有的样子”究竟是什么。
5.1 高频问题与对策速查表
按我经验里出现频率从高到低排列，整理成一张速查表，应急时拿出来直接对照：
| 问题 | 原因 | 解决方案 |
|---|---|---|
| 打入的图片换台电脑就裂开 | 使用了绝对路径 | 图片统一放入 assets 目录，文档中使用相对路径 |
| 段落全黏在一起 | 只按了一次回车 | 段落间空一行；源码模式下确认空行存在 |
| 表格渲染失败 | 表格分隔行列数与表头不一致 | 开启 markdownlint，提交前自动检查 |
| 单元格里的竖线把表格拆开 | 竖线未被转义 | 写成|，或用行内代码包裹 |
| 导出 PDF 不显示中文 | PDF 渲染引擎缺少中文字体 | 使用 XeLaTeX 或 HTML+PrinceXML 路线，配置中文字体 |
| Word 转 Markdown 后格式混乱 | 源文档有文本框和手动缩进 | 先用样式刷把 Word 整理一遍，再交给 Pandoc |
| GitHub 上图片裂开 | 文件名大小写不匹配 | 图片统一小写命名，用-分隔单词 |
| AI 生成的表格列数不一致 | 模型没有接受排版约束 | 在提示词中加入 Markdown 排版规则段 |
| 代码块没有高亮 | 缺少语言标注 | 统一补上```python等语言类型 |
| 标题出现跳级 | 写作时层级意识不强 | 开启 markdownlint 的 MD001 规则 |
这张表你收藏也好、打印贴桌上也好，碰到对应问题的时候直接抄作业就行。它背后是我踩过坑换来的经验，不是从语法文档抄来的定义。
5.2 写字之前，先定一套“最小排版规范”
如果你现在手头已经有一堆 Markdown 文档，但一直没有固定的排版规范，我不建议马上建立一个大而全的规则库。那样做不仅很难推进，还会让你在维护规范上消耗比写文档还多的时间。我的做法是先只定五条最小规范，跑一段时间等习惯了，再陆续补充：
- 段落之间空一行，行尾不保留多余空格。
- 标题不跳级，一级标题唯一。
- 代码块必须标注语言类型。
- 图片用相对路径，统一放在
assets文件夹。 - 表格列数一致，单元格不放长文本。
这五条基本覆盖了 90% 的观感问题，也最容易执行。我是在一个四五人的小团队里先用这套规则跑起来的，后来大家习惯了，才逐步引入 markdownlint 和 Prettier 做自动化检查。先把最小规范变成肌肉记忆，再叠加上工具，是最稳妥的路径。如果你是一个人在写个人博客，这套最小规范同样适用——它是你个人品牌的隐形一部分，版式干净，读者对内容的信任感会高很多。
最后再分享一个小细节。不知道你有没有注意过，GitHub 上很多高质量项目的 README，它的排版看起来平平无奇，但你读起来就是舒服。这个“舒服”其实就是排版在起作用：标题层级告诉你现在在哪，列表节奏告诉你该扫读还是细读，代码块的语言标注让你提前知道这段是什么类型的内容，表格的数字对齐让你不用靠数空格来理解数据。真正的 Markdown 排版高手，不会让读者注意到“这里的排版很好”，而是让读者完全沉浸到内容里，不被任何格式上的瑕疵绊住。这是排版该有的样子，也是我一直努力的方向。
