说实话我每次收到别人发来的 Markdown 文件基本上扫一眼的前十秒心里就已经给这个人定了性文档是随手写的还是认真整理过的。Markdown 的门槛低到近乎没有门槛但正因为人人都能上手它排出来的版式才最能暴露一个人的工作习惯。你可以在 Typora 里看到一个高亮得五彩斑斓、标题层级乱跳、表格列宽挤成一团的文档也可以在 GitHub 上遇到一个只用纯文本就让人读得行云流水的 README。这个差距根本不在于有没有天赋而在于有没有把排版这件事当成工程来做。这篇东西我不想讲枯燥的语法手册那些官方文档和教程里有的是。我想聊的是“Markdown 排版该有的样子”——一个我在无数项目文档、技术博客、团队 Wiki 和个人笔记里反复琢磨之后真正沉淀下来的判断标准与实操套路什么时候用标题、表格怎么写才不会裂、图片路径怎么设计才能经得起换电脑和换仓库、导出 PDF 和 Word 时怎么保排版不崩、以及和 AI 协作生成内容时怎么让它别把格式搞得乱七八糟。这篇适合所有想把文档写出“高级感”的人无论你是刚开始接触 Markdown 的纯新手还是写了多年文档但总觉得哪里不对的老手都能从这里找到一些可以直接抄作业的东西。1. 排版先想明白Markdown 的体面来自语义不来自样式先说一个我观察到的普遍误区很多人一提到排版第一反应就是“我要让标题变成红色”“我要把这段字放大加粗”。这是典型的用 Word 思维去写 Markdown。Markdown 从设计之初就是一个“面向语义”的轻量标记语言——它让你标记的是“这段文字是什么”而不是“这段文字长什么样”。所以 Markdown 排版该有的样子第一条就是要克制住调字体、调颜色的冲动。1.1 不要用 HTML 思维写 Markdown字体、颜色不是排版核心确实Markdown 兼容内联 HTML你可以在文档里写font colorred警告/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.pngWindows 下 Typora 能显示推到 GitHub 上就裂了。所以我现在的习惯是图片文件全部小写命名用连字符分隔多个单词比如project-architecture.png。这算是“排版该有的样子”里很小但很专业的细节。图片尺寸也是排版的一部分。Markdown 原生语法不支持指定宽高但很多渲染器支持{: width600px}这类扩展写法或者直接使用 HTML 的img width600 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-doccustom-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 或 HTMLPrinceXML 路线配置中文字体Word 转 Markdown 后格式混乱源文档有文本框和手动缩进先用样式刷把 Word 整理一遍再交给 PandocGitHub 上图片裂开文件名大小写不匹配图片统一小写命名用-分隔单词AI 生成的表格列数不一致模型没有接受排版约束在提示词中加入 Markdown 排版规则段代码块没有高亮缺少语言标注统一补上python等语言类型标题出现跳级写作时层级意识不强开启 markdownlint 的 MD001 规则这张表你收藏也好、打印贴桌上也好碰到对应问题的时候直接抄作业就行。它背后是我踩过坑换来的经验不是从语法文档抄来的定义。5.2 写字之前先定一套“最小排版规范”如果你现在手头已经有一堆 Markdown 文档但一直没有固定的排版规范我不建议马上建立一个大而全的规则库。那样做不仅很难推进还会让你在维护规范上消耗比写文档还多的时间。我的做法是先只定五条最小规范跑一段时间等习惯了再陆续补充段落之间空一行行尾不保留多余空格。标题不跳级一级标题唯一。代码块必须标注语言类型。图片用相对路径统一放在assets文件夹。表格列数一致单元格不放长文本。这五条基本覆盖了 90% 的观感问题也最容易执行。我是在一个四五人的小团队里先用这套规则跑起来的后来大家习惯了才逐步引入 markdownlint 和 Prettier 做自动化检查。先把最小规范变成肌肉记忆再叠加上工具是最稳妥的路径。如果你是一个人在写个人博客这套最小规范同样适用——它是你个人品牌的隐形一部分版式干净读者对内容的信任感会高很多。最后再分享一个小细节。不知道你有没有注意过GitHub 上很多高质量项目的 README它的排版看起来平平无奇但你读起来就是舒服。这个“舒服”其实就是排版在起作用标题层级告诉你现在在哪列表节奏告诉你该扫读还是细读代码块的语言标注让你提前知道这段是什么类型的内容表格的数字对齐让你不用靠数空格来理解数据。真正的 Markdown 排版高手不会让读者注意到“这里的排版很好”而是让读者完全沉浸到内容里不被任何格式上的瑕疵绊住。这是排版该有的样子也是我一直努力的方向。