你有没有过这种经历在WordPress后台写了一篇长文光调字号、改颜色、对齐缩进就折腾了一个小时真正写的内容没几行我前几年做技术博客时就这样古腾堡编辑器虽然功能多但一打开就像进了装修现场写文章的心思全被排版耗光了。后来我把整套写作流程切到 Markdown才算是找回了“先把内容写出来”的痛快感。这篇文章想聊聊我摸索了大半年才定型的 WordPress Markdown 搭配方案包括插件怎么选、本地编辑器用什么、图片路径怎么处理、代码块为什么老出问题以及怎么把博客内容反手导出成 Markdown。适合被后台编辑器折磨的博主、写技术教程的朋友以及想给博客建立一个稳定写作流程的人。1. 为什么我最终放弃了后台编辑器转头拥抱 Markdown1.1 写作真正的敌人是“排版”而不是“没灵感”很多人觉得写博客就是打开后台、写内容、发布。但实际上人脑在两个模式之间来回切换是极度消耗精力的你在想“这个论点怎么论证”的同时还要盯字号、行距、标题颜色、引用块样式精力必然被分摊。Markdown 的做法是彻底把排版交给规则你只输入#、、反引号这些纯文本标记发布时渲染成标准 HTML。我转过去之后写作速度至少快了三分之一前期文章的修改频率也降了不少。古腾堡编辑器这几年迭代得确实越来越强块、模板、模式这些概念都很好但它解决的是“页面搭建”的问题不是“专注写作”的问题。你写一篇两三千字的教程需要的是快速记录思路、插入代码块、引用文档、加个表格而不是反复拖动块、调宽度、对齐。古腾堡给了你太多选择反而让写作本身变成了一种体力劳动。1.2 Markdown 的优势放到 WordPress 场景里更明显从技术博客的角度看Markdown 有四个特性是富文本编辑器比不了的。第一是纯文本可迁移。WordPress 虽然有导出备份功能但导出的 XML 文件本质是 HTML 包裹的数据要改、要搜索、要重新利用都不方便。Markdown 文件本身就是存档任何一个文本编辑器都能打开换成任何博客系统或者不发博客只发到本地知识库都毫无障碍。第二是版本管理。本地 Markdown 文件可以直接丢进 Git每一次改动都有记录哪次改坏了想回滚一行命令就搞定。后台编辑器没有这个能力你改完保存就是覆盖错了就回不去了。第三是不受编辑器绑架。WordPress 版本更新、古腾堡界面变化、主题换了我的写作流程完全不受影响。我见过不少朋友因为编辑器改版而不得不重学一遍后台操作这套组合拳基本不存在这个问题。第四是平台通用。同一份 Markdown 可以快速发到公众号、知乎、语雀、Notion 等平台想同时运营多个内容渠道时不需要每个平台都重新排一次版。1.3 这套组合适合谁不适合谁我不打算无脑吹 Markdown 万能。它适合的是技术博客、教程类网站、喜欢本地写作再发布的人、需要批量生产内容的团队。它的缺点也很明显第一对完全没有语法概念的小白来说学习成本确实存在第二如果文章内容极度依赖复杂排版比如电商详情页、企业官网的产品展示页、带复杂交互的图文Markdown 反而不如古腾堡直观。我见过很多人一上来就全套折腾插件最后又退回古腾堡原因就是把方案想得太复杂。实际上你完全可以从“本地用 Markdown 写草稿、再粘贴进后台”开始不需要任何插件先体会写作流程的变化再决定要不要加后续装备。接下来我会尽量把你“要不要这么干”的判断成本降到最低。2. 在 WordPress 里开启 Markdown 的三条路径我都替你们试过了2.1 方案一WP Githuber MD功能最全这个插件是我目前的主力方案本质上是把 WordPress 后台改造成一个完整的 Markdown 写作环境。它支持 GitHub 风格的 Markdown 语法代码高亮用的是 PrismJS数学公式支持 KaTeX 和 MathJax 两套引擎还带自动目录、Mermaid 图表、代码行号、文章字数统计等功能。最方便的是它能按文章类型开关比如你只想让“文章”用 Markdown“页面”保持古腾堡也可以在设置里单独配置。我建议技术博主优先试这个理由很简单你需要围绕代码块的完整生态而这个插件把代码块的“写作—高亮—行号—复制按钮”一条龙解决掉了省去自己拼装多个插件的麻烦。但有几个细节要注意它默认接管后台编辑器切换到可视化选项卡时展示的是渲染后的 HTML 而不是 Markdown 源码。刚上手可能觉得“我的 MD 哪去了”实际上发布完全正常只要发布后别再切回可视化编辑就行。它自带的 Mermaid 渲染和某些主题的前端脚本可能冲突需要按文章类型临时关掉后面踩坑部分我会具体说。如果站点已经用了大量短代码需要检查插件是否兼容个别短代码在 MD 渲染流程中会被当成普通文本转义。2.2 方案二WP Markdown Editor轻量路线如果你只是想在经典编辑器里用 Markdown 语法写文章不需要代码高亮、数学公式、目录这些重型功能WP Markdown Editor 是更轻的选择。它的安装和配置都很简单装完就能用。但我在实际使用中遇到过兼容性问题当 WordPress 版本升级或主题启用某些过滤函数时渲染结果会不稳定偶尔出现段落丢失的情况。所以我建议普通用户先在当前环境里拿一篇短文章试运行几天确认没问题再长期使用。从维护角度看这种轻量插件的更新频率普遍不如功能型插件高长期依赖的话要留意社区维护状况。如果项目生命周期比较长我更推荐直接上功能完整的方案省得以后迁移数据。2.3 方案三本地写 Markdown再把 HTML 粘贴进 WordPress这是最稳定也最麻烦的方式我称为“伪 Markdown 方案”。本地用任意编辑器写完 Markdown导出为 HTML复制全文粘贴到古腾堡的自定义 HTML 块里。技术上百分之百兼容永远不会因为插件和主题打架而出问题。但它有个致命缺点后续想在后台改一句话得回本地改完再重新粘贴一遍。更新文章变成了一场搬运体力活除非文章是一次性的否则我不建议长期用这个方式。不过它在一种场景下特别好用给客户做维护必须绕过所有插件变量保证内容在任何主题下都能正常显示。这种时候HTML 已经是最稳定的中间格式了。2.4 我最终的选择和理由我自己主力用 WP Githuber MD。原因很简单它把“在后台改文章”这件事变得足够顺滑。写作主战场在本地编辑器发布前粘贴进后台偶尔需要移动端改几个字直接打开后台的 MD 界面也能收拾干净。选型时我的建议是先明确你要哪些能力再决定装哪个插件。如果你只写纯文字文章WP Markdown Editor 完全够用多出来的功能反而干扰如果你要放代码块、数学公式、目录就别在轻量插件上反复试探直接上功能完整的方案。3. 日常写作链路我在本地怎么写、图片怎么传、代码怎么贴3.1 本地编辑器选择Typora、VS Code、Obsidian 的实际体验WordPress 后台那套 Markdown 插件解决的是“发布端”的问题日常真正的写作我推荐在本地完成。我把常用的几个编辑器列个对比都是我实际用过的感受。编辑器免费/付费核心优势主要短板适合场景Typora付费所见即所得图片粘贴自动保存界面干净非免费需要跟进授权纯写作、快速成文VS Code免费配合 Markdown All in One、Markdown Preview Enhanced 插件代码编辑和文章写作无缝切换导出 PDF 方便默认界面偏工程化需要简单配置技术长文、代码教程Obsidian免费文档库管理、双链、标签体系素材积累效率极高发布到 WordPress 需要额外流程素材管理、长周期写作项目Marktext免费Typora 的开源替代品所见即所得功能相对基础表格和复杂排版支持一般预算有限但想用所见即所得我自己当前的搭配是短期灵感用系统备忘录和语雀记录长期素材在 Obsidian 里建库写技术长文用 Typora 或 VS Code。不管用哪个编辑器最终产物都是纯 Markdown 文件放进一个固定文件夹配合 Git 做版本备份。3.2 图片路径先图床还是先媒体库这是很多人卡住的第一步也是“WordPress Markdown”工作流里最容易被低估的环节。Markdown 里写如果图片在本地路径自然不对如果图床配置不当还会碰到防盗链、流量超额、域名变更导致的全站图片挂掉。我给出两种能落地的流程。流程 A先把图片传给 WordPress 媒体库拿到完整 URL再填到 Markdown 里。适合文章数量少、后台和本地穿插操作的人。注意事项是媒体库 URL 的目录结构依托于年月路径很长手工复制容易漏字符建议直接在媒体库的“附件显示设置”里复制链接。流程 B本地用相对路径写images/xxx.png发布前统一替换成媒体库 URL。适合批量写草稿的人。我用 VS Code 的全局搜索替换一次搞定把images/全部替换成https://你的域名/wp-content/uploads/2025/02/再逐一核对剩余错误路径。我推荐流程 B因为我经常在没有网络的环境下写文章图片先放本地文件夹回到有网环境再统一上传替换。如果你长期用图床阿里云 OSS、腾讯云 COS、七牛云都行那更省事直接填全 URL但务必要在图床控制台配置好防盗链白名单同时设置好流量告警避免费用异常。3.3 代码高亮和 Mermaid 图怎么塞进文章很多人以为在 Markdown 里写了三个反引号WordPress 就会自动高亮代码。实际上WordPress 本身不做语法高亮主题自带的高亮和 Markdown 插件的高亮也可能冲突。我的做法是交给 Markdown 插件统一处理主题侧把代码高亮功能关掉否则会出现同一段代码被两种样式叠加的混乱情况。WP Githuber MD 里可以单独设置 PrismJS 的语言列表按需加载不需要把几十种语言全塞进页面里拖慢速度。Mermaid 图也是这样。插件一般提供独立开关你只要在 Markdown 源码里写一句graph LR开头的图定义发布时插件会渲染成 SVG 输出。但主题如果不支持这类内容预览时可能显示不正常我建议发布前在本地预览先确定图能渲染再粘贴到后台。3.4 发布前的预览检查清单我把下面这几项做成了固定动作每次发布前过一遍能省掉后面大量修改标题层级是否错乱#只有文章标题用正文从##开始。代码块是否被正确识别语言标注写清楚比如php、js、bash。图片路径有没有漏替换发布后图片绝对路径是完整域名开头。数学公式是否渲染成功KaTeX 渲染失败时页面上会直接显示源码。目录锚点是否正常点目录里的链接能不能跳到对应标题。移动端代码块有没有横向滚动主题的pre样式如果没有overflow-x: auto小屏幕会很痛苦。4. 踩坑实录代码块挤成一团、图片神秘消失、主题双重渲染4.1 代码块发布后全部挤在一行问题出在 wpautop现象本地预览好好的发到 WordPress 后代码块里的换行全部变成空格整块代码像被压缩的弹簧。排查链路打开页面右键查看源代码找到pre和code标签看换行是被抹掉了还是被br标签替代了。如果代码块区域里有p标签插进pre标签内说明是 WordPress 的 wpautop 自动段落标签在作怪。Markdown 插件一般会过滤 wpautop但主题的the_content过滤器可能又把自动格式化挂回来了。临时切换到默认主题看问题是否消失。如果消失问题就在当前主题。定位到主题的functions.php找到添加wpautop的那行条件性地在当前文章类型中移除。补充一点这个问题不会因为换一个 Markdown 插件就解决因为 wpautop 挂在 WordPress 内容输出链路上任何插件都可能受影响。我看到奇怪渲染结果时第一反应永远是查看页面源代码再判断是哪层在改写而不是反复更换插件。4.2 图片路径404、403、以及懒加载导致的“时好时坏”图片问题分三类表现看起来都像“图挂了”但处理方式完全不同。404 一般是用相对路径导致的。比如文章页面的 URL 是域名/文章别名/你在 Markdown 里写了images/xxx.png浏览器会解析成域名/文章别名/images/xxx.png自然找不到。解决方法是把图片路径替换成全 URL。403 多半是权限或防盗链问题。图片能打开但过一段时间打不开或者换个设备打不开检查图床是否开启了 Referer 防盗链或者 CDN 的防盗链配置是否把某些来源给拦了。图床流量被盗刷的问题经常以这种形式暴露出来我会按时看 CDN 日志和费用明细。200 状态码但图片一会儿有一会儿没有八成是主题开了懒加载。Markdown 渲染出来的img标签没有带主题懒加载脚本需要的class属性浏览器预加载和正式加载逻辑互相打架。不用急着改 Markdown 源码先到主题设置里把懒加载关掉或者改成主题官方支持的写作方式。4.3 主题自带 Markdown 渲染出现双重编译有些开发者主题尤其是带文档站属性的主题会自己在the_content上挂一层 Markdown 解析目的是方便文档作者直接用 MD 写页面。这时候如果你再用 Markdown 插件写文章等于已经渲染成 HTML 后又跑了一遍 Markdown文章标题会变成乱码、下划线被当成斜体语法、链接文本变得奇奇怪怪。排查步骤临时切换主题问题消失基本就是主题的解析函数在做二次处理。到主题后台选项里搜“Markdown”、“解析”、“自动格式化”很多主题已经把这类开关做成选项了。如果主题没有开关就在子主题的functions.php里找到对应过滤函数用remove_filter摘掉它并且只对特定文章类型生效避免影响其他页面。这个坑我最初以为是插件配置错误调了一个晚上没解决换成默认主题才发现是主题打架。所以给新手一个笨但有效的建议任何渲染异常第一步永远是“切换默认主题试试”。先用排除法把主题变量给去掉别在插件配置里死磕。5. 反向折腾把 WordPress 内容导出成 Markdown以及 MD 转 Word/PDF 的实用姿势5.1 为什么要反向折腾不少人以为 WordPress 的文章进了数据库就再也出不来其实只是很少人去做“内容资产化”的换位思考。我现在的习惯是每月跑一次内容导出要么在后台用“工具 → 导出”得到 XML 文件要么通过 WordPress REST API 把文章抓下来存成 Markdown。这样做有三个实际好处异地备份不受服务器影响换主机、换 CMS 时数据可以直接迁移要发公众号、知乎、小红书时可以基于 Markdown 重新排版不用从零开始复制粘贴。5.2 用 Pandoc 把导出的 HTML 批量转成 MarkdownWordPress 导出的 XML 里文章正文以 HTML 形式存在。要转 Markdown最省心的工具是 Pandoc它号称“格式转换界的瑞士军刀”支持几十种格式互转。先把 XML 里每篇文章的内容解出来存成post.html然后一条命令转成 Markdownpandoc -f html -t gfm-raw_html -o post.md post.htmlgfm是 GitHub 风格 Markdowngfm-raw_html这个输出格式会在 Markdown 里保留无法转换的 HTML 标签方便二次清理。如果文章多写一个循环或者用find批量处理都可以。实测下来表格、列表、代码块基本都能保持结构。最乱的是自定义 HTML 块和嵌入视频转出来会有一段看不懂的标签这类内容建议转换后单独清理。另外WordPress 导出的 HTML 里图片链接是完整 URL转成 MD 后链接不变正好方便换平台使用。5.3 Markdown 转 Word / PDF 的常用命令与中文字体把 Markdown 发去投稿、交付给同事、或者存档打印最常用的是转 Wordpandoc test.md -o test.docx --toc -M title文章标题--toc自动生成目录-M title设置文档标题元数据出来的 Word 文档自带目录结构。转 PDF 则建议用 xelatex 引擎重点解决中文字体显示问题pandoc test.md -o test.pdf --pdf-enginexelatex -V CJKmainfontNoto Sans CJK SC在 macOS 上可以把Noto Sans CJK SC换成PingFang SCWindows 上一般是SimSun或Microsoft YaHei。不指定字体的话中文大概率显示成方块甚至直接报错这是 Pandoc 转中文 PDF 最常见的坑。5.4 常见答疑VS Code 导出 PDF 一定要装 PrinceXML 吗不一定。VS Code 里常用的 Markdown PDF 插件用的是 Chromium 打印引擎直接把 Markdown 渲染成 PDF不需要额外装 PrinceXML。PrinceXML 是另一套 HTML/XML 转 PDF 的付费级方案优点是对复杂文档的排版控制非常精细适合做文档生成系统个人写作场景完全没必要引入。如果你在 VS Code 里装了 Markdown PDF 之后中文乱码检查插件设置里的 Print Options 是否指定了前端能识别的中文字体名即可。另外现在很多自动化平台上有“PDF 转 Markdown”的流程原理上也是先把 PDF 解析成 HTML 再转 MD和 Pandoc 是一条思路差别主要在解析精度和表格还原能力上。对格式要求不高的内容拿来应急挺合适但严肃场景我依然推荐 Pandoc至少你能确定每一步都是可控的。6. 高频疑问和个人习惯倒计时、地图、Shopify、剪藏这些场景怎么接6.1 Markdown 文章里还能不能用倒计时、地图这类功能能而且很简单。Markdown 渲染出的 HTML 不会阻止你在内容中插入自定义 HTML 或短代码。倒计时可以直接用一个现成插件然后在文章里写短代码百度地图这类就更直接了把地图平台生成的 iframe 嵌入代码粘贴到“自定义 HTML”块里即可。我在实际写博客时遇到特殊功能块时的原则是MD 语法只负责常规内容标题、段落、列表、引用、代码特殊功能块用 HTML 或短代码兜底。两者并不冲突也不需要在 Markdown 和富文本之间来回切换。6.2 WordPress 和 Shopify写作体验为什么差距这么大热词里老有人拿这两个比我的看法是它们解决的根本不是同一个问题。Shopify 的核心是商品、库存、支付、订单它的内容编辑能力只是附属品富文本编辑器连 Markdown 都不支持写一篇长博客文章会非常痛苦。WordPress 核心是内容管理配合 Markdown 插件之后写作体验完全可以做得比任何 SaaS 建站平台都顺手。所以我的建议是先搞清楚自己的站点是“内容驱动”还是“商品驱动”。如果是内容博客、技术教程、行业资讯选 WordPress Markdown 更合理如果你是独立站卖货需要快速上商品、管库存、对接支付Shopify 的开箱即用体验确实更省心。拿电商的需求去要求博客系统或者拿博客的需求去要求电商系统都会觉得难用。6.3 markdownload 这类剪藏工具怎么融入写作流这类浏览器扩展能把网页正文直接提取成 Markdown比如 markdownload安装后点一下图标当前页面的文章内容就变成 MD 文本了。我平时看到好的技术资料、行业报道会用这类工具存进 Obsidian 素材库这样积累的素材本身就是纯文本后面写文章引用时不用二次转换。提醒一下剪藏来的内容一定要标注原始链接和作者信息。一方面避免直接复制发布造成版权问题另一方面写作时要回看原文语境时有链接会方便很多。我对素材库的规范是“标题 来源 摘要 原文链接”缺一不可。6.4 关于编辑器“破解版”和插件安全这里必须泼盆冷水我见过有人为了省几十块钱下载所谓破解版 Typora结果电脑被装了后门程序网站后台密码也被扫走整站被挂马。写作工具的钱不能省。Typora 正版价格不高不想花钱就用免费开源的 Marktext、Obsidian能力足够。WordPress 插件一定要从后台官方目录或插件官网下载不要用“汉化破解版”、“极速安装版”这类来源不明的包。插件安全是整站安全的基本底线一个插件被塞了后门轻则弹广告重则数据库被删、服务器被拿去挖矿。我做这套搭配半年多来最直观的感受是工具从来不是核心核心是你愿不愿意把精力从排版里解放出来放到真正的内容上。Markdown 不是银弹它也有自己的麻烦事但当你习惯了在本地写、在后台发布这套节奏之后再回头用古腾堡加富文本你会明显感觉到那种“为了排版而排版”的消耗有多不值。我的建议是别一口气上全套装备先从本地用 Markdown 写一篇草稿开始哪怕最后发布时还是复制粘贴进后台你的写作体验也会完全不一样。
WordPress+Markdown写作指南：从插件选择到踩坑实录
你有没有过这种经历在WordPress后台写了一篇长文光调字号、改颜色、对齐缩进就折腾了一个小时真正写的内容没几行我前几年做技术博客时就这样古腾堡编辑器虽然功能多但一打开就像进了装修现场写文章的心思全被排版耗光了。后来我把整套写作流程切到 Markdown才算是找回了“先把内容写出来”的痛快感。这篇文章想聊聊我摸索了大半年才定型的 WordPress Markdown 搭配方案包括插件怎么选、本地编辑器用什么、图片路径怎么处理、代码块为什么老出问题以及怎么把博客内容反手导出成 Markdown。适合被后台编辑器折磨的博主、写技术教程的朋友以及想给博客建立一个稳定写作流程的人。1. 为什么我最终放弃了后台编辑器转头拥抱 Markdown1.1 写作真正的敌人是“排版”而不是“没灵感”很多人觉得写博客就是打开后台、写内容、发布。但实际上人脑在两个模式之间来回切换是极度消耗精力的你在想“这个论点怎么论证”的同时还要盯字号、行距、标题颜色、引用块样式精力必然被分摊。Markdown 的做法是彻底把排版交给规则你只输入#、、反引号这些纯文本标记发布时渲染成标准 HTML。我转过去之后写作速度至少快了三分之一前期文章的修改频率也降了不少。古腾堡编辑器这几年迭代得确实越来越强块、模板、模式这些概念都很好但它解决的是“页面搭建”的问题不是“专注写作”的问题。你写一篇两三千字的教程需要的是快速记录思路、插入代码块、引用文档、加个表格而不是反复拖动块、调宽度、对齐。古腾堡给了你太多选择反而让写作本身变成了一种体力劳动。1.2 Markdown 的优势放到 WordPress 场景里更明显从技术博客的角度看Markdown 有四个特性是富文本编辑器比不了的。第一是纯文本可迁移。WordPress 虽然有导出备份功能但导出的 XML 文件本质是 HTML 包裹的数据要改、要搜索、要重新利用都不方便。Markdown 文件本身就是存档任何一个文本编辑器都能打开换成任何博客系统或者不发博客只发到本地知识库都毫无障碍。第二是版本管理。本地 Markdown 文件可以直接丢进 Git每一次改动都有记录哪次改坏了想回滚一行命令就搞定。后台编辑器没有这个能力你改完保存就是覆盖错了就回不去了。第三是不受编辑器绑架。WordPress 版本更新、古腾堡界面变化、主题换了我的写作流程完全不受影响。我见过不少朋友因为编辑器改版而不得不重学一遍后台操作这套组合拳基本不存在这个问题。第四是平台通用。同一份 Markdown 可以快速发到公众号、知乎、语雀、Notion 等平台想同时运营多个内容渠道时不需要每个平台都重新排一次版。1.3 这套组合适合谁不适合谁我不打算无脑吹 Markdown 万能。它适合的是技术博客、教程类网站、喜欢本地写作再发布的人、需要批量生产内容的团队。它的缺点也很明显第一对完全没有语法概念的小白来说学习成本确实存在第二如果文章内容极度依赖复杂排版比如电商详情页、企业官网的产品展示页、带复杂交互的图文Markdown 反而不如古腾堡直观。我见过很多人一上来就全套折腾插件最后又退回古腾堡原因就是把方案想得太复杂。实际上你完全可以从“本地用 Markdown 写草稿、再粘贴进后台”开始不需要任何插件先体会写作流程的变化再决定要不要加后续装备。接下来我会尽量把你“要不要这么干”的判断成本降到最低。2. 在 WordPress 里开启 Markdown 的三条路径我都替你们试过了2.1 方案一WP Githuber MD功能最全这个插件是我目前的主力方案本质上是把 WordPress 后台改造成一个完整的 Markdown 写作环境。它支持 GitHub 风格的 Markdown 语法代码高亮用的是 PrismJS数学公式支持 KaTeX 和 MathJax 两套引擎还带自动目录、Mermaid 图表、代码行号、文章字数统计等功能。最方便的是它能按文章类型开关比如你只想让“文章”用 Markdown“页面”保持古腾堡也可以在设置里单独配置。我建议技术博主优先试这个理由很简单你需要围绕代码块的完整生态而这个插件把代码块的“写作—高亮—行号—复制按钮”一条龙解决掉了省去自己拼装多个插件的麻烦。但有几个细节要注意它默认接管后台编辑器切换到可视化选项卡时展示的是渲染后的 HTML 而不是 Markdown 源码。刚上手可能觉得“我的 MD 哪去了”实际上发布完全正常只要发布后别再切回可视化编辑就行。它自带的 Mermaid 渲染和某些主题的前端脚本可能冲突需要按文章类型临时关掉后面踩坑部分我会具体说。如果站点已经用了大量短代码需要检查插件是否兼容个别短代码在 MD 渲染流程中会被当成普通文本转义。2.2 方案二WP Markdown Editor轻量路线如果你只是想在经典编辑器里用 Markdown 语法写文章不需要代码高亮、数学公式、目录这些重型功能WP Markdown Editor 是更轻的选择。它的安装和配置都很简单装完就能用。但我在实际使用中遇到过兼容性问题当 WordPress 版本升级或主题启用某些过滤函数时渲染结果会不稳定偶尔出现段落丢失的情况。所以我建议普通用户先在当前环境里拿一篇短文章试运行几天确认没问题再长期使用。从维护角度看这种轻量插件的更新频率普遍不如功能型插件高长期依赖的话要留意社区维护状况。如果项目生命周期比较长我更推荐直接上功能完整的方案省得以后迁移数据。2.3 方案三本地写 Markdown再把 HTML 粘贴进 WordPress这是最稳定也最麻烦的方式我称为“伪 Markdown 方案”。本地用任意编辑器写完 Markdown导出为 HTML复制全文粘贴到古腾堡的自定义 HTML 块里。技术上百分之百兼容永远不会因为插件和主题打架而出问题。但它有个致命缺点后续想在后台改一句话得回本地改完再重新粘贴一遍。更新文章变成了一场搬运体力活除非文章是一次性的否则我不建议长期用这个方式。不过它在一种场景下特别好用给客户做维护必须绕过所有插件变量保证内容在任何主题下都能正常显示。这种时候HTML 已经是最稳定的中间格式了。2.4 我最终的选择和理由我自己主力用 WP Githuber MD。原因很简单它把“在后台改文章”这件事变得足够顺滑。写作主战场在本地编辑器发布前粘贴进后台偶尔需要移动端改几个字直接打开后台的 MD 界面也能收拾干净。选型时我的建议是先明确你要哪些能力再决定装哪个插件。如果你只写纯文字文章WP Markdown Editor 完全够用多出来的功能反而干扰如果你要放代码块、数学公式、目录就别在轻量插件上反复试探直接上功能完整的方案。3. 日常写作链路我在本地怎么写、图片怎么传、代码怎么贴3.1 本地编辑器选择Typora、VS Code、Obsidian 的实际体验WordPress 后台那套 Markdown 插件解决的是“发布端”的问题日常真正的写作我推荐在本地完成。我把常用的几个编辑器列个对比都是我实际用过的感受。编辑器免费/付费核心优势主要短板适合场景Typora付费所见即所得图片粘贴自动保存界面干净非免费需要跟进授权纯写作、快速成文VS Code免费配合 Markdown All in One、Markdown Preview Enhanced 插件代码编辑和文章写作无缝切换导出 PDF 方便默认界面偏工程化需要简单配置技术长文、代码教程Obsidian免费文档库管理、双链、标签体系素材积累效率极高发布到 WordPress 需要额外流程素材管理、长周期写作项目Marktext免费Typora 的开源替代品所见即所得功能相对基础表格和复杂排版支持一般预算有限但想用所见即所得我自己当前的搭配是短期灵感用系统备忘录和语雀记录长期素材在 Obsidian 里建库写技术长文用 Typora 或 VS Code。不管用哪个编辑器最终产物都是纯 Markdown 文件放进一个固定文件夹配合 Git 做版本备份。3.2 图片路径先图床还是先媒体库这是很多人卡住的第一步也是“WordPress Markdown”工作流里最容易被低估的环节。Markdown 里写如果图片在本地路径自然不对如果图床配置不当还会碰到防盗链、流量超额、域名变更导致的全站图片挂掉。我给出两种能落地的流程。流程 A先把图片传给 WordPress 媒体库拿到完整 URL再填到 Markdown 里。适合文章数量少、后台和本地穿插操作的人。注意事项是媒体库 URL 的目录结构依托于年月路径很长手工复制容易漏字符建议直接在媒体库的“附件显示设置”里复制链接。流程 B本地用相对路径写images/xxx.png发布前统一替换成媒体库 URL。适合批量写草稿的人。我用 VS Code 的全局搜索替换一次搞定把images/全部替换成https://你的域名/wp-content/uploads/2025/02/再逐一核对剩余错误路径。我推荐流程 B因为我经常在没有网络的环境下写文章图片先放本地文件夹回到有网环境再统一上传替换。如果你长期用图床阿里云 OSS、腾讯云 COS、七牛云都行那更省事直接填全 URL但务必要在图床控制台配置好防盗链白名单同时设置好流量告警避免费用异常。3.3 代码高亮和 Mermaid 图怎么塞进文章很多人以为在 Markdown 里写了三个反引号WordPress 就会自动高亮代码。实际上WordPress 本身不做语法高亮主题自带的高亮和 Markdown 插件的高亮也可能冲突。我的做法是交给 Markdown 插件统一处理主题侧把代码高亮功能关掉否则会出现同一段代码被两种样式叠加的混乱情况。WP Githuber MD 里可以单独设置 PrismJS 的语言列表按需加载不需要把几十种语言全塞进页面里拖慢速度。Mermaid 图也是这样。插件一般提供独立开关你只要在 Markdown 源码里写一句graph LR开头的图定义发布时插件会渲染成 SVG 输出。但主题如果不支持这类内容预览时可能显示不正常我建议发布前在本地预览先确定图能渲染再粘贴到后台。3.4 发布前的预览检查清单我把下面这几项做成了固定动作每次发布前过一遍能省掉后面大量修改标题层级是否错乱#只有文章标题用正文从##开始。代码块是否被正确识别语言标注写清楚比如php、js、bash。图片路径有没有漏替换发布后图片绝对路径是完整域名开头。数学公式是否渲染成功KaTeX 渲染失败时页面上会直接显示源码。目录锚点是否正常点目录里的链接能不能跳到对应标题。移动端代码块有没有横向滚动主题的pre样式如果没有overflow-x: auto小屏幕会很痛苦。4. 踩坑实录代码块挤成一团、图片神秘消失、主题双重渲染4.1 代码块发布后全部挤在一行问题出在 wpautop现象本地预览好好的发到 WordPress 后代码块里的换行全部变成空格整块代码像被压缩的弹簧。排查链路打开页面右键查看源代码找到pre和code标签看换行是被抹掉了还是被br标签替代了。如果代码块区域里有p标签插进pre标签内说明是 WordPress 的 wpautop 自动段落标签在作怪。Markdown 插件一般会过滤 wpautop但主题的the_content过滤器可能又把自动格式化挂回来了。临时切换到默认主题看问题是否消失。如果消失问题就在当前主题。定位到主题的functions.php找到添加wpautop的那行条件性地在当前文章类型中移除。补充一点这个问题不会因为换一个 Markdown 插件就解决因为 wpautop 挂在 WordPress 内容输出链路上任何插件都可能受影响。我看到奇怪渲染结果时第一反应永远是查看页面源代码再判断是哪层在改写而不是反复更换插件。4.2 图片路径404、403、以及懒加载导致的“时好时坏”图片问题分三类表现看起来都像“图挂了”但处理方式完全不同。404 一般是用相对路径导致的。比如文章页面的 URL 是域名/文章别名/你在 Markdown 里写了images/xxx.png浏览器会解析成域名/文章别名/images/xxx.png自然找不到。解决方法是把图片路径替换成全 URL。403 多半是权限或防盗链问题。图片能打开但过一段时间打不开或者换个设备打不开检查图床是否开启了 Referer 防盗链或者 CDN 的防盗链配置是否把某些来源给拦了。图床流量被盗刷的问题经常以这种形式暴露出来我会按时看 CDN 日志和费用明细。200 状态码但图片一会儿有一会儿没有八成是主题开了懒加载。Markdown 渲染出来的img标签没有带主题懒加载脚本需要的class属性浏览器预加载和正式加载逻辑互相打架。不用急着改 Markdown 源码先到主题设置里把懒加载关掉或者改成主题官方支持的写作方式。4.3 主题自带 Markdown 渲染出现双重编译有些开发者主题尤其是带文档站属性的主题会自己在the_content上挂一层 Markdown 解析目的是方便文档作者直接用 MD 写页面。这时候如果你再用 Markdown 插件写文章等于已经渲染成 HTML 后又跑了一遍 Markdown文章标题会变成乱码、下划线被当成斜体语法、链接文本变得奇奇怪怪。排查步骤临时切换主题问题消失基本就是主题的解析函数在做二次处理。到主题后台选项里搜“Markdown”、“解析”、“自动格式化”很多主题已经把这类开关做成选项了。如果主题没有开关就在子主题的functions.php里找到对应过滤函数用remove_filter摘掉它并且只对特定文章类型生效避免影响其他页面。这个坑我最初以为是插件配置错误调了一个晚上没解决换成默认主题才发现是主题打架。所以给新手一个笨但有效的建议任何渲染异常第一步永远是“切换默认主题试试”。先用排除法把主题变量给去掉别在插件配置里死磕。5. 反向折腾把 WordPress 内容导出成 Markdown以及 MD 转 Word/PDF 的实用姿势5.1 为什么要反向折腾不少人以为 WordPress 的文章进了数据库就再也出不来其实只是很少人去做“内容资产化”的换位思考。我现在的习惯是每月跑一次内容导出要么在后台用“工具 → 导出”得到 XML 文件要么通过 WordPress REST API 把文章抓下来存成 Markdown。这样做有三个实际好处异地备份不受服务器影响换主机、换 CMS 时数据可以直接迁移要发公众号、知乎、小红书时可以基于 Markdown 重新排版不用从零开始复制粘贴。5.2 用 Pandoc 把导出的 HTML 批量转成 MarkdownWordPress 导出的 XML 里文章正文以 HTML 形式存在。要转 Markdown最省心的工具是 Pandoc它号称“格式转换界的瑞士军刀”支持几十种格式互转。先把 XML 里每篇文章的内容解出来存成post.html然后一条命令转成 Markdownpandoc -f html -t gfm-raw_html -o post.md post.htmlgfm是 GitHub 风格 Markdowngfm-raw_html这个输出格式会在 Markdown 里保留无法转换的 HTML 标签方便二次清理。如果文章多写一个循环或者用find批量处理都可以。实测下来表格、列表、代码块基本都能保持结构。最乱的是自定义 HTML 块和嵌入视频转出来会有一段看不懂的标签这类内容建议转换后单独清理。另外WordPress 导出的 HTML 里图片链接是完整 URL转成 MD 后链接不变正好方便换平台使用。5.3 Markdown 转 Word / PDF 的常用命令与中文字体把 Markdown 发去投稿、交付给同事、或者存档打印最常用的是转 Wordpandoc test.md -o test.docx --toc -M title文章标题--toc自动生成目录-M title设置文档标题元数据出来的 Word 文档自带目录结构。转 PDF 则建议用 xelatex 引擎重点解决中文字体显示问题pandoc test.md -o test.pdf --pdf-enginexelatex -V CJKmainfontNoto Sans CJK SC在 macOS 上可以把Noto Sans CJK SC换成PingFang SCWindows 上一般是SimSun或Microsoft YaHei。不指定字体的话中文大概率显示成方块甚至直接报错这是 Pandoc 转中文 PDF 最常见的坑。5.4 常见答疑VS Code 导出 PDF 一定要装 PrinceXML 吗不一定。VS Code 里常用的 Markdown PDF 插件用的是 Chromium 打印引擎直接把 Markdown 渲染成 PDF不需要额外装 PrinceXML。PrinceXML 是另一套 HTML/XML 转 PDF 的付费级方案优点是对复杂文档的排版控制非常精细适合做文档生成系统个人写作场景完全没必要引入。如果你在 VS Code 里装了 Markdown PDF 之后中文乱码检查插件设置里的 Print Options 是否指定了前端能识别的中文字体名即可。另外现在很多自动化平台上有“PDF 转 Markdown”的流程原理上也是先把 PDF 解析成 HTML 再转 MD和 Pandoc 是一条思路差别主要在解析精度和表格还原能力上。对格式要求不高的内容拿来应急挺合适但严肃场景我依然推荐 Pandoc至少你能确定每一步都是可控的。6. 高频疑问和个人习惯倒计时、地图、Shopify、剪藏这些场景怎么接6.1 Markdown 文章里还能不能用倒计时、地图这类功能能而且很简单。Markdown 渲染出的 HTML 不会阻止你在内容中插入自定义 HTML 或短代码。倒计时可以直接用一个现成插件然后在文章里写短代码百度地图这类就更直接了把地图平台生成的 iframe 嵌入代码粘贴到“自定义 HTML”块里即可。我在实际写博客时遇到特殊功能块时的原则是MD 语法只负责常规内容标题、段落、列表、引用、代码特殊功能块用 HTML 或短代码兜底。两者并不冲突也不需要在 Markdown 和富文本之间来回切换。6.2 WordPress 和 Shopify写作体验为什么差距这么大热词里老有人拿这两个比我的看法是它们解决的根本不是同一个问题。Shopify 的核心是商品、库存、支付、订单它的内容编辑能力只是附属品富文本编辑器连 Markdown 都不支持写一篇长博客文章会非常痛苦。WordPress 核心是内容管理配合 Markdown 插件之后写作体验完全可以做得比任何 SaaS 建站平台都顺手。所以我的建议是先搞清楚自己的站点是“内容驱动”还是“商品驱动”。如果是内容博客、技术教程、行业资讯选 WordPress Markdown 更合理如果你是独立站卖货需要快速上商品、管库存、对接支付Shopify 的开箱即用体验确实更省心。拿电商的需求去要求博客系统或者拿博客的需求去要求电商系统都会觉得难用。6.3 markdownload 这类剪藏工具怎么融入写作流这类浏览器扩展能把网页正文直接提取成 Markdown比如 markdownload安装后点一下图标当前页面的文章内容就变成 MD 文本了。我平时看到好的技术资料、行业报道会用这类工具存进 Obsidian 素材库这样积累的素材本身就是纯文本后面写文章引用时不用二次转换。提醒一下剪藏来的内容一定要标注原始链接和作者信息。一方面避免直接复制发布造成版权问题另一方面写作时要回看原文语境时有链接会方便很多。我对素材库的规范是“标题 来源 摘要 原文链接”缺一不可。6.4 关于编辑器“破解版”和插件安全这里必须泼盆冷水我见过有人为了省几十块钱下载所谓破解版 Typora结果电脑被装了后门程序网站后台密码也被扫走整站被挂马。写作工具的钱不能省。Typora 正版价格不高不想花钱就用免费开源的 Marktext、Obsidian能力足够。WordPress 插件一定要从后台官方目录或插件官网下载不要用“汉化破解版”、“极速安装版”这类来源不明的包。插件安全是整站安全的基本底线一个插件被塞了后门轻则弹广告重则数据库被删、服务器被拿去挖矿。我做这套搭配半年多来最直观的感受是工具从来不是核心核心是你愿不愿意把精力从排版里解放出来放到真正的内容上。Markdown 不是银弹它也有自己的麻烦事但当你习惯了在本地写、在后台发布这套节奏之后再回头用古腾堡加富文本你会明显感觉到那种“为了排版而排版”的消耗有多不值。我的建议是别一口气上全套装备先从本地用 Markdown 写一篇草稿开始哪怕最后发布时还是复制粘贴进后台你的写作体验也会完全不一样。
