Doocs MD 开源排版工具：让微信公众号完美支持 Markdown

如果你在公众号后台手动排版超过一年大概率会有这种感觉排版这件事本身比写作更消耗耐心。我在试过一堆网页编辑器、浏览器插件和在线转换工具之后最后固定在 Doocs MD 上。这不是因为它长得好看而是因为它解决的问题恰好是微信场景下的核心痛点——把 Markdown 变成能直接粘贴进微信后台、且排版不会乱掉的富文本。下面这份使用手册不是官方文档的复读而是我从第一次打开页面到现在把每一步都实际点过的经验记录。无论你是刚接触 Markdown 的公众号新手还是想统一团队排版风格的编辑这份东西应该都能帮上忙。1. 微信排版的老大难为什么我最终留下了 Doocs MD1.1 还在用微信原生编辑器的人每天都在忍受什么公众号后台自带的编辑器功能上并不是不能用只是用起来非常费力。我自己最直观的感受是样式不稳定。同一个字号、同一个行距在 Chrome 里调好了换到 Edge 或手机端预览可能又是另一副面孔。尤其是遇到代码块、表格、引用这种稍微复杂一点的内容原生编辑器的表现基本属于能用但别指望好看。还有一个更隐蔽的问题是段落结构。微信后台编辑器中回车换行之后生成的段落标签在不同系统下表现不一样有时候是段落间距有时候只是换行导致整篇文章的行距看起来忽疏忽密。你明明写的时候是整齐的发布到手机上一看段落之间挤在一起阅读体验很打折扣。对于经常写技术文章的人来说还有代码高亮、缩进、等宽字体这些需求原生编辑器几乎给不了支持。1.2 Doocs MD 的定位不是 Markdown 笔记本是“公众号排版专用桥接器”Doocs MD 这类工具存在的原因很简单微信后台不认 Markdown但写内容的人越来越习惯 Markdown。它不是像 Typora 那样的通用 Markdown 编辑器也不是 Obsidian 那种知识管理库它更像是一座桥。左边写 Markdown 原文右边实时看到接近公众号成稿效果的预览点一下复制再切到微信公众号后台粘贴段间距、代码块样式、表格边框、引用底色这些都已经处理好了。这套流程省掉的是写完 Markdown 再手动粘到编辑器里重新排版的半个多小时对日更公众号来说这半小时很值钱。我把它专门留在浏览器收藏夹的第一个位置平时写初稿用别的软件但到了要发公众号的时候一律拿到 Doocs MD 里过一遍再复制。1.3 适合谁用不适合谁用先说实话这套工具不是所有人的菜。适合的人公众号运营者尤其是需要高频发文的。技术作者文章里经常出现代码块、表格、数学公式。团队协作场景需要统一排版风格、减少人工调整。习惯用 Markdown 写作但发布平台是微信公众号的人。不适合的人只是偶尔发一篇个人随笔排版要求不高直接写在公众号后台可能更快。想找一个全功能笔记软件、需要双链和知识库管理的人Doocs MD 不解决这个问题。希望一键自动发布到公众号后台的人Doocs MD 目前还是复制到后台粘贴这步操作不会替你把文章发出去。认清这几点再用它才不会产生不切实际的预期。2. 三条路线跑起来在线版、本地静态版和 Docker 自部署2.1 在线版打开就用适合偶尔排版Doocs MD 有一个官方部署的在线版本地址我记得是 md.doocs.org打开就是编辑界面不需要注册登录也不需要安装任何东西。对绝大多数人来说这条路线已经足够了。在线版的好处是省事。浏览器打开直接开始写 Markdown右侧预览区同步更新。写完点复制切到公众号后台粘贴完成。没有安装过程也没有跨平台适配问题。但有几个细节需要留意。第一草稿和配置默认存在浏览器的 localStorage 里也就是说它依赖当前浏览器。如果你换了电脑或者清理了浏览器缓存之前保存过的草稿和主题设置可能会丢。第二在线版对网络有依赖虽然编辑内容本身不会频繁请求服务器但网络断开时页面加载不出来。第三如果你们团队要所有人保持同一套样式在线版各改各的配置反而容易出现每个人转出来都不太一样的情况。所以我的建议是个人偶尔用在线版完全够用重度使用或团队协作最好走本地部署。2.2 本地部署仓库拉下来就能跑适合离线与深度定制我第一次想要本地部署是因为有段时间要去一个网络不稳定的环境写稿想保证随时都能打开编辑器。Doocs MD 是开源项目仓库里有完整的代码本地跑起来并不难。如果你熟悉 Node 环境最直接的方式是把代码克隆到本地然后安装依赖、启动开发服务。大致命令是这样的git clone https://github.com/doocs/md.git cd md npm install npm run dev启动后浏览器访问本机地址就能看到一个和在线版一模一样的编辑器。这种方式适合喜欢折腾的人改代码、调试都很方便。如果你不想装 Node也可以直接把构建好的静态文件放在 nginx 或任意静态服务器下面。我试过用 Python 一条命令起一个临时静态服务python3 -m http.server 8080然后把仓库里的静态资源放进去浏览器访问http://localhost:8080同样能用。这种方式的好处是几乎没有额外依赖适合临时应急。2.3 Docker 自部署团队共用一个排版台如果你们是一个小团队希望所有人都访问同一个 Doocs MD 地址而不是各自打开一个本地页面那么部署在一台服务器上是最省心的方案。官方仓库里带有 Dockerfile我的做法是直接在服务器上构建镜像并启动容器docker build -t doocs-md . docker run -d --name doocs-md -p 8080:80 doocs-md启动后团队成员访问http://服务器IP:8080就能使用。配置文件、主题模板、草稿记录都会留在各自浏览器里但大家用的是同一个版本、同一个代码库不会出现你用的功能我没有这类版本差异。这里我想多说一句自部署不等于自动解决配置共享问题。因为浏览器 localStorage 是跟着浏览器走的各人定的自定义 CSS 依然存在各人的浏览器里。想让全团队风格统一还是要靠统一维护一份 CSS 模板让所有人手动应用到自己的浏览器配置中这一步跑不掉。2.4 部署时最容易忽略的两个问题第一个是公网部署最好带 HTTPS。虽然 Doocs MD 本身只是个编辑器不涉及什么敏感数据但在微信生态里复制粘贴这种操作经常发生在 HTTPS 页面之间。如果编辑器页面用的是 HTTP部分浏览器的剪贴板权限和安全策略会更严格可能会遇到复制不生效的情况。为了省心给服务器挂个证书没有坏处。第二个是端口别乱开。Docker 部署时如果你把 8080 端口直接暴露到公网记得在防火墙里做好限制。团队内部工具没必要完全裸奔加一层简单的 IP 白名单或者用内网部署能少很多不必要的麻烦。3. 编辑器核心能力逐项拆解Markdown 到微信样式的关键细节3.1 换行与段落微信文章的行距为什么总是不对很多刚接触 Markdown 的人最容易在换行上栽跟头。比如在编辑区里写第一行内容 第二行内容这两行之间没有空行渲染出来它们是在同一个段落里的预览区看起来就是紧挨着的两行文字。真正产生段落分隔的是空行第一段内容 第二段内容在微信后台粘贴后段落间距是否自然其实取决于编辑器渲染时生成的标签结构。Doocs MD 的处理相对可靠它会按照 Markdown 的空行语义生成对应的段落结构到了微信后台基本能保持正常的段间距。我的使用习惯是同一个小段落内部不要随便回车非要强制换行的话就在行尾加两个空格让 Markdown 把它识别为软换行这样在微信手机端预览时行间距会比硬切段落更自然。这个细节看似不起眼但对整篇文章的阅读节奏影响非常大。3.2 代码块从“黑底乱码”到高亮整齐公众号里贴代码原生编辑器几乎是噩梦。等宽字体不生效、缩进丢失、行号乱跳、背景色突兀很多人的解决办法是把代码截图。截图虽然不会乱但代码无法复制对读者很不友好。Doocs MD 里插入代码块很简单用三个反引号包裹代码并指定语言类型​python def hello(): print(Hello, 公众号!) ​右侧预览区会立刻渲染成带语法高亮的代码块背景、字体、颜色都处理好了。复制到微信后台之后大部分样式能保留但能不能长期稳定还要看你在自定义 CSS 里怎么设置字体。我的经验是给代码块指定 CSS 字体栈pre, code { font-family: SF Mono, Consolas, Liberation Mono, Menlo, monospace; }这样即使微信后台对某些网页字体的支持有限最终也会退回到系统中可用的等宽字体不会变成随意的宋体。3.3 表格公众号排版的老大难在这里是基本功微信公众号后台的表格功能非常难用插入表格之后要改宽度、调边框每一步都像在跟浏览器搏斗。但在 Doocs MD 里表格就是纯 Markdown 语法的事| 项目 | 微信原生编辑器 | Doocs MD | | ---- | ------------ | -------- | | 表格边框 | 需要手动设置 | 自动渲染带边框 | | 对齐方式 | 不稳定 | 支持左右中间对齐 | | 复制后样式 | 容易丢失 | 相对稳定保留 |复制到微信后台后表格能不能保持边框取决于主题和自定义 CSS。很多主题默认给表格加了边框但也有些主题偏简洁需要自己补样式。我在自定义 CSS 里长期加这一段table { width: 100%; border-collapse: collapse; margin-bottom: 16px; } th, td { border: 1px solid #ddd; padding: 8px 12px; text-align: left; } th { background-color: #f7f7f7; font-weight: 600; }加了之后表格在微信后台基本不会变成三无表格——无边框、无间距、无底色。3.4 数学公式KaTeX 渲染后能不能带到微信里如果你的文章偶尔需要写公式比如技术号讲到时间复杂度和概率统计Doocs MD 支持在 Markdown 里直接写 LaTeX 数学公式。行内公式这样写质能方程$E mc^2$独立公式这样写$$\sum_{i1}^n i \frac{n(n1)}{2}$$右侧预览区会通过 KaTeX 渲染出数学公式的样子。复制到微信后台时公式已经变成了 HTML 结构不是纯文本所以普通浏览器中能看到。但我踩过坑微信手机端的渲染对 KaTeX 生成的复杂结构支持并不是百分之百有的公式在电脑预览正常到了手机上就错位甚至变成乱码。我的建议是能用一两行表示的公式直接渲染后复制公式又长又多的做成整张图片插入这是最保险的方案。科学类长文章尤其要注意这一步不要省。3.5 图片本地拖入、Base64 与外链图床的取舍图片是另一个容易翻车的点。Doocs MD 支持直接把本地图片拖入编辑器它会以 Base64 形式嵌进 Markdown 源码。这种方式的好处是方便文章内容自包含复制到微信后台也经常能显示。但坏处也很明显一张几 MB 的图片转成 Base64 后会让 HTML 体积暴增很长很长的编码串会拖慢编辑器复制到微信后台时还可能因为内容过大导致部分图片显示异常。我有一次贴了七八张截图复制过去后有三张变成裂图后期修复花了大量时间。现在我常用的方案是先把图片上传到图床拿到 HTTP/HTTPS 外链然后在 Markdown 里用标准格式引用这样编辑器里的 HTML 非常干净复制到微信后台也快。如果没有自建图床上传到微信后台的素材库再引用也是可以的只是需要多一步操作。总之图片处理是 Markdown 排版里最容易被低估的环节发布前必须逐张检查。4. 主题与自定义 CSS让排版风格稳定复现4.1 内置主题只是起点Doocs MD 提供了几个内置主题切换一下右侧预览区就会换成不同的风格。默认主题胜在通用适合大部分普通文章。但在长期运营公众号的人眼里内置主题只能算起点——你可能希望正文字号是 15px 而不是默认的 16px你可能希望引用块是灰底而不是白底这些细节靠内置主题没法完全满足。插件机制里通常都有一个自定义 CSS 的入口打开之后你可以把一段完整的 CSS 粘进去覆盖预览区和最终导出样式。第一次用的时候我建议先小步调试只改一两个变量比如body的字号和行高看看预览效果再逐步加更多规则。4.2 自定义 CSS 的长线收益团队或账号如果想形成稳定的排版风格自定义 CSS 是最值得投入的环节。我自己的账号长期保持一套比较简洁的样式核心规则其实不多/* 正文基础 */ body { font-size: 15px; line-height: 1.75; text-align: justify; color: #333; } /* 标题样式 */ h2 { font-size: 20px; margin: 28px 0 14px; padding-left: 10px; border-left: 4px solid #1890ff; } h3 { font-size: 17px; margin: 22px 0 10px; } /* 引用块 */ blockquote { margin: 16px 0; padding: 12px 16px; background-color: #f8f8f8; border-left: 3px solid #ddd; color: #555; } /* 行内代码 */ code { background-color: #f0f0f0; padding: 2px 4px; border-radius: 3px; font-size: 14px; } /* 图片居中 */ img { display: block; margin: 0 auto; }这套样式用在技术文章上很舒服加了一段左边框的二级标题文章结构在手机上会非常清晰。复制到微信后台后大多数基础属性都能保留。注意不要太依赖非常复杂的 CSS 特性比如 Flex 布局、Grid 布局、CSS 变量这些在微信后台的富文本编辑环境里不一定被完整支持。老老实实用padding、margin、border、background稳定性最高。4.3 代码高亮与页面主题的配合代码高亮主题的选择也会影响整篇文章的手感。浅色页面配深色代码块视觉上会突然沉下去深色页面配深色代码块又容易和正文混在一起。我自己的偏好是代码块用浅灰底、深色字保持和正文一样的明亮度这样读者从正文滚动到代码时不会觉得刺眼。你可以在设置里尝试多个代码高亮主题找到一款和你自定义 CSS 搭配起来最顺眼的。选定之后不要频繁更换因为公众号订阅者有阅读惯性统一的风格比每一篇都换口味更重要。5. 复制到公众号之前我必走的五道检查流程5.1 先复制 HTML不要手动全选正文Doocs MD 工具栏上通常有一个复制按钮点击之后会把当前文章渲染成适合微信后台粘贴的 HTML 内容放到剪贴板。新手最容易踩的坑是在预览区里用鼠标手动全选、手动复制。这样复制的只是预览区看到的文字内容很多样式和结构会悄悄丢掉粘到微信后台之后段落和代码块全乱。所以第一准则用编辑器提供的复制按钮或者对应的快捷键不要手动框选复制。这个小习惯能避免大量奇怪的格式问题。5.2 粘贴到微信后台后的逐项检查粘贴完成后不要立刻点保存。先花三十秒从头到尾扫一遍重点看这几个地方检查项常见问题处理方式标题层级二级标题丢失左侧边框重新应用自定义 CSS 后再复制代码块背景色丢失、字体凑合给pre code加背景和等宽字体表格边框不显示或错位使用显式border样式引用块底色消失用background-colorborder-left图片裂图或空白切换到外链图片或重新上传如果在电脑端粘贴后看起来正常再进行下一步。电脑端不正常的内容手机端只会更严重。5.3 图片与外链的兜底方案图片检查单独拿出来说是因为它最容易在发布后出问题。复制过去之后如果图片显示正常恭喜可以继续。如果裂图先不要反复复制换一种图片路径方式试试。最好用的兜底方案是直接把图片上传到微信公众号素材库然后把图片插入到正文中再手动调整位置。另外如果你用的是第三方图床要确认图床是否支持 HTTPS以及是否防盗链。有些图床的图片在微信后台能预览但发布到手机上就会被拦截原因是微信内置浏览器带了 Referrer 信息刚好触发图床防盗链规则。这个坑很隐蔽发文之前最好用手机流量实测一次。5.4 手机预览的最终核实微信后台保存草稿后应该立刻点手机预览扫码在手机上把整篇从头滑到尾。我遇到过的情况是电脑上表格整整齐齐手机上一列挤成了压缩饼干代码块电脑上能横向滚动手机上直接溢出屏幕非常丑。手机预览时重点看三样东西表格宽度是否正常、代码块是否横向溢出、图片是否完整显示。发现问题就回到 Doocs MD 里调整 CSS多试一次基本能稳定。6. 高频问题排查记录那些年我踩过的坑6.1 表格边框消失或对齐错乱这个坑出现的频率最高。排查思路其实不复杂先确认 Doocs MD 预览区里表格是否正常如果预览区就不正常那是 Markdown 语法问题检查表头分隔行是否用了合法的竖线和冒号如果预览区正常但粘贴到微信后台后边框消失那就是导出时的 CSS 缺少表格边框定义。当时我排查后找到的解决办法就是在自定义 CSS 里给table、th、td显式添加边框。加完后再复制粘贴到微信后台边框就稳定了。6.2 数学公式在手机上变成乱码这个故障我记录过两次。第一次是在一篇对比算法的文章里公式比较少复制过去后手机上显示得还算正常。第二次文章里写了接近二十个公式手机上就开始出现错位个别公式直接显示成乱码字符。排查链路是先在手机端微信后台预览确认哪些公式乱码回到 Doocs MD把乱码公式单独拿出来测试最后决定不折腾了把公式区域截图上传。现在我的规则是公式超过三个就截图不给自己埋雷。6.3 浏览器缓存导致主题“改了但没生效”有段时间我改了自定义 CSS预览区却一直显示旧样式。我以为是编辑器的问题后来才发现是浏览器 localStorage 里的旧配置没有覆盖。遇到这种情况按下 F12 打开开发者工具找到站点数据存储把 Doocs MD 相关的 localStorage 清掉再重新配置一遍自定义 CSS就能正常生效。如果是在线版清空后草稿也会消失所以务必先备份你的 Markdown 源文件。6.4 多人协作时样式漂移团队里如果每个人都打开自己的浏览器各自配置样式很快会出现同一篇文章不同人转出来效果不一样的情况。我的解决办法是把自定义 CSS 存成一份共享文档团队里每个人都复制同样的一段代码。谁要调样式先在共享文档里改然后大家统一更新绝不允许各自在本地浏览器里偷偷改。更省事的做法是把这套 CSS 放到公司内部服务器的配置文件里如果能通过集中配置下发是最好的。如果做不到共享文档也足够解决大部分问题。7. 关于这套工具我最后的几句实在话实话实说Doocs MD 不是万能的。它不能替你写作也不能保证微信后台永远不会吃掉任何样式。但在我目前的公众号工作流里它是难得一直留下来的排版辅助工具。我现在发文前的固定流程是先用 VS Code 或 Typora 写 Markdown 初稿然后打开本地部署的 Doocs MD把初稿粘进去确认代码块、表格、公式、图片都正常点复制切到公众号后台粘贴再做一次手机预览最后发布。这套流程跑顺之后我基本不再为排版问题熬夜。如果你和我一样每天都要写公众号、又不想把时间耗在后台编辑器上建议花一个晚上把 Doocs MD 跑通然后把自定义 CSS 存好以后每一篇文章都能直接复用。工具本身并不复杂真正有价值的是你自己沉淀下来的那套样式和使用习惯。