最近写项目交接文档，我又踩了一遍老坑。
本地用 VS Code 写 Markdown 体验是不错，但一涉及到公式、流程图，预览插件就各种不兼容； teammate 用 Mac，我用 Windows，换台电脑格式就偏；最后要导 PDF 给甲方，又得折腾 Pandoc 和 LaTeX，字体还总缺失。一来二去，半天没了。
这次我干脆把整套流程迁到了浏览器里，试了两周，居然意外顺手。
一、我需要的其实就三件事
写技术文档这件事，拆开来不外乎：
- 一个能实时预览的 Markdown 编辑器；
- 支持代码高亮、公式、Mermaid 流程图；
- 导出样式可控的 PDF，方便发给别人。
之前我本地装了三四个插件才凑齐这些功能，现在发现有个在线 Markdown 编辑器直接把这些打包了。
打开页面，左边写源码，右边实时渲染，所见即所得。代码块会自动高亮，写架构图的时候直接插 Mermaid 语法，不需要再切到别的画图工具。
我这张图里其实是一份项目梳理文档，表格、列表、代码块混排，右侧预览没有错位。对于写接口说明或者部署手册来说，这种同步预览能少返工很多次。
二、从 Markdown 到 PDF，我之前卡在哪
本地转 PDF 最让我头疼的是排版不可控。
比如用浏览器打印，页边距忽大忽小；用 Pandoc 转，中文字体要单独配置；用某些在线转换，公式又变图片，分辨率一塌糊涂。
这次我试了一个专门的 Markdown 转 PDF 工具，可以调主题、纸张大小、方向和页边距，字号也能拉滑块改。关键是公式和代码高亮能完整保留，不会转成低清图。
设置完直接点导出，出来的 PDF 就是标准 A4，放进邮件附件或者项目文档库都够用。
三、一个具体的写文档流程
我现在写技术文档大致是这样的：
- 先在在线编辑器里把大纲和正文敲完，边写边看效果；
- 遇到复杂流程就插入 Mermaid 代码，实时渲染出来；
- 需要给外部人员时，整篇粘贴到 Markdown 转 PDF 工具里，选个主题、调下边距，导出即可。
整个流程没有本地依赖，换电脑、换系统都不影响。上次我在客户现场临时改文档，直接登录账号就能接着写，不用再配环境。
四、适合什么场景
这套流程我觉得比较适合：
- 接口文档、部署手册这类需要频繁修改的技术文档；
- 需要插入公式或流程图的方案文档；
- 最后要输出 PDF 归档或外发的场景。
当然，如果你写博客用静态站点生成器，或者团队有统一的文档平台，那另说。但对个人和小团队来说，浏览器里完成 “写 → 看 → 导出” 整条链路，确实省了不少配置时间。
五、顺便提一下
这两个工具我是在工具派上找到的，地址是 https://gjupai.com/ 。同一个站里还有 JSON 格式化、SQL 格式化、表格数据清洗之类的小工具，写文档时顺手查点数据也挺方便。
项目地址：https://gjupai.com/
最后补充一句：在线工具的好处是即用即走，但重要文档还是记得本地备份一份。我一般会同时导出 Markdown 源文件和 PDF，双保险。