tuzi-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 .tuzi-skills/tuzi-markdown-to-html/EXTEND.md && echo "project"

# Then user-level (cross-platform: $HOME works on macOS/Linux/WSL)
test -f "$HOME/.tuzi-skills/tuzi-markdown-to-html/EXTEND.md" && echo "user"

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

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

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

工作流

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

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

检测：

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

格式建议：

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

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

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

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

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

步骤 1：确定主题

主题解析顺序（以第一个匹配项为准）：

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

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

# Check tuzi-post-to-wechat EXTEND.md for default_theme
test -f "$HOME/.tuzi-skills/tuzi-post-to-wechat/EXTEND.md" && grep -o 'default_theme:.*' "$HOME/.tuzi-skills/tuzi-post-to-wechat/EXTEND.md"

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

如果未找到默认主题：使用 AskUserQuestion 进行确认：

主题	描述
default（推荐）	经典主题 - 传统排版，标题居中并带底边，二级标题为白字彩底
grace	优雅主题 - 文字阴影、圆角卡片、精致引用块
simple	简洁主题 - 现代极简风格、不对称圆角、清爽留白
modern	现代主题 - 大圆角、药丸形标题、宽松行距（搭配 --color red 还原传统红金风格）

步骤 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、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 中的标题
--keep-title	保留内容中的第一个标题	false（已移除）
--help	显示帮助

颜色预设：

名称	Hex	标签
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)
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

# Theme with custom color
npx -y bun ${SKILL_DIR}/scripts/main.ts article.md --theme modern --color red

# 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

将 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	优雅主题 - 文字阴影、圆角卡片、精致引用块（by @brzhang）
simple	简洁主题 - 现代极简风、不对称圆角、清爽留白（by @okooo5km）
modern	现代主题 - 大圆角、药丸形标题、宽松行距（搭配 --color red 可还原传统红金风格）

支持的 Markdown 功能

功能	语法
标题	# H1 至 ###### H6
粗体/斜体	**bold**、*italic*
代码块	```lang，带语法高亮
行内代码	`code`
表格	GitHub 风格的 Markdown 表格
图片	
链接	[text](url)，支持脚注引用
引用块	> 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 标题中提取，或使用文件名。

扩展支持

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