首页 / 全部技能 / 文档与知识 / baoyu-markdown-to-html
English (EN)简体中文 (ZH)日本語 (JA)
文档与知识 · JimLiu/baoyu-skills

baoyu-markdown-to-html

Converts Markdown to styled HTML with WeChat-compatible themes. Supports code highlighting, math, Mermaid (rendered to PNG via headless Chrome), PlantUML, footnotes, alerts, infographics, and optional bottom citations for external links. Use when user asks for "markdown to html", "convert md to html", "md 转 html", "微信外链转底部引用", or needs styled HTML output from markdown.

L4 高权限 · 分级授权与审计V1 已固定执行命令联网读写文件Dual-pass Audit
Author JimLiuGitHub JimLiu/baoyu-skills ↗Stars 25926License MIT（仓库根 LICENSE，Copyright (c) 2026 Jim Liu；GitHub API spdx_id=MIT）Commit 1567581c26
管控等级描述 skill 的能力与建议配套的管控措施，不代表质量或安全认证，也不表示可用或不可用。是否使用由用户和管理者决定。不同 agent 宿主对权限的约束各不相同，请勿假定宿主一定会提供安全兜底。第三方 skill 版权归原作者，使用风险由使用者自行承担。

1实现原理 · 为什么它能做到

主体是本地 Bun 脚本 + 仓库内共享包：渲染用 baoyu-md（marked/juice/highlight.js 管线），Mermaid 出图用 baoyu-chrome-cdp 的 headless Chrome 渲染器。

skills/baoyu-markdown-to-html/scripts/main.ts
import { closeRenderer, renderMermaidToPng } from "baoyu-chrome-cdp/mermaid";
依赖在 scripts/package.json 声明并由 bun.lock 锁定（baoyu-md ^0.1.1、baoyu-chrome-cdp ^0.1.1）；脚本本身只做参数解析、mermaid 预处理、图片占位符改写、落盘与 JSON 汇报。

Mermaid 代码块被渲染成本地 PNG（headless Chrome + CDP），带内容哈希缓存；Chrome 缺失或渲染失败则回退为 <pre class="mermaid">，转换整体不失败。

skills/baoyu-markdown-to-html/SKILL.md
Code blocks fenced as ` ```mermaid ` are rendered to PNGs via headless Chrome (CDP) and cached at `imgs/.mermaid-cache/mermaid-<hash>.png`.
缓存键包含代码/主题/scale/目标宽度/背景/mermaid 版本；依赖包内自带 mermaid.min.js（本地读取，无 CDN 拉取）。

PlantUML 代码块默认由公共 PlantUML 服务渲染：管线注册了 markedPlantUML，默认 serverUrl 指向 plantuml.com，因此图表源码会出网到第三方服务。

packages/baoyu-md/src/extensions/plantuml.ts
serverUrl: options.serverUrl || `https://www.plantuml.com/plantuml`,
注册点在 packages/baoyu-md/src/renderer.ts（`markedPlantUML({`），而本 skill 的 renderMarkdownDocument → initRenderer 会经过该渲染器（packages/baoyu-md/src/document.ts 调用 initRenderer）。SKILL.md 也把 PlantUML 列为支持特性，故这是默认可用路径。

文档里的远程图片会被下载到临时目录，再在 HTML 里改写为带 data-local-path 的 img 标签（便于下游平台/客户端再上传）。

packages/baoyu-md/src/images.ts
await downloadFile(imagePath, localPath);
触发条件：图片源以 http(s):// 开头（`if (imagePath.startsWith("http://") || imagePath.startsWith("https://")) {`）；本 skill 只在存在远程图片时才建临时目录（main.ts 的 hasRemoteImages 分支）。下载走 node:http/https，UA 为 Mozilla/5.0，跟随 301/302。

输出与备份纪律：HTML 写回与源文件同目录同名（.html），已存在则先重命名备份，最后把结果作为 JSON 打到 stdout。

skills/baoyu-markdown-to-html/scripts/main.ts
backupPath = `${finalHtmlPath}.bak-${formatTimestamp()}`;
SKILL.md 写明冲突处理：`Backup: /path/to/article.html.bak-YYYYMMDDHHMMSS`，JSON 输出含 htmlPath/backupPath/contentImages/mermaidImages 等字段。

主题/颜色/字号/引用模式是外部可配的显式选项；--cite 会把普通外链收成底部编号引用，但微信自家链接保持原位。

