Docs & Knowledge · JimLiu/baoyu-skills

baoyu-markdown-to-html

Name: baoyu-markdown-to-html
Author: JimLiu/baoyu-skills

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 High-Privilege · Graded auth & full auditV1 Commit-PinnedExecute CommandNetwork AccessWrite FileDual-pass Audit

Control levels describe skill capabilities and suggested control measures; they do not represent quality or safety certifications, nor do they dictate usability. Usage decisions rest entirely with users and administrators. Different agent hosts apply varying constraints; do not assume hosts provide automatic protection. Third-party skill copyrights belong to their original authors. Use at your own risk.

1How It Works & Mechanism

The core consists of local Bun scripts and shared packages within the repository: rendering uses baoyu-md (marked/juice/highlight.js pipeline), and Mermaid diagram rendering uses the headless Chrome renderer in baoyu-chrome-cdp.

skills/baoyu-markdown-to-html/scripts/main.ts

import { closeRenderer, renderMermaidToPng } from "baoyu-chrome-cdp/mermaid";

Dependencies are declared in scripts/package.json and locked by bun.lock (baoyu-md ^0.1.1, baoyu-chrome-cdp ^0.1.1); the script itself only handles argument parsing, mermaid preprocessing, image placeholder rewriting, file writing, and JSON reporting.

Mermaid code blocks are rendered into local PNGs (headless Chrome + CDP) with content hash caching; if Chrome is missing or rendering fails, it falls back to <pre class="mermaid">, ensuring overall conversion does not fail.

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`.

The cache key includes code, theme, scale, target width, background, and mermaid version; the dependency package includes its own mermaid.min.js (read locally, no CDN fetches).

PlantUML code blocks are rendered by default via a public PlantUML service: the pipeline registers markedPlantUML, whose default serverUrl points to plantuml.com, meaning diagram source code is sent outbound to a third-party service.

packages/baoyu-md/src/extensions/plantuml.ts

serverUrl: options.serverUrl || `https://www.plantuml.com/plantuml`,

The registration point is in packages/baoyu-md/src/renderer.ts (`markedPlantUML({`), and renderMarkdownDocument → initRenderer in this skill passes through this renderer (packages/baoyu-md/src/document.ts calls initRenderer). SKILL.md also lists PlantUML as a supported feature, making this the default available path.

Remote images in the document are downloaded to a temporary directory and rewritten in the HTML into img tags with data-local-path (facilitating re-uploading by downstream platforms/clients).

packages/baoyu-md/src/images.ts

await downloadFile(imagePath, localPath);

Trigger condition: image sources starting with http(s):// (`if (imagePath.startsWith("http://") || imagePath.startsWith("https://")) {`); this skill creates a temporary directory only when remote images exist (the hasRemoteImages branch in main.ts). Downloads use node:http/https with a Mozilla/5.0 User-Agent and follow 301/302 redirects.

Output and backup discipline: The HTML is written to the same directory and base name as the source file (.html); if it already exists, it is renamed as a backup first, and the final result is emitted as JSON to stdout.

skills/baoyu-markdown-to-html/scripts/main.ts

backupPath = `${finalHtmlPath}.bak-${formatTimestamp()}`;

SKILL.md specifies conflict resolution: `Backup: /path/to/article.html.bak-YYYYMMDDHHMMSS`, and the JSON output contains fields such as htmlPath, backupPath, contentImages, mermaidImages, etc.

Theme, color, font size, and citation mode are explicit, externally configurable options; --cite collects standard external links into numbered citations at the bottom, while native WeChat links remain in place.

skills/baoyu-markdown-to-html/SKILL.md

`https://mp.weixin.qq.com/...` links stay as direct links and are not moved to the bottom.

Theme resolution order: CLI --theme > this skill's EXTEND.md default_theme > baoyu-post-to-wechat EXTEND.md default_theme (cross-skill fallback) > ask the user; --cite is disabled by default (SKILL.md: 'Default: Off. Do not ask by default.').

Chinese language detection is performed upfront in the workflow, and upon user consent, baoyu-format-markdown is invoked first for cleaning (fixing CJK bold parsing failures and Chinese-English spacing).

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 is triggered only when the input contains CJK characters; if the user declines, it continues with the original file—this is an optional cross-skill call that introduces baoyu-format-markdown's own behavior (including its npx dependencies).

