返回总教程

baoyu-markdown-to-html 把 Markdown 渲染为内联样式 HTML，目标是适配微信公众号等不方便加载外部 CSS 的平台。它不是通用 Markdown 清洗器，也不会替你判断文章事实、版权或图片是否可公开。

本文基于固定提交源码核对；案例是操作示例，不是公众号账号、在线发布或浏览器实测。写作过程中未执行安装、转换、渲染或发布。

一、适用场景与边界

适合已经完成内容和排版的中文文章：需要选择主题色、代码高亮、表格、图片、脚注、提示块，或把普通外链集中成文末引用。输出 HTML 与输入 Markdown 同目录，便于把它复制到公众号编辑器或交给其他发布流程。

它不是“把任意 Markdown 变成浏览器完全等价页面”的保证。微信编辑器可能再次清洗 HTML；外链图片需要网络访问；Mermaid 依赖 Chrome/Chromium/Edge 通过 CDP 渲染，缺浏览器时会退回 <pre class="mermaid">，转换仍可能成功但不再是图片。PlantUML、数学、脚注和自定义主题也应在目标平台预览。

中文文件还有一个前置分支：若检测到 CJK 且Markdown 排版可用，技能会询问是否先整理格式。这是用户选择，不应自动把原稿改成另一份内容。标题默认从 frontmatter 或首个 H1/H2 推断，并默认移除正文第一个标题；若需要保留必须明确使用 --keep-title。

二、按需安装与固定版本

本系列已核实 skills CLI 1.7.2 的按技能参数，按需安装命令是：

1
npx skills add jimliu/baoyu-skills --skill baoyu-markdown-to-html --agent codex

该命令安装的是当前仓库内容，最新安装不等于固定快照。本文核对的来源固定在提交 1567581c26ec29f4216c6e6835415bf30343b0e3。要重现同一行为，应把该提交的完整技能目录放入项目，并检查 scripts/package.json 中的 baoyu-md 与 baoyu-chrome-cdp 依赖。

运行时需要 Bun 或可用的 npx -y bun；源码帮助输出已核实使用：

1
npx -y bun "{baseDir}/scripts/main.ts" "article.md" --theme grace

{baseDir} 是技能目录，文件路径可为绝对路径。不要把 --theme 当作 Agent 的自然语言主题名；脚本支持 default、grace、simple、modern。安装前无需执行发布或登录，也不需要公众号凭证。

三、输入、输出与选项

输入必须是 .md 且存在。输出固定为同目录的同名 .html；例如 article.md 生成 article.html。如果 HTML 已存在，脚本先改名为 article.html.bak-YYYYMMDDHHMMSS，再写新文件。这个备份是输出冲突保护，不代表输入 Markdown 有备份，重要改动前仍应保存版本。

常用选项来自源码帮助：

需求 参数
主题 `—theme default\ grace\ simple\ modern`
主色 --color red 或十六进制
字体 `—font-family sans\ serif\ serif-cjk\ mono` 或 CSS 值
字号 --font-size 14px 到 18px
代码主题 --code-theme NAME
Mac 风格代码框 --mac-code-block / --no-mac-code-block
行号 --line-number
统计 --count
图片图注 `—legend title-alt\ alt-title\ title\ alt\ none`
保留首标题 --keep-title
外链文末引用 --cite
Mermaid --mermaid-theme、--mermaid-scale、--mermaid-width、--mermaid-bg
禁用 Mermaid --no-mermaid

--cite 默认关闭，只在用户明确要求“底部引用”等场景启用。普通外链变成编号上标并集中到 引用链接；微信公众号文章链接保持直接链接，链接文字本身就是 URL 时也保留行内形式。不要为了“看起来更像论文”自行打开该选项。

四、可复制的自然语言 Agent 请求

1
2
3
4
5
6
7
请使用 baoyu-markdown-to-html 转换 [Markdown绝对路径]。
先检查中文内容；如果建议先用 baoyu-format-markdown，先询问我，不要自动改原稿。
主题使用 [grace/modern/default]，主色 [颜色]，默认移除正文首个标题。
只有我明确要求时才启用文末外链引用；本次 [启用/不启用] --cite。
检查本地图片、代码块、表格、脚注和 Mermaid；缺少 Chrome 时如实报告回退结果。
输出同目录 HTML，不发布。若旧 HTML 存在，保留脚本生成的备份路径。
最后报告 title、htmlPath、backupPath、图片处理和 Mermaid 缓存结果。

如果文章是技术教程：

1
2
3
请保留代码原文和 fenced language，使用清晰的代码主题与行号。
不要把代码中的链接搬到文末引用，不要移除图片 alt 文本。
如果首个 H1 已在 frontmatter 中作为标题，默认不重复显示；除非我要求使用 --keep-title。