skills/baoyu-markdown-to-html/SKILL.md
`https://mp.weixin.qq.com/...` links stay as direct links and are not moved to the bottom.
主题解析顺序：CLI --theme > 本 skill EXTEND.md default_theme > baoyu-post-to-wechat EXTEND.md default_theme（跨 skill 回退）> 询问用户；--cite 默认关闭（SKILL.md：'Default: Off. Do not ask by default.'）。

流程前置会做中文检测，并在用户同意时先调用 baoyu-format-markdown 清洗（修 CJK 加粗解析失败与中英间距）。

skills/baoyu-markdown-to-html/SKILL.md
**If user agrees**: Invoke `baoyu-format-markdown` skill to format the file, then use formatted file as input.
Step 0 仅在输入含 CJK 时触发；用户拒绝则用原文件继续——这是一处跨 skill 的可选调用，会引入 baoyu-format-markdown 自身的行为（含其 npx 依赖）。

配置面是 EXTEND.md（默认主题、自定义 CSS 变量、代码块样式、mermaid 主题/scale/背景），三级路径首个命中即用，未找到则用默认值、不做首次安装流程。

skills/baoyu-markdown-to-html/SKILL.md
**EXTEND.md supports**: default theme, custom CSS variables, code block style, mermaid defaults (`mermaid_theme`, `mermaid_scale`, `mermaid_background`).
与其他 baoyu skill（image-gen/wechat 会强制首次配置）不同，本 skill 无 EXTEND.md 也可直接工作。

2核心能力

01Markdown → 内联 CSS 的样式化 HTML（四套主题 default/grace/simple/modern + 13 个颜色预设 + 字体/字号选项）
02Mermaid 渲染为本地 PNG（headless Chrome/CDP + 哈希缓存 + 失败回退 `<pre class="mermaid">`）
03外部链接转底部引用（--cite，可选），微信链接与纯 URL 链接除外
04图片占位符改写与本地路径回报（contentImages 含 placeholder/localPath/originalPath）
05丰富的 Markdown 方言支持：GFM 表格、代码高亮、alert、脚注、ruby 注音、数学、PlantUML
06结果以 JSON 汇报（htmlPath/backupPath/contentImages/mermaidImages），便于 agent 继续下游流程

3外部依赖

KindDependency / Endpoint
packagebaoyu-md（npm，仓库 packages/ 内的共享包；marked/juice/highlight.js/remark 管线）
packagebaoyu-chrome-cdp（npm，仓库 packages/ 内共享包；提供 CDP 与 mermaid 渲染器）
networkPlantUML 公共渲染服务（默认 serverUrl，图表源码经 GET 送出）
networkMarkdown 中出现的任意 http(s) 图片主机（下载到本地临时目录）
cli本地 Chrome/Chromium/Edge（headless 渲染 Mermaid；缺失则回退）
clibun（首选运行时；无 bun 时 npx -y bun）

4管控建议与判定依据