The configuration surface is EXTEND.md (default theme, custom CSS variables, code block styles, mermaid theme/scale/background); the first match across a three-level path is used, and if not found, default values are used without running an initial setup wizard.

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`).

Unlike other baoyu skills (such as image-gen/wechat, which enforce initial configuration), this skill can operate directly without an EXTEND.md.

2Core Capabilities

01Markdown → Styled HTML with inlined CSS (four themes: default/grace/simple/modern + 13 color presets + font and font-size options)

02Mermaid rendering to local PNG (headless Chrome/CDP + hash caching + fallback to `<pre class="mermaid">` on failure)

03External links converted to bottom citations (--cite, optional), excluding WeChat links and raw URL links

04Image placeholder rewriting and local path reporting (contentImages contains placeholder/localPath/originalPath)

05Rich Markdown dialect support: GFM tables, code highlighting, alerts, footnotes, ruby annotations, math, PlantUML

06Results reported in JSON (htmlPath/backupPath/contentImages/mermaidImages) for seamless downstream agent workflows

3External Dependencies

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

4Recommended Governance & Evidence

Suggested Controls for Safe Operation

For Agent Runtime

Graded/per-use authorization, sandbox recommended

For Administrators

Approval workflow, rollback support, full audit

Evidence & Triggers (File Paths & Excerpts)

scripts/: Execute local script or command: bun {baseDir}/scripts/main.ts <markdown_file> [--theme …] [--cite] [--merma
网络端点: Declared external network access: https://www.plantuml.com/plantuml (default, only when document contains plantuml code blocks: diagram source code is sent as a URL-encoded payload and returns diagram)
本地工作目录: File read/write and artifact output: .html with the same base name and directory as the input (renamed to .html.bak-YYYYMMDDHHMMSS before overwriting)

Audit Notes: Three-part justification: ① The subject of assessment is this skill directory (SKILL.md + scripts/main.ts + main.test.ts + bun.lock; shared package logic resides in repository packages/ and is declared as an officially supported feature in SKILL.md); ② The directory's own behavior = local script execution + local headless Chrome image generation + local disk writes (.html and imgs/.mermaid-cache/*.png, with backup before overwrite); ③ The key factor for the Amber rating is that executing per SKILL.md sends user content outbound to external service backends: SKILL.md explicitly lists PlantUML support, and its rendering routes through markedPlantUML registered by the dependency package using the default public rendering service `serverUrl: options.serverUrl || `https://www.plantuml.com/plantuml`,` (diagram source code sent externally), and `const protocol = url.startsWith("https://") ? https : http;` downloads arbitrary http(s) images in documents locally. There is no credential harvesting, no reverse engineering/spoofing, no TLS downgrade, and Chrome does not disable sandboxing or apply anti-detection patches (unlike `--disable-blink-features=AutomationControlled` in post-to-wechat/post-to-weibo in the same repo, it is absent from this skill's Chrome launch flags), so it is not escalated to Red; if a document contains neither plantuml blocks nor remote images, behavior degrades to purely local (Blue level).

5Second-Pass Verification

[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.' 一致。

6Verdict & Scenarios

Pragmatic approach tailored for WeChat Official Accounts: CSS inlining + local image path reporting + converting external links to bottom citations directly solve formatting loss and unclickable external links in the WeChat editor.

Mermaid runs via local headless Chrome with content hash caching, requiring no cloud rendering dependencies and avoiding redundant diagram generation on repeated conversions.

Complete fallback path: Gracefully falls back to `<pre class="mermaid">` when Chrome is absent or rendering fails, ensuring the overall conversion does not fail.

Broad Markdown dialect coverage (GFM, syntax highlighting, alerts, footnotes, ruby, math, PlantUML), plus 4 themes + 13 preset colors + font/size options.

Programmatically consumable output: JSON output (htmlPath/backupPath/contentImages/mermaidImages) allows subsequent skills (e.g., post-to-wechat) to take over directly.

Best for: Ideal for converting written Markdown articles into styled HTML ready to paste directly into the WeChat Official Account editor, or serving as the rendering frontend for post-to-wechat; also suitable for offline writing workflows requiring local Mermaid/math rendering while retaining local image paths.

Not for: Not suitable for sensitive documents containing internal architecture diagrams (PlantUML) or image links from untrusted sources (defaults to sending/fetching externally); not suitable for web layouts requiring pixel-perfect control (outputs WeChat-friendly inlined-style HTML rather than full site themes); and not suitable for environments lacking Chrome that strictly require Mermaid diagram rendering (silently degrades to code blocks).

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

Agents automatically download and verify mirrors from this JSON guide.

② Upstream GitHub

GitHub Repo ↗

Pinned to commit 1567581c26.