baoyu-markdown-to-html

Markdown 转 HTML 转换器

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

执行

Agent 执行：使用 bun .agents/skills/baoyu-markdown-to-html/scripts/main.ts <markdown_file> [options]。

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

路径要求

• CWD：必须从 vault 根目录运行。
• 输入：<markdown_file> 必须是绝对路径或相对于 vault 根目录的路径。
• 输出：在输入文件所在目录中创建 .html 文件。

工作流

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

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

检测：

1. 读取输入 Markdown 文件
2. 检查内容是否包含 CJK 字符（中文／日文／韩文）
3. 如果没有 CJK 内容 → 跳至步骤 1

格式建议：

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

使用 AskUserQuestion 询问是否先进行格式整理。格式整理可以修复：

• 标点符号位于粗体标记内导致 ** 解析失败的问题
• CJK／英文间距问题

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

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

步骤 1：确定主题

主题判定顺序（命中第一项即停止）：

1. 用户明确指定了主题（CLI --theme 或对话中指定）
2. 如果没有指定 → 使用 AskUserQuestion 进行确认

主题	描述
default（推荐）	经典风格——传统布局，标题居中并带有底部边框，H2 使用彩色背景和白色文字
grace	优雅风格——文字阴影、圆角卡片、精致的引用块
simple	简约风格——现代极简设计、非对称圆角、清爽留白
modern	现代风格——大圆角、胶囊形标题、舒展的行高（搭配 --color red 使用传统红金风格）

步骤 1.5：确定引用模式

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

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

启用后的行为：

• 普通外部链接会显示为带编号的上标，并集中列在文末的 引用链接 部分。
• https://mp.weixin.qq.com/... 链接仍作为直接链接保留，不会移至文末。
• 链接文本与 URL 相同的裸链接会保留在原处。

步骤 2：转换

bun .agents/skills/baoyu-markdown-to-html/scripts/main.ts <markdown_file> --theme <theme> [--cite]

步骤 3：报告结果

显示 JSON 结果中的输出路径。如果创建了备份，请一并说明。

用法

bun .agents/skills/baoyu-markdown-to-html/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（移除）
--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 默认值）

示例：

# Basic conversion (uses default theme, removes first heading)
bun .agents/skills/baoyu-markdown-to-html/scripts/main.ts article.md

# With specific theme
bun .agents/skills/baoyu-markdown-to-html/scripts/main.ts article.md --theme grace

# Theme with custom color
bun .agents/skills/baoyu-markdown-to-html/scripts/main.ts article.md --theme modern --color red

# Enable bottom citations for ordinary external links
bun .agents/skills/baoyu-markdown-to-html/scripts/main.ts article.md --cite

# Keep the first heading in content
bun .agents/skills/baoyu-markdown-to-html/scripts/main.ts article.md --keep-title

# Override title
bun .agents/skills/baoyu-markdown-to-html/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	经典风格——传统布局，标题居中并带有底部边框，H2 使用彩色背景和白色文字
grace	优雅风格——文字阴影、圆角卡片、精致的引用块（作者：@brzhang）
simple	极简风格——现代简约、不对称圆角、留白清爽（作者：@okooo5km）
modern	现代风格——大圆角、胶囊形标题、舒适的行高（搭配 --color red 使用，可呈现传统红金风格）

支持的 Markdown 功能

功能	语法
标题	# H1 到 ###### H6
粗体/斜体	**bold**、*italic*
代码块	使用带语法高亮的 ```lang
行内代码	`code`
表格	GitHub 风格的 Markdown 表格
图片	
链接	[text](url)；添加 --cite 可将普通外部链接移至文末参考资料
引用块	> quote
列表	- 无序，1. 有序
提示框	> [!NOTE]、> [!WARNING] 等
脚注	[^1] 引用
Ruby 注音	`{base
Mermaid	```mermaid 图表
PlantUML	```plantuml 图表

Frontmatter

支持使用 YAML frontmatter 添加元数据：

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

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