建议配套管控措施
面向 Agent
分级或逐次授权，建议在沙箱运行
面向管理者
审批流程、可回滚、全程审计
判定依据（文件路径与关键语句摘要）
  • scripts/: 执行本地脚本或命令: bun {baseDir}/scripts/main.ts <markdown_file> [--theme …] [--cite] [--merma
  • 网络端点: 声明外部网络访问: https://www.plantuml.com/plantuml（默认，仅当文档含 plantuml 代码块：图表源码作为 URL 编码体发出，返回
  • 本地工作目录: 文件读写与工件输出: 与输入同目录同名的 .html（覆盖前重命名为 .html.bak-YYYYMMDDHHMMSS）
审计说明： 。三段自证：① 判级对象是本 skill 目录（SKILL.md + scripts/main.ts + main.test.ts + bun.lock；共享包逻辑在仓库 packages/ 内，且被 SKILL.md 作为官方支持特性声明）；② 目录内自身行为＝本地脚本 + 本地 headless Chrome 出图 + 本地写盘（.html 与 imgs/.mermaid-cache/*.png，覆盖前备份）；③ 判橙的关键＝按 SKILL.md 执行时用户内容会出网到外部服务后端：SKILL.md 明列 PlantUML 支持，其渲染经依赖包注册的 markedPlantUML 走默认公共渲染服务 `serverUrl: options.serverUrl || `https://www.plantuml.com/plantuml`,`（图表源码外发），另 `const protocol = url.startsWith("https://") ? https : http;` 会把文档里的任意 http(s) 图片下载到本地。无凭证读取、无逆向/冒充、无 TLS 降级、Chrome 未禁用沙箱也未打反检测补丁（对比同仓 post-to-wechat/post-to-weibo 的 `--disable-blink-features=AutomationControlled`，本 skill 的 Chrome 启动参数里没有），故不升红；若文档既无 plantuml 块也无远程图片，则行为退化为纯本地（蓝级）。

5第二遍独立确认

  • [ok] 共享包依赖与版本锁定 — scripts/package.json 仅声明 baoyu-md ^0.1.1 与 baoyu-chrome-cdp ^0.1.1，bun.lock 有锁定条目；两包在本仓 packages/ 内有源码（psync 可读），非黑盒。
  • [ok] Mermaid 本地渲染且无 CDN — packages/baoyu-chrome-cdp/src/mermaid.ts 从包内 assets 读 mermaid.min.js（`if (fs.existsSync(path.join(candidate, "mermaid.min.js"))) return candidate;`）并注入本地页面，无外部脚本地址。
  • [ok] PlantUML 默认出网到公共服务器（判橙依据） — packages/baoyu-md/src/extensions/plantuml.ts 默认 serverUrl=https://www.plantuml.com/plantuml；注册于 renderer.ts 的 markedPlantUML()；本 skill 的 document.ts 路径调用 initRenderer，SKILL.md 亦将 PlantUML 列为支持特性。
  • [ok] 远程图片会被真实下载 — packages/baoyu-md/src/images.ts 的 downloadFile 使用 node:http/https + Mozilla/5.0 UA 下载并跟随 301/302；本 skill 在 hasRemoteImages 时建临时目录承接，HTML 内保留原 URL 并附 data-local-path。
  • [ok] 本 skill 的 Chrome 启动参数无安全降级/反检测项 — packages/baoyu-chrome-cdp/src/index.ts 的 launchChromeBase args 仅为 --remote-debugging-port/--user-data-dir/--no-first-run/--no-default-browser-check（+headless）；全包 grep bypass/detect/webdriver/stealth 零命中，无 --no-sandbox。
  • [ok] 无凭证读取 — 本目录 token 扫描 process.env/API_KEY/TOKEN/SECRET/.env 零命中；仅 EXTEND.md 偏好文件（路径在 SKILL.md 明列）。
  • [ok] mermaid securityLevel: loose 的渲染面 — packages/baoyu-chrome-cdp/src/mermaid.ts 以 `mermaid.initialize({ startOnLoad: false, theme: …, securityLevel: "loose" })` 渲染文档中的图表代码，属本地无头浏览器内执行用户文档内容；已在 injection_surface 与 verdict.risks 标注。
  • [ok] 『微信友好』定位与实际产物 — CSS 由 juice 内联（baoyu-md 依赖含 juice ^11.0.1），图片输出 localPath 供下游上传；--cite 默认关闭，与 SKILL.md 'Default: Off. Do not ask by default.' 一致。

6结论

  • 面向公众号的实用主义：CSS 内联 + 图片本地路径回报 + 外链转底部引用，直接解决微信编辑器粘贴掉样式、外链不可点的问题。
  • Mermaid 走本地 headless Chrome 并做内容哈希缓存，无云渲染依赖，重复转换不重复出图。
  • 降级路径完备：没有 Chrome 或渲染失败时回退 `<pre class="mermaid">`，转换整体不失败。
  • 覆盖的 Markdown 方言广（GFM/高亮/alert/脚注/ruby/数学/PlantUML），且有 4 主题 + 13 预设色 + 字体字号选项。
  • 输出可被程序消费：JSON（htmlPath/backupPath/contentImages/mermaidImages）让后续 skill（如 post-to-wechat）能直接接手。
    • 适合： 适合把写好的 Markdown 文章转成可直接粘贴进微信公众号编辑器的样式化 HTML，或作为 post-to-wechat 的渲染前端；也适合需要本地渲染 Mermaid/公式并保留本地图片路径的离线写作流。
    不适合： 不适合处理含内部架构图（PlantUML）或来源不明图片链接的敏感文档（默认会外发/外取）；不适合要求像素级可控的网页排版（输出的是公众号友好的内联样式 HTML，而非站点主题）；也不适合无 Chrome 且依赖 Mermaid 出图的场景（会静默退化为代码块）。
    Install Agent-Ready
    ① Verified Mirror 2026-09-15
    Option A · Direct DownloadDownload baoyu-markdown-to-html.tar.gz
    sha256: 548cfdf151b66892…
    Option B · Copy Guide for Agent
    install.json
    agent 读 JSON 指南后会自动从本站下载安装，无需更多说明。
    ② Upstream GitHub
    GitHub Repo ↗
    Pinned to commit 1567581c26.