名称: baoyu-markdown-to-html 描述: 将 Markdown 转换为带 WeChat 兼容主题的样式 HTML。支持代码高亮、数学公式、PlantUML、脚注、警告框和图表。当用户询问“markdown 转 html”、“转换 md 到 html”、“md转html”或需要从 markdown 生成样式 HTML 输出时使用。

Markdown 转 HTML 转换器

将 Markdown 文件转换为带有内联 CSS 的美丽样式 HTML，针对微信公众号和其他平台进行了优化。

脚本目录

代理执行: 确定此 SKILL.md 目录为 SKILL_DIR，然后使用 ${SKILL_DIR}/scripts/<name>.ts。

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

偏好设置 (EXTEND.md)

使用 Bash 检查 EXTEND.md 存在性（优先级顺序）：

# 首先检查项目级
test -f .baoyu-skills/baoyu-markdown-to-html/EXTEND.md && echo "project"

# 然后用户级（跨平台：$HOME 在 macOS/Linux/WSL 上工作）
test -f "$HOME/.baoyu-skills/baoyu-markdown-to-html/EXTEND.md" && echo "user"

┌──────────────────────────────────────────────────────────────┬───────────────────┐ │ 路径 │ 位置 │ ├──────────────────────────────────────────────────────────────┼───────────────────┤ │ .baoyu-skills/baoyu-markdown-to-html/EXTEND.md │ 项目目录 │ ├──────────────────────────────────────────────────────────────┼───────────────────┤ │ $HOME/.baoyu-skills/baoyu-markdown-to-html/EXTEND.md │ 用户主目录 │ └──────────────────────────────────────────────────────────────┴───────────────────┘

┌───────────┬───────────────────────────────────────────────────────────────────────────┐ │ 结果 │ 操作 │ ├───────────┼───────────────────────────────────────────────────────────────────────────┤ │ 找到 │ 读取、解析、应用设置 │ ├───────────┼───────────────────────────────────────────────────────────────────────────┤ │ 未找到 │ 使用默认值 │ └───────────┴───────────────────────────────────────────────────────────────────────────┘

EXTEND.md 支持: 默认主题 | 自定义 CSS 变量 | 代码块样式

工作流程

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

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

检测:

读取输入 markdown 文件
检查内容是否包含 CJK 字符（中文/日文/韩文）
如果没有 CJK 内容 → 跳到步骤 1

格式建议:

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

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

带有标点符号的粗体标记导致 ** 解析失败
CJK/英文间距问题

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

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

步骤 1: 确认主题

在转换之前，使用 AskUserQuestion 确认主题（除非用户已指定）：

主题	描述
`default` (推荐)	经典主题 - 传统排版，标题居中带底边，二级标题白字彩底
`grace`	优雅主题 - 文字阴影，圆角卡片，精致引用块
`simple`	简洁主题 - 现代极简风，不对称圆角，清爽留白

步骤 2: 转换

npx -y bun ${SKILL_DIR}/scripts/main.ts <markdown_file> --theme <theme>

步骤 3: 报告结果

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

用法

npx -y bun ${SKILL_DIR}/scripts/main.ts <markdown_file> [options]

选项:

选项	描述	默认
`--theme <name>`	主题名称 (default, grace, simple)	default
`--title <title>`	覆盖前端内容中的标题
`--keep-title`	保留内容中的第一个标题	false (移除)
`--help`	显示帮助

示例:

# 基本转换 (使用默认主题，移除第一个标题)
npx -y bun ${SKILL_DIR}/scripts/main.ts article.md

# 使用特定主题
npx -y bun ${SKILL_DIR}/scripts/main.ts article.md --theme grace

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

# 覆盖标题
npx -y bun ${SKILL_DIR}/scripts/main.ts article.md --title "我的文章"

输出

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

输入: /path/to/article.md
输出: /path/to/article.html

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

备份: /path/to/article.html.bak-YYYYMMDDHHMMSS

JSON 输出到 stdout:

{
  "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"
    }
  ]
}

主题

主题	描述
`default`	经典主题 - 传统排版，标题居中带底边，二级标题白字彩底
`grace`	优雅主题 - 文字阴影，圆角卡片，精致引用块 (by @brzhang)
`simple`	简洁主题 - 现代极简风，不对称圆角，清爽留白 (by @okooo5km)

支持的 Markdown 特性

特性	语法
标题	`# H1` 到 `###### H6`
粗体/斜体	`粗体`, `斜体`
代码块	```lang 带语法高亮
内联代码	`代码`
表格	GitHub 风格的 markdown 表格
图片	`![alt](src)`
链接	`[文本](url)` 带脚注引用
引用块	`> 引用`
列表	`-` 无序, `1.` 有序
警告框	`> [!NOTE]`, `> [!WARNING]`, 等
脚注	`[^1]` 引用
注音文本	`{base
Mermaid	```mermaid 图
PlantUML	```plantuml 图

前端内容

支持 YAML 前端内容用于元数据：

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

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

扩展支持

通过 EXTEND.md 自定义配置。有关路径和支持的选项，请参阅 偏好设置 部分。