选Markdown在线编辑器这件事看着是选工具其实是在选一条渲染链路。我过去一年里在各种编辑器之间来回搬文档光Markdown文件就存了好几百份最后真正让我头疼的不是打字手感而是同一个文件在A站点渲染正常、到B站点样式全丢、导出PDF又跑版。这篇文章我把选型思路、渲染管线里最容易踩的3个坑以及Markdown转PDF时那些“看着小事、改起来要命”的排版问题一次性拆开讲清楚。想省时间的可以直接跳到第4章的速查表想搞明白背后原理的建议从头看。1. 在线Markdown编辑器怎么选先想清楚这三件事1.1 第一件事编辑内核决定输入体验但渲染端才决定输出结果很多人在选编辑器时只看界面好不好看、支不支持实时预览其实这里有个经常被忽略的分工编辑区和渲染区是两套完全独立的东西。编辑区负责的是“写”常见的内核有CodeMirror、Monaco Editor这类它们负责光标、缩进、代码高亮、自动补全。写Markdown的人对这块感知最强的就是表格对齐、代码块缩进、列表自动续行是否顺手。以我的实际体验来说Monaco在代码块编辑上更接近VSCode的手感CodeMirror则更轻更流畅但这两者差异并不会影响最终产物。渲染区负责的是“读”也就是把你写的那串带井号、星号、横线的纯文本变成带标题层级、加粗斜体、代码高亮的页面。不同编辑器在这一步的差距非常大而这一步恰恰决定了你“看到的样子”是不是文档的真正样子。选型时先问自己一个问题我主要在哪里看渲染效果如果写技术文档渲染区和线上文档站点的效果是否一致如果用在线编辑器写完后要复制到公众号、知乎、语雀那渲染结果会不会被平台再处理一遍很多人踩坑都是因为忽略了这个问题把在线编辑器当成“所见即所得”工具最后发现它的渲染结果根本不能代表最终效果。1.2 第二件事渲染规范是“共同语言”不认GFM的编辑器会坑哭你Markdown看似简单实际上存在多套规范版本。最原始的CommonMark是基础版但很多常用语法它并不支持比如表格、删除线、任务列表、自动链接。而现在大家在日常写作中最常用的其实是GitHub Flavored Markdown也就是GFM。GFM是在CommonMark基础上扩展出来的方言它加入了表格、任务列表、删除线、锚点跳转等实用功能。绝大多数主流编辑器比如Typora、语雀、Notion、Obsidian、StackEdit都是按GFM或者GFM超集来渲染的。但问题来了不同编辑器对GFM的支持程度并不一致。有的编辑器不认GFM只支持CommonMark那么你辛辛苦苦写的表格在编辑器里不会渲染成表格而会变成一堆管道符和短横线有的编辑器干脆把表格当作HTML解析遇到特殊符号就断行。我自己就遇到过写任务列表- [ ] 待办在A工具里显示成复选框粘贴到B工具里直接变成三个字符[ ]跑在正文里的情况非常离谱。所以选型时要确认清楚编辑器支持哪套规范最好直接拿一段包含表格、删除线、任务列表、多级列表、嵌套代码块的测试文档同时丢进去比一比渲染结果这比看宣传页上的“支持GFM”五个字靠谱得多。1.3 第三件事导出能力不是附加项是选型的硬指标Markdown文件本身是纯文本这意味着它天然适合跨平台传播版本管理也方便。但问题是不是所有人都愿意或者能够直接阅读Markdown源码绝大多数场景下你得把Markdown转成PDF、Word或者HTML交给别人。这就涉及导出能力。不同在线编辑器的导出能力差距极大有的只能导出HTML导出的PDF要自己用浏览器打印有的PDF导出实际上是“打印网页”支持程度取决于浏览器有的走Pandoc后端导出理论上支持任意格式但实际效果和主题模板强相关有的干脆不支持导出只能在网页里看。我建议选型时把导出能力放在和编辑体验同等重要的位置上来考虑。你可以问自己几个问题导出PDF时能不能自定义页边距中文字体是否正常代码块会不会被截断表格会不会超出页面范围这些在后面的章节里会详细展开。我给一个非常朴素的选型建议如果你的主力需求是本地写作、偶尔导出Typora仍然是最顺手的工具之一如果是在线协作、实时共享Notion、语雀这类偏产品的编辑器更好用如果是写技术文档且要进代码仓库那VSCode加Markdown Preview Enhanced插件才是真正的归宿因为它把渲染和导出都交给了同一个后端减少了很多不必要的转换损耗。2. 渲染管线的3个坑同一个md为什么到哪都不一样2.1 渲染管线到底是什么markdown到页面要经过几个环节很多人把Markdown到页面看成一步到位实际上它是一条完整的管线Markdown源码先被解析成AST也就是抽象语法树然后由HTML渲染器生成HTML字符串接着由浏览器或Electron容器把HTML解析成DOM再套用CSS样式完成最终页面渲染。这条链路里的每一个环节都可能改变最终结果。AST阶段决定“哪些语法被识别”HTML渲染器决定“识别之后生成什么结构”浏览器决定“结构和样式怎么结合”。三个环节里任何一个出现差异你看到的页面就会不一样。这也是为什么同一个Markdown文件在Typora里面渲染是一个样子在语雀里面又是一个样子到了浏览器Markdown预览插件里又变成第三个样子。不是谁做错了而是它们各自渲染管线的参数和过滤规则不一样。我这样类比Markdown源码是一份菜谱AST解析相当于翻译成厨师能看懂的操作步骤HTML渲染器相当于按步骤把菜做出来CSS样式则是摆盘。步骤翻译不同、做菜火候不同、摆盘风格不同最后端上桌的菜自然不一样。2.2 坑一规格混战GFM和CommonMark之间差了一个表格这是最常见也最隐蔽的坑。很多在线编辑器会标榜自己支持GFM但细看它的渲染结果其实只支持CommonMark加表格其他扩展语法一个也没跟上。我实际踩过的一个例子是用某在线编辑器写包含多行表格的Markdown文档表格里有|符号和反斜杠转义在源码里看完全正常预览时表格却直接裂开——有的行识别成了普通段落有的行错位。查了半天发现那个编辑器用的解析器是marked的旧版本旧版的表格解析对反斜杠转义支持不友好遇到特殊字符就原样输出。还有一个更隐蔽的问题是任务列表。GFM规范里任务列表是把[ ]和[x]放在列表项的开头但某些编辑器只识别小写x不识别大写X甚至只识别[ ]和[x]无法识别[X]。如果你用大写X标记已完成渲染出来仍然是未勾选状态。我的建议是平时写文档尽量用GFM规范但别把某个编辑器对GFM的“宣传支持”当成“完整支持”。最稳妥的办法是准备一份语法自检测试平时写长文档时每隔几段就切到源码模式看一眼。不要只在预览模式里写那会让你以为一切正常实际上渲染结果很可能是错误的。2.3 坑二过滤规则不同HTML和样式被静默吞掉Markdown允许内嵌HTML这是它的一个重要特性但也带来一个问题在网页环境里浏览器出于安全考虑会对HTML进行过滤尤其是script标签、事件属性和危险的CSS表达式。这种过滤机制每个团队实现得不一样有的过滤程度很严格有的则相对宽松。我在使用在线编辑器时就遇到过这种情况为了给某段文字加个自定义样式在Markdown里写了一段span stylecolor:red警示/span结果预览时样式直接消失了既不报错也不提示就像那段HTML被静默吞掉了一样。后来才发现那个编辑器为了防XSS对所有内联样式做了白名单过滤color属性不在白名单里整个span标签被剥成了纯文本。这种静默失败是非常坑人的。因为从源码看一切正常从预览看好像也没太大异常但你期望的红色文字就是不会出现。更麻烦的是如果你把这段Markdown复制到另一个编辑器里过滤规则不一样这段HTML可能又被原样渲染出来了。所以在不同编辑器之间迁移文档时带有自定义HTML的段落一定要重点检查。要想避开这个坑分两步第一步写作时尽量避免依赖内嵌HTML和自定义样式Markdown本身提供的语法足够覆盖99%的排版需求第二步如果确需自定义样式可以先把内容在本地编辑器里确认渲染效果再往在线编辑器里粘粘完后切到预览模式和源码模式对比看别嫌麻烦。2.4 坑三容器样式继承换个主题就变“另一篇文档”这个问题很多人没意识到但它的杀伤力比前两个都大。每个编辑器都有自己的预设CSS包括默认字体、标题大小、行高、代码块背景色、引用块的左边框颜色、表格的边框样式。这些样式通常隐藏在主题里你写文档时看到的排版效果其实是“你的内容这个主题的CSS”共同作用的结果。一旦换主题或者把内容粘贴到另一个渲染环境里你的文档看起来就会完全不一样。我举个具体例子在A工具里三级标题显示为18像素、加粗、带下划线粘贴到B工具里三级标题变成22像素、加粗、但颜色变成了主题蓝。你原来的“第三层标题”在视觉上可能变得比第二层还大整个层级感就乱了。更隐蔽的是代码块。每个编辑器对代码块的默认字体、背景色、行号显示、滚动条样式都不同代码块里的中文换行行为也不一样。我在某个在线编辑器里写的代码块粘贴到另一个工具后长行直接被折行显示完全不能看。查了半天才发现是代码块容器的white-space属性不同导致的。要解决这个问题最好的办法是不要依赖编辑器的主题样式来传达文档结构。也就是说标题层级的意义应该由Markdown语法本身来保证而不是由某个主题下的视觉效果来保证。在选编辑器时尽量选择主题之间差异较小的或者选能导出为标准CSS的工具这样至少在不同环境之间迁移时样式损失会更小。3. md转PDF跑版记录那些年我们追过的页边距3.1 一次真实的跑版事故表格飞出页面代码块被拦腰截断先说一个我最近遇到的真实案例。有一个技术文档项目里面用Markdown写了一份三十多页的接口说明内容包括大量代码块、接口表格和流程图。项目经理要求输出一份PDF版本放在归档系统里。我用在线编辑器直接导出PDF第一次跑版就来了一张六列接口参数表直接超出页面边界最右边的两列内容被硬生生裁掉连滚动条都没有因为PDF是静态页面。更麻烦的是表格中间一行恰好跨到了下一页表头没有重复那一行数据被切成两半看着就像文档印错了。代码块的问题更突出。一段很长的JSON配置样例在页面上显示得好好的导出PDF后代码块每行都在中间位置断开换行缩进完全错乱有的行末尾还被截断。我用浏览器打印功能重新导了一次虽然代码块不断行了但代码块和正文之间的分页又不对了——有的代码块直接从页面底部被切掉半截可读性非常差。这就是典型的PDF跑版问题。它不是某一个编辑器的问题而是Markdown到PDF转换过程中三个环节的衔接出了问题解析阶段没处理好Markdown结构样式阶段没适配打印页面排版阶段没有考虑分页细节。3.2 排查路径先区分机器问题、解析问题还是布局问题遇到PDF跑版时不要急着换工具先按这个思路排查先确认是不是解析问题再确认是样式问题最后才是布局问题。第一步先在编辑器里确认Markdown源码是否能正确渲染成HTML。如果连预览都跑版那就是解析阶段的问题换导出工具也没用得改源码或者换编辑器。第二步如果预览正常导出PDF跑版就要看导出工具是怎么工作的。有的工具是直接对预览页面执行打印有的是先转HTML再转PDF还有的是走Pandoc转LaTeX再生成PDF。这三种路线的渲染逻辑完全不同跑版原因也各不相同。比如我遇到的那个表格超出页面边界的问题就是典型的布局问题——HTML表格默认不会自动缩放列宽来适应页面宽度如果列太多就会溢出页边距。这跟浏览器打印时没有对表格应用合适的CSS样式有很大关系。第三步确认跑版是全局性的还是局部性的。全局性的比如所有中文都乱码、所有页边距都异常通常是主题或者渲染工具配置的问题局部性的比如某个表格跑版、某段代码被截断通常是内容本身和布局规则冲突。按这个思路排查能省下大量瞎试的时间。推荐一个很实用的工具组合先用VSCode的Markdown Preview Enhanced插件把Markdown导出为HTML再用浏览器打印成PDF。这样至少能分辨出问题到底是出在Markdown解析阶段还是PDF布局阶段。3.3 三条主流导出路径的实测心得目前Markdown转PDF的主流路径有三条我分别说下实测心得。第一条是“在线编辑器自带导出”。这类导出大多是网页打印优点是方便缺点也很明显——页边距、纸张大小、打印缩放全都由编辑器预设了用户可控参数非常少。适合快速出小文档不适合正式交付。我一般只在文件三页以内、格式要求不高时用。第二条是“VSCode插件导出”。网上很多教程会提到VSCode里要把Markdown导出为PDF需要下载安装PrinceXML然后通过Markdown Preview Enhanced插件调用PrinceXML来生成PDF。这个说法是对的但容易让人误会以为不装PrinceXML就不能导出。实际上Markdown Preview Enhanced有多种导出方式可以直接用Chrome打印也可以借助Pandoc转成PDFPrinceXML只是其中一种可选路径。PrinceXML的特点是排版引擎非常成熟生成的PDF质量很高对CSS的支持远比浏览器打印好表格分页、页边距控制、页眉页脚这些细节都支持得很好。但是它是商业软件非商业用途免费商用需要购买授权。如果你在VSCode里导出PDF时遇到了“ requires princexml ”之类的提示并且需要商用建议直接用Chrome打印替代效果也不会差太多。第三条是“本地装Pandoc加LaTeX引擎”。这是最强大但门槛也最高的一条路。Pandoc能把Markdown转成PDF中间默认走LaTeX引擎。LaTeX能处理几乎所有排版细节包括中文排版、页边距、表格分页、代码块跨页但你需要安装对应字体和宏包第一次配置往往要折腾几个小时。我个人的建议是如果你需要频繁生成正式PDF文档这个方案值得认真配一次如果只是偶尔导出用Chrome打印就足够了。3.4 中文排版专项字体、换行和“孤儿标点”很多人以为Markdown转PDF跑版是解析问题结果折腾半天发现是中文排版根本没被处理。中文排版的坑和英文完全不一样我单独拎出来说。第一个坑是字体缺失。很多导出工具默认字体是英文的遇到中文就会回退到系统默认字体效果千奇百怪。有的环境回退到宋体但字重不对有的回退到黑体但字间距过大最离谱的是有些环境直接当成乱码处理。所以在导出PDF之前一定要在导出设置里检查中文字体配置确保指定了系统中存在的中文字体比如Microsoft YaHei、PingFang SC、Noto Sans CJK SC。第二个坑是换行规则。中文默认是无空格书写每行文字之间没有天然断点。PDF布局引擎在排版时会对中文按字符宽度折行但如果在长英文单词或者URL附近折行位置就会变得非常难看。更麻烦的是引用块或者列表项里换行后的缩进对不齐。第三个坑是“孤儿标点”就是行首出现逗号、句号、引号、括号这类标点。中文排版规范要求行首不能出现这些标点但很多PDF生成引擎不会自动处理。要解决这个问题最简单的方法是选对引擎——Pandoc加XeLaTeX引擎默认处理得比较好PrinceXML对中文标点压缩也处理得相当不错。浏览器打印在这方面表现不一如果遇到行首标点问题可以试试调整页面缩放比例或者换一个打印引擎。4. 常见问题速查表与我的避坑清单4.1 高频问题速查表我把自己在Markdown编辑和转PDF时踩过的高频问题整理成了一个速查表方便你直接对照排查现象大概率原因解决思路表格超出页面边界HTML表格默认不自动收缩列宽打印时没有额外的表格CSS导PDF前先导出HTML在HTML里加table { width: 100%; table-layout: fixed; }表格跨页后表头不重复打印样式没有设置thead重复展示在打印CSS里设置表格头部行属性若用Pandoc导出则检查LaTeX模板代码块被拦腰截断分页时没有对pre、code设置分页避让规则打印CSS加pre { page-break-inside: avoid; }或使用支持该规则的导出引擎代码块长行折行white-space属性被设置为normal或pre-wrap检查打印CSS将code的white-space设为pre并开启横向滚动或横向分页中文变成乱码或字体失真导出环境缺少中文字体或指定的字体名不存在在导出工具里显式指定系统中存在的中文字体必要时安装Noto Sans CJK SC行首出现逗号句号PDF排版引擎不支持中文标点挤压规则换用XeLaTeX引擎或PrinceXML导出浏览器打印则尝试调高打印缩放相同文档在不同工具渲染结果不同各工具对应的Markdown解析器版本和扩展语法支持不同迁移文档时重点检查表格、任务列表、删除线、内嵌HTML这四类语法编辑器预览和导出PDF效果不一致预览页面应用的是屏幕样式PDF应用的是打印样式在CSS里单独为media print优化排版规则这里尤其要提醒一下表格宽度问题这是跑版重灾区。如果你经常用Markdown写表格建议养成一个习惯表格列数不超过四列列内容尽量简短。如果确实需要宽表格优先考虑拆表或者改成列表形式而不是硬塞进PDF。4.2 选型与迁移前的检查清单在把大量文档写进某个编辑器之前先把这套检查清单过一遍能省下后续很多迁库的麻烦第一检查语法兼容性。拿一段包含标题、列表、表格、代码块、引用、删除线、任务列表、脚注的测试文档在候选编辑器里逐个渲染截图对比。这个过程半小时就够但能帮你筛掉一半不靠谱的工具。第二检查导入导出闭环。相当于要确认两个方向一是把这个编辑器导出的HTML或PDF重新粘贴到其他平台格式是否保持二是把其他平台复制的富文本粘贴到编辑器是否能自动转成Markdown。很多编辑器只做了导出或只做了导入闭环能力弱长期使用会很难受。第三检查存储格式。在线编辑器的数据是存在云端数据库里的还是能导出标准的.md文件这个直接关系到你的数据自由。建议选择能导出标准Markdown文件的编辑器并且养成定期导出备份的习惯。第四检查渲染延迟和性能。文档超过几千行时拖动滚动条是否卡顿长表格能否流畅滚动代码高亮是否正常有些编辑器在短文档时表现良好长文档一写就卡这是内核层面的问题靠设置解决不了。迁移老文档时我建议分三批迁移先迁一批格式最简单的确认基本流程没问题再迁一批带表格和代码块的排查扩展语法兼容性最后迁一批含图片和特殊符号的确认资源引用路径是否有效。4.3 我的几条私藏经验最后分享几条我在实际操作中积累的经验这些不会写在官方文档里但真的很实用。第一长文档转PDF前一定先导出一份HTML做“中间检查”。Markdown到PDF是两步转换插一层HTML能让你轻松分辨跑版到底发生在哪一步。导出HTML后用浏览器打开看一眼目录结构对不对、表格宽度是否正常再决定要不要继续转PDF。这一步能帮你节省大量试错时间。第二PDF导出前清空不必要的自定义HTML。我在第2章提过不同编辑器的HTML过滤规则不一样。导PDF时如果你在Markdown里嵌入了大量自定义HTML和行内样式很容易在转换过程中出现意外。不是不能用而是要在导出前检查一遍发现问题逐一排查不要在转换工具上反复调参。第三页边距是MD转PDF最重要的参数。很多跑版根本不是渲染问题而是页边距太小。我用Pandoc导出时默认页边距是2.5厘米左右够用但用浏览器打印时默认页边距可能只有1厘米甚至0.5厘米表格稍微宽一点就会贴着页边。建议统一设置成上下2.5厘米、左右2厘米适配大多数场景。第四写文档时就要想着“将来要导出PDF”。这是最根本的一条经验。Markdown写作时尽量用规范语法少依赖某个编辑器的私有扩展代码块里不要写超长的单行文本表格不要塞太多列图片设置好相对路径和高度。这样不管以后换什么工具都不会太痛苦。我在实际使用中的体会是没有完美的Markdown编辑器只有适合自己工作流的编辑器。你把大量内容写进一个封闭编辑器之前先花半小时测清楚它的渲染规范和导出能力远比你写了几百个文件之后再来迁移划算得多。如果你现在正在选型不妨就拿这篇里面的测试清单去试一圈相信你很快就能判断哪个工具和你合拍。