Cherry Markdown 文档生成指南：五种格式导出与批量发布一步到位

Cherry Markdown 文档生成指南：五种格式导出与批量发布一步到位

【免费下载链接】cherry-markdown✨ A Markdown Editor项目地址: https://gitcode.com/GitHub_Trending/ch/cherry-markdown

在团队知识库或 API 文档的维护场景中，同一份 Markdown 往往需要同时产出 PDF 归档、HTML 上线、长图分享等不同的交付物。Cherry Markdown 作为开源 Markdown 编辑器，内置了一整套文档生成能力：五种格式从预览区一键导出，引擎部分还能脱离界面在 Node.js 中调用，支撑批量化、自动化的转换流程。

📤 能力全景：它能输出什么

所有导出入口集中在预览区实例的export方法上，也通过工具栏「导出」下拉菜单直接触达：

1. PDF—— 走浏览器打印通道，版式固定，适合归档与打印分发。
2. 长图（png）—— 把整个预览区渲染到 canvas，适合发到即时通讯群或插入幻灯片。
3. Markdown—— 导出纯源码文本，不掺任何布局信息，适合继续回版本库编辑。
4. HTML—— 输出带 DOCTYPE 与 meta 的完整 HTML5 文档，适合挂到静态站点。
5. Word—— 将排版好的 HTML 写入剪贴板，粘贴进 Word 即成，适合办公协作流。

菜单项是按需出现的：window.print不可用的环境不会列出 PDF 选项，这一点在 导出菜单钩子 中可以确认。

🚀 快速上手：三步导出第一份文档

Step 1：挂载编辑器。引入包并在容器元素上实例化，value传入你的 Markdown 正文。

Step 2：拿到导出入口。界面用户直接点工具栏「导出」菜单；开发侧则调用cherry.previewer.export，这也是 导出实现 的统一收口。

Step 3：指定格式执行。第一个参数是格式类型，第二个参数是文件名，缺省时取文档首行文本。

下面这段最小示例完成初始化并导出一份 PDF，前后各两句说明它的用途：

import Cherry from 'cherry-markdown'; const cherry = new Cherry({ el: '#editor', value: '# v2.3 发布说明\n\n新增导出能力……' }); // 格式: pdf / img / markdown / html / word，文件名缺省取首行 cherry.previewer.export('pdf');

代码跑完会弹出系统打印对话框，选择「另存为 PDF」即得产物；界面在导出结束还会派发cherry:export:done自定义事件，方便你挂监听做后续自动化。

🧭 五种格式怎么选：一张表看懂

导出格式	扩展名	适合谁	一句话提醒
PDF	.pdf	归档、打印、对外交付	产物由浏览器打印对话框生成，记得选「另存为 PDF」
长图	.png	群分享、截图引用	文档里音频/视频标签会被剔除，超长文档图很大
Markdown	.md	版本库、再编辑	纯源码，样式与排版不随文件走
HTML	.html	静态站、内网发布	文件本身不含编辑器样式，需自行引用 CSS
Word	粘贴保存	Office 协作、正式评审	走剪贴板，需在 Word 里手动粘贴

选型时记住两条：给机器和人共同消费的场景优先 Markdown 加 HTML 双份输出；给外部客户的一次性交付物用 PDF 或长图更省心。

🎨 按团队规范定制输出

定制分两层。第一层是引擎参数：makeHtml的returnType决定返回字符串还是 DOM 节点；Engine 还支持在钩子链上包装makeHtml，统一改写产出。第二层是自定义模板：HTML 导出只给出文档骨架，标题、版本、页脚、内联样式都由你的模板函数拼装，这正好承接「动态内容注入」的需求。

配置点	说明
returnType	'string'返回 HTML 文本，便于二次拼接
模板函数	自行组装 DOCTYPE、meta、title 与团队样式
版本注入	从package.json或环境变量读取，写入页脚
样式策略	链接构建产物cherry-markdown.min.css或内联定制 CSS

下面用模板函数注入版本号与构建时间，解决「每份导出物都带可追溯元信息」的问题：

const engine = new CherryEngine(); const html = engine.makeHtml(md, 'string'); // 模板函数注入版本与构建时间，再写入目标文件 const out = tpl(html, { v: pkg.version, t: new Date().toISOString() }); fs.writeFileSync(`doc-v${pkg.version}.html`, out);

模板里可以放任何静态内容，但注入值建议只来自构建上下文，不要在页面里塞运行时脚本，以免导出物变成统计与埋点载体而引入风险。

⚙️ 批量与自动化：接入你的工作流

批量转换脚本

批量场景不需要再挂编辑器，直接复用同一个CherryEngine实例遍历目录即可，实例复用能避免每篇文档重复加载依赖：

const engine = new CherryEngine(); for (const f of files) { fs.writeFileSync(`dist/${f}.html`, tpl(engine.makeHtml(read(f)))); } // 按 10 篇一批处理，批间调用 gc 控制内存

性能上抓三个要点：引擎实例全程复用、按批处理并在批间释放引用、单篇转换本身有缓存可命中重复句子。文档量从几十篇涨到几百篇时，耗时增长基本保持线性，不会出现数量翻倍耗时也翻倍的情况。

CI/CD 流水线触发

把上面的脚本放进仓库，再让流水线在主干合入后自动执行转换。GitLab 的写法大致如下，产物作为 artifact 保留一周便于回查：

docs: stage: build script: [yarn install, node scripts/batch-export.js docs dist] artifacts: { paths: [dist] } only: [main]

产物发布与版本管理

发布环节建议把dist同步到静态服务或对象存储，并保留可回滚的版本档案：以「时间戳 + 内容哈希」作为版本 ID，每次构建把 Markdown 源与产出物一起归档，回滚就是切换到上一个版本 ID 重新发布。哈希让重复内容的构建天然去重，也方便在评审里证明「本次产物与源一一对应」。

🛟 常见问题与避坑指南

导出 PDF 为什么弹出的是打印对话框

这是设计使然：exportPDF依赖window.print生成矢量级 PDF，你在对话框里选「另存为 PDF」即得目标文件。好处是字体与分页完全交给系统处理，坏处是无法在无头环境直接跑，无头场景请走makeHtml加第三方转 PDF 的组合。

长图导出后图片缺失或发虚怎么办

预览区默认懒加载图片，导出前会把未加载的懒加载地址替换回真实 src，所以「缺图」多发生在跨域图片上——canvas 被污染后对应区域会空白，优先使用同域或本地图片。发虚则是 canvas 按当前布局宽度渲染所致，导出前把窗口拉宽通常能改善。

点了导出 Word 却没有文件下载

Word 导出的实现是「写剪贴板」而非生成文件：浏览器首次使用会请求剪贴板权限，授权后界面出现提示，你切到 Word 粘贴即完成。mermaid 图、公式等元素在导出前已被预处理成位图，粘贴后基本不会样式漂移。

一份 Cherry Markdown 实例即可覆盖五种格式的单篇导出，makeHtml再把它延伸到批量与流水线场景。下一步：按「快速上手」三步先导出一份 PDF，跑通后再把批量脚本接进你的 CI。

【免费下载链接】cherry-markdown✨ A Markdown Editor项目地址: https://gitcode.com/GitHub_Trending/ch/cherry-markdown