baoyu-markdown-to-html 适合已经完成内容与排版的 Markdown 文章，需要生成有样式的 HTML 文件。它支持代码、公式、表格和图表等内容，并提供适合公众号编辑场景的样式；转换文件本身并不会替你登录或发布到平台。
安装与调用
在项目目录的终端运行下面的命令，只安装这个 Skill 到 Claude Code：
npx skills add jimliu/baoyu-skills --skill baoyu-markdown-to-html -a claude-code
需要 Node.js 和可用的 npx。若使用 Codex，把 -a claude-code 换成 -a codex；在对话里明确要求使用 baoyu-markdown-to-html 并附上材料，不把终端安装命令当成任务提示。其他客户端应使用自身的技能选择入口。
用一篇小稿验证转换规则
准备包含标题、段落、表格和图片的 Markdown。若文章中英混排问题明显，可先完成排版再转换；不要在转换阶段同时要求大量改写。可以这样输入：
使用 baoyu-markdown-to-html 转换 article.md。
主题 grace，主色 green，保留正文第一个标题，普通外链移到文末引用。
不修改正文内容。输出后给 HTML 路径、图片依赖与 Mermaid 是否成功渲染的结果。
只生成本地文件，不发布。
对应的脚本参数包括 --theme grace --color green --keep-title --cite。需要从实际安装目录运行 scripts/main.ts，运行时优先 Bun，也可使用 npx -y bun。不加 --keep-title 时默认移除正文第一个标题，用元数据中的标题承担相应位置。
特别检查图片和图表
输出通常与输入同目录，例如 article.md 对应 article.html；已有 HTML 会先生成带时间戳的备份。读取返回结果中的 htmlPath、图片列表和可能的备份路径，比只看终端出现“成功”更能确定实际产物。
--cite 默认关闭，开启后把普通外部链接转成编号并收集到文末；公众号原文链接以及直接显示 URL 的裸链接有单独处理规则，不应假设所有链接都会转换。需要这种版式时，在预览中检查编号、链接文字和引用条目是否对应。
Mermaid 图通过无头浏览器渲染为本地 PNG，并缓存到 imgs/.mermaid-cache/。本机没有 Chrome、Chromium 或 Edge，或渲染失败时，文章转换仍可能完成，但图表退回代码块。看到 HTML 文件不等于所有图都已成功生成。
最后在浏览器及目标平台预览，核对表格横向空间、代码可读性、图片路径和公式。复制 HTML 到平台编辑器后样式可能变化，应以实际阅读画面为准。保留 Markdown 作为后续修改源，避免只改 HTML 后再转换把修改覆盖掉。
发公众号前做一次小规模预演
准备一篇同时含有二级标题、外链、表格、本地图片和 Mermaid 图的短稿，先用你打算正式采用的主题、颜色和引用选项转换。用浏览器打开输出 HTML，确认首个标题是否因默认规则消失、脚注编号是否和链接对应、图表究竟是 PNG 还是代码块。若 Mermaid 回退，先确认浏览器可执行文件是否可用，再决定改用静态图片或保留文本，不能只看转换命令退出成功。
同样的 HTML 粘到目标编辑器后再检查一次。目标平台可能改写样式，表格横向滚动、代码高亮和外链标记尤其容易与本地预览不同。若发布平台要求上传图片，本地相对路径只是引用，不代表图片已经随 HTML 上传。正式文章通过预演后才批量转换其他稿件，并保留 Markdown 源文件与备份；下次改稿从 Markdown 重新生成，避免两个版本越改越不一致。
把转换结果当成预览关口
把 HTML 转换当作“发布版本的预览关口”。Just Jason 的文章流程先完成写作、图片、压缩和 Markdown 整理，再用 baoyu-markdown-to-html 生成公众号格式，最后才发布。这样可以在发布前单独检查标题层级、引用块、代码和图片。拿到 HTML 后打开真实预览，不要只看文件生成成功；图片若仍指向本地路径，微信公众号读者就看不到。发布端若还会重写样式或图片地址，再按发布端最终预览复查一次。
若连第一份示例文档都不能转换，先看报错发生在解析 Markdown 前，还是渲染图片时。历史上有用户在新装环境遇到 baoyu-chrome-cdp/mermaid 导入失败；问题指向当时发布的依赖包与仓库源码不一致。该 issue 已关闭，当前应先更新到维护者推荐版本，再用只含标题和一张图片的小文件复现；不要在依赖未加载时反复修改正文排版。