五、操作案例：将中文教程交付给公众号编辑

假设 Obsidian 中已有 deploy-guide.md，包含 frontmatter、二级标题、Shell 代码、两张本地截图和一个 Mermaid 流程图。目标是交给编辑预览，而不是直接发布。下面展示核实后的操作顺序，不声称已经运行这个文件。

  1. 先检查输入。 确认文件扩展名为 .md，图片相对 deploy-guide.md 的路径存在，Mermaid 围栏没有被代码示例嵌套破坏。
  2. 处理中文预检查。 若 Markdown 强调标记夹着中文标点，询问是否先用排版技能。接受时使用排版后的副本；拒绝时保留原稿并记录选择。
  3. 选择主题和标题策略。 grace 用于更柔和的卡片式呈现，simple 适合留白，modern 可配自定义主色。frontmatter 已有 title 时默认以它为标题，正文首个 H1 通常移除，避免出现两份标题。
  4. 转换 Mermaid。 有 Chrome 时按代码、主题、缩放、宽度、背景计算缓存键，PNG 写入 imgs/.mermaid-cache/。检查 JSON 结果里的 mermaidImages，关注是新渲染还是命中缓存。
  5. 检查图片与外链。 本地图片会解析为 HTML 图片；远程图片可能先在临时目录处理，输出 HTML 中保留可访问来源。选择 --cite 后只移动普通外链，不应期待微信链接也出现在文末。
  6. 对照 HTML。 打开生成文件，检查标题、摘要、代码、表格、图片宽度和引用段。再粘贴到测试公众号草稿或本地 HTML 预览环境；这是内容交付前检查，不是发布授权。
  7. 回写 Obsidian 链接。 Obsidian 继续以 Markdown 为源文件，HTML 作为交付产物。不要让发布脚本反过来把 HTML 当成下一次 Markdown 输入，否则容易积累内联样式和重复标题。

六、主题、配置与渲染细节

EXTEND.md 按项目、XDG、用户目录查找，第一个命中生效；没有就用默认值。支持默认主题、自定义 CSS 变量、代码样式和 Mermaid 默认值。CLI 显式参数优先于配置。若本技能没有 default_theme，流程还会检查 baoyu-post-to-wechat 的同名配置，作为跨技能回退；不要只在一个文件里找不到主题就马上询问用户。

Mermaid 相关参数可在配置或命令行表达：主题支持 default、forest、dark、neutral、base；缩放为正数且不大于 4；宽度为正整数；背景可用 white、transparent 或十六进制颜色。没有 Chrome 时仍输出 HTML，但 Mermaid 会以 <pre> 回退，不应在交付报告里写“图已渲染”为真。

源码返回 JSON，包含标题、作者、摘要、htmlPath、可选 backupPath、内容图片与 Mermaid 图片列表。错误日志写到 stderr，JSON 写到 stdout；若用脚本串接，应分别读取，不要把日志文本当作 JSON。

七、验收清单

  • [ ] 输入 Markdown 路径存在且扩展名正确，原文件保持未改。
  • [ ] 标题只出现一次，--keep-title 的选择与预期一致。
  • [ ] frontmatter 的 title、author、description、图片路径均正确。
  • [ ] HTML 输出路径准确，旧 HTML 有备份时路径已记录。
  • [ ] 代码、表格、脚注、提示块、图片和外链按预期渲染。
  • [ ] Mermaid 报告明确写出渲染、缓存或 <pre> 回退状态。
  • [ ] --cite 只有在明确要求时开启，微信链接规则符合预期。
  • [ ] Obsidian 保留 Markdown 源，Hexo 或公众号只接收经过预览的 HTML。

八、排错

HTML 有了但 Mermaid 是代码块。 先检查 Chrome/Chromium/Edge 和 CDP 渲染条件；这是源码允许的成功回退，不是正文转换完全失败。若发布平台不支持 <pre class="mermaid">，应安装或指定可用浏览器后重跑，并检查缓存目录。

标题重复。 这是默认删除首标题的边界：如果使用了 --keep-title，或 frontmatter 与正文各有一个标题，按目标平台选择其一。不要在 HTML 上手工删除后又重复转换源 Markdown。

远程图片不显示。 HTML 可能保留原始 URL，目标平台会受防盗链、HTTPS、网络策略影响。优先使用有授权的本地图片并检查相对路径；不要把图片下载到技能源码目录。

主题没有按配置生效。 按优先级检查 CLI、当前技能 EXTEND.md 和发布技能的跨技能配置。显式 --theme 后应以命令为准。

文末引用多了或少了。 核对是否真的传了 --cite，并按规则区分普通外链、微信文章链接和“链接文字等于 URL”的情况。

九、相关技能与固定来源

固定源码提交：1567581c26ec29f4216c6e6835415bf30343b0e3。