AI Skills
baoyu-markdown-to-html

baoyu-markdown-to-html

热门

将 Markdown 转换为带有微信兼容主题的样式化 HTML。支持代码高亮、数学公式、Mermaid（通过无头 Chrome 渲染为 PNG）、PlantUML、脚注、提示块、信息图，以及可选的外部链接底部引用。当用户要求“markdown to html”、“convert md to html”、“md 转 html”、“微信外链转底部引用”或需要从 markdown 生成样式化 HTML 输出时使用。

2.2万Star
2606Fork
更新于 2026/6/18
获取 Skill源代码

相关 Skills

ponytail-help8.4万skill-share7万nature-ref-verifier3.3万
SKILL.md
只读
名称
baoyu-markdown-to-html
描述

将 Markdown 转换为带有微信兼容主题的样式化 HTML。支持代码高亮、数学公式、Mermaid（通过无头 Chrome 渲染为 PNG）、PlantUML、脚注、提示块、信息图，以及可选的外部链接底部引用。当用户要求“markdown to html”、“convert md to html”、“md 转 html”、“微信外链转底部引用”或需要从 markdown 生成样式化 HTML 输出时使用。

版本
1.117.3

Markdown 转 HTML 转换器

将 Markdown 文件转换为内联 CSS 的漂亮样式化 HTML，针对微信公众号和其他平台优化。

用户输入工具

当此技能提示用户时，遵循以下工具选择规则（优先级顺序）：

  1. 优先使用当前代理运行时暴露的内置用户输入工具——例如 AskUserQuestion、request_user_input、clarify、ask_user 或任何等效工具。
  2. 回退：如果不存在此类工具，则发出编号的纯文本消息，并要求用户回复每个问题的选择编号/答案。
  3. 批处理：如果工具支持单次调用多个问题，则将所有适用问题合并为一次调用；如果仅支持单个问题，则按优先级顺序逐一询问。

下面的具体 AskUserQuestion 引用是示例——在其他运行时中替换为本地等效项。

脚本目录

代理执行：确定此 SKILL.md 目录为 {baseDir}。解析 ${BUN_X} 运行时：如果安装了 bun → bun；如果 npx 可用 → npx -y bun；否则建议安装 bun。将 {baseDir} 和 ${BUN_X} 替换为实际值。

脚本 用途
scripts/main.ts 主入口点

偏好设置 (EXTEND.md)

按优先级顺序检查 EXTEND.md——第一个找到的生效：

优先级 路径 范围
1 .baoyu-skills/baoyu-markdown-to-html/EXTEND.md 项目
2 ${XDG_CONFIG_HOME:-$HOME/.config}/baoyu-skills/baoyu-markdown-to-html/EXTEND.md XDG
3 $HOME/.baoyu-skills/baoyu-markdown-to-html/EXTEND.md 用户主目录

如果未找到，则使用默认值。

EXTEND.md 支持：默认主题、自定义 CSS 变量、代码块样式、mermaid 默认值（mermaid_theme、mermaid_scale、mermaid_background）。

工作流程

步骤 0：预检查（中文内容）

条件：仅当输入文件包含中文文本时执行。

检测：

  1. 读取输入 markdown 文件
  2. 检查内容是否包含中日韩（CJK）字符
  3. 如果不包含 CJK 内容 → 跳转到步骤 1

格式建议：

如果检测到 CJK 内容且 baoyu-format-markdown 技能可用：

使用 AskUserQuestion 询问是否先格式化。格式化可以修复：

  • 标点符号在加粗标记内导致 ** 解析失败的问题
  • CJK/英文间距问题

如果用户同意：调用 baoyu-format-markdown 技能格式化文件，然后使用格式化后的文件作为输入。

如果用户拒绝：继续使用原始文件。

步骤 1：确定主题

主题解析顺序（第一个匹配生效）：

  1. 用户明确指定的主题（CLI --theme 或对话中）
  2. EXTEND.md 中的 default_theme（此技能自身的 EXTEND.md，在步骤 0 中检查）
  3. baoyu-post-to-wechat 的 EXTEND.md 中的 default_theme（跨技能回退）
  4. 如果未找到 → 使用 AskUserQuestion 确认

跨技能 EXTEND.md 检查（仅当此技能的 EXTEND.md 没有 default_theme 时）：

如果存在，读取 $HOME/.baoyu-skills/baoyu-post-to-wechat/EXTEND.md 并查找 default_theme: 行。如果存在则使用该值；否则继续。

如果从 EXTEND.md 解析到主题：直接使用，不要询问用户。

如果未找到默认值：使用 AskUserQuestion 从下方主题表中确认一个主题。

步骤 1.5：确定引用模式

默认：关闭。默认不询问。

仅当用户明确要求“微信外链转底部引用”、“底部引用”、“文末引用”或传递 --cite 时启用。

启用时的行为：

  • 普通外部链接以编号上标形式渲染，并收集在最后的 引用链接 部分。
  • https://mp.weixin.qq.com/... 链接保持为直接链接，不移动到底部。
  • 链接文本等于 URL 的裸链接保持内联。

步骤 2：转换

${BUN_X} {baseDir}/scripts/main.ts <markdown_file> --theme <theme> [--cite]

步骤 3：报告结果

显示 JSON 结果中的输出路径。如果创建了备份，请提及。

用法

${BUN_X} {baseDir}/scripts/main.ts <markdown_file> [options]

选项：

选项 描述 默认值
--theme <name> 主题名称（default, grace, simple, modern） default
--color <name|hex> 主色：预设名称或十六进制值 主题默认
--font-family <name> 字体：sans, serif, serif-cjk, mono 或 CSS 值 主题默认
--font-size <N> 字号：14px, 15px, 16px, 17px, 18px 16px
--title <title> 覆盖 frontmatter 中的标题
--cite 将外部链接转换为底部引用，追加 引用链接 部分 false（关闭）
--keep-title 保留内容中的第一个标题 false（移除）
--mermaid-theme <name> Mermaid 主题：default, forest, dark, neutral, base default
--mermaid-scale <N> Mermaid 渲染缩放比例（正数，≤ 4） 2
--mermaid-width <N> Mermaid 目标显示宽度（CSS px）；当图表宽度小于此值时，PNG 以 width × scale 像素渲染 860
--mermaid-bg <value> Mermaid 背景：white, transparent 或 #hex white
--no-mermaid 跳过 Mermaid PNG 渲染；输出 <pre class="mermaid"> 回退 false
--help 显示帮助

颜色预设：

名称 十六进制 标签
blue #0F4C81 经典蓝
green #009874 翡翠绿
vermilion #FA5151 活力朱红
yellow #FECE00 柠檬黄
purple #92617E 薰衣草紫
sky #55C9EA 天蓝
rose #B76E79 玫瑰金
olive #556B2F 橄榄绿
black #333333 石墨黑
gray #A9A9A9 烟灰
pink #FFB7C5 樱花粉
red #A93226 中国红
orange #D97757 暖橙（modern 默认）

示例：

# 基本转换（使用默认主题，移除第一个标题）
${BUN_X} {baseDir}/scripts/main.ts article.md

# 指定主题
${BUN_X} {baseDir}/scripts/main.ts article.md --theme grace

# 主题搭配自定义颜色
${BUN_X} {baseDir}/scripts/main.ts article.md --theme modern --color red

# 为普通外部链接启用底部引用
${BUN_X} {baseDir}/scripts/main.ts article.md --cite

# 保留内容中的第一个标题
${BUN_X} {baseDir}/scripts/main.ts article.md --keep-title

# 覆盖标题
${BUN_X} {baseDir}/scripts/main.ts article.md --title "我的文章"

输出

文件位置：与输入 markdown 文件相同目录。

  • 输入：/path/to/article.md
  • 输出：/path/to/article.html

冲突处理：如果 HTML 文件已存在，将首先备份：

  • 备份：/path/to/article.html.bak-YYYYMMDDHHMMSS

JSON 输出到标准输出：

{
  "title": "文章标题",
  "author": "作者名",
  "summary": "文章摘要...",
  "htmlPath": "/path/to/article.html",
  "backupPath": "/path/to/article.html.bak-20260128180000",
  "contentImages": [
    {
      "placeholder": "MDTOHTMLIMGPH_1",
      "localPath": "/path/to/img.png",
      "originalPath": "imgs/image.png"
    }
  ],
  "mermaidImages": [
    {
      "hash": "a1b2c3d4e5f6",
      "localPath": "/path/to/imgs/.mermaid-cache/mermaid-a1b2c3d4e5f6.png",
      "cached": false
    }
  ]
}

Mermaid 渲染：以 ```mermaid 围栏的代码块通过无头 Chrome（CDP）渲染为 PNG，并缓存在 imgs/.mermaid-cache/mermaid-<hash>.png。缓存键包括代码、主题、缩放比例、目标宽度、背景和 mermaid 版本。如果不想将生成的图表纳入版本控制，请将 imgs/.mermaid-cache/ 添加到 .gitignore。需要系统上安装 Chrome/Chromium/Edge；否则代码块回退为 <pre class="mermaid">…</pre>，转换仍然成功。

主题

主题 描述
default 经典 - 传统布局，居中标题带底部边框，H2 为白色文字彩色背景
grace 优雅 - 文字阴影，圆角卡片，精致引用块（by @brzhang）
simple 简约 - 现代极简，不对称圆角，干净留白（by @okooo5km）
modern 现代 - 大圆角，药丸形状标题，宽松行高（搭配 --color red 获得传统红金风格）

支持的 Markdown 特性

特性 语法
标题 # H1 到 ###### H6
加粗/斜体 **bold**, *italic*
代码块 ```lang 带语法高亮
行内代码 `code`
表格 GitHub 风格的 markdown 表格
图片 ![alt](src)
链接 [text](url)；添加 --cite 将普通外部链接移到底部引用
引用块 > quote
列表 - 无序，1. 有序
提示块 > [!NOTE], > [!WARNING] 等
脚注 [^1] 引用
注音文字 `{base
Mermaid ```mermaid 块通过无头 Chrome 渲染为本地 PNG（缓存在 imgs/.mermaid-cache/ 下）；如果 Chrome 不可用或渲染失败，回退为 <pre class="mermaid">
PlantUML ```plantuml 图表

Frontmatter

支持 YAML frontmatter 元数据：

---
title: 文章标题
author: 作者名
description: 文章摘要
---

如果未找到标题，则从第一个 H1/H2 标题提取或使用文件名。

扩展支持

通过 EXTEND.md 进行自定义配置。参见偏好设置部分了解路径和受支持的选项。