baoyu-markdown-to-html

Markdown 转 HTML 转换器

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

脚本目录

Agent 执行：将此 SKILL.md 所在目录确定为 SKILL_DIR，然后使用 ${SKILL_DIR}/scripts/<name>.ts。

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

偏好设置（EXTEND.md）

使用 Bash 按优先级顺序检查 EXTEND.md 是否存在：

# Check project-level first
test -f .baoyu-skills/baoyu-markdown-to-html/EXTEND.md && echo "project"

# Then user-level (cross-platform: $HOME works on 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：预检查（中文内容）

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

检测：

1. 读取输入 Markdown 文件
2. 检查内容是否包含 CJK 字符（中文／日文／韩文）
3. 如果没有 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>	覆盖 frontmatter 中的标题
--keep-title	保留内容中的第一个标题	false（已移除）
--help	显示帮助

示例：

# Basic conversion (uses default theme, removes first heading)
npx -y bun ${SKILL_DIR}/scripts/main.ts article.md

# With specific theme
npx -y bun ${SKILL_DIR}/scripts/main.ts article.md --theme grace

# Keep the first heading in content
npx -y bun ${SKILL_DIR}/scripts/main.ts article.md --keep-title

# Override title
npx -y bun ${SKILL_DIR}/scripts/main.ts article.md --title "My Article"

输出

文件位置：与输入 Markdown 文件位于同一目录。

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

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

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

输出到 stdout 的 JSON：

{
  "title": "Article Title",
  "author": "Author Name",
  "summary": "Article 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	优雅主题 - 文字阴影，圆角卡片，精致引用块（由 @brzhang 提供）
simple	简洁主题 - 现代极简风，不对称圆角，清爽留白（由 @okooo5km 提供）

支持的 Markdown 功能

功能	语法
标题	# H1 至 ###### H6
粗体/斜体	**bold**、*italic*
代码块	使用 ```lang 并启用语法高亮
行内代码	`code`
表格	GitHub 风格的 Markdown 表格
图片	
链接	[text](url)，支持脚注引用
引用块	> quote
列表	- 无序列表，1. 有序列表
提示	> [!NOTE]、> [!WARNING] 等
脚注	[^1] 引用
注音文字	`{base
Mermaid	```mermaid 图表
PlantUML	```plantuml 图表

Frontmatter

支持用于元数据的 YAML frontmatter：

---
title: Article Title
author: Author Name
description: Article summary
---

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

扩展支持

通过 EXTEND.md 使用自定义配置。路径和支持的选项请参阅 Preferences 部分。