tuzi-markdown-to-html

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Markdown to HTML Converter

Markdown转HTML转换器

Converts Markdown files to beautifully styled HTML with inline CSS, optimized for WeChat Official Account and other platforms.

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

Script Directory

脚本目录

Agent Execution: Determine this SKILL.md directory as

SKILL_DIR

, then use

${SKILL_DIR}/scripts/<name>.ts

Script	Purpose
`scripts/main.ts`	Main entry point

Agent执行：将此SKILL.md所在目录设为

SKILL_DIR

，然后使用

${SKILL_DIR}/scripts/<name>.ts

路径。

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

Preferences (EXTEND.md)

偏好设置（EXTEND.md）

Use Bash to check EXTEND.md existence (priority order):

bash

undefined

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

bash

undefined

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)

再检查用户级别（跨平台：$HOME在macOS/Linux/WSL下均可生效）

test -f "$HOME/.tuzi-skills/tuzi-markdown-to-html/EXTEND.md" && echo "user"


┌──────────────────────────────────────────────────────────────┬───────────────────┐
│                             Path                             │     Location      │
├──────────────────────────────────────────────────────────────┼───────────────────┤
│ .tuzi-skills/tuzi-markdown-to-html/EXTEND.md               │ Project directory │
├──────────────────────────────────────────────────────────────┼───────────────────┤
│ $HOME/.tuzi-skills/tuzi-markdown-to-html/EXTEND.md         │ User home         │
└──────────────────────────────────────────────────────────────┴───────────────────┘

┌───────────┬───────────────────────────────────────────────────────────────────────────┐
│  Result   │                                  Action                                   │
├───────────┼───────────────────────────────────────────────────────────────────────────┤
│ Found     │ Read, parse, apply settings                                               │
├───────────┼───────────────────────────────────────────────────────────────────────────┤
│ Not found │ Use defaults                                                              │
└───────────┴───────────────────────────────────────────────────────────────────────────┘

**EXTEND.md Supports**: Default theme | Custom CSS variables | Code block style

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变量 | 代码块样式

Workflow

工作流

Step 0: Pre-check (Chinese Content)

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

Condition: Only execute if input file contains Chinese text.

Detection:

Read input markdown file
Check if content contains CJK characters (Chinese/Japanese/Korean)
If no CJK content → skip to Step 1

Format Suggestion:

If CJK content detected AND

tuzi-format-markdown

skill is available:

Use

AskUserQuestion

to ask whether to format first. Formatting can fix:

Bold markers with punctuation inside causing
```
**
```
parse failures
CJK/English spacing issues

If user agrees: Invoke

tuzi-format-markdown

skill to format the file, then use formatted file as input.

If user declines: Continue with original file.

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

检测逻辑:

读取输入的markdown文件
检查内容是否包含CJK字符（中文/日文/韩文）
如果无CJK内容 → 直接跳至步骤1

格式建议:

如果检测到CJK内容且

tuzi-format-markdown

skill可用：

使用

AskUserQuestion

询问用户是否先进行格式化。格式化可修复以下问题：

加粗标记内部包含标点导致
```
**
```
解析失败
中英文混排间距问题

如果用户同意：调用

tuzi-format-markdown

skill格式化文件，然后使用格式化后的文件作为输入。

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

Step 1: Determine Theme

步骤1：确定主题

Theme resolution order (first match wins):

User explicitly specified theme (CLI
```
--theme
```
or conversation)
EXTEND.md
```
default_theme
```
(this skill's own EXTEND.md, checked in Step 0)
```
tuzi-post-to-wechat
```
EXTEND.md
```
default_theme
```
(cross-skill fallback)
If none found → use AskUserQuestion to confirm

Cross-skill EXTEND.md check (only if this skill's EXTEND.md has no

default_theme

bash

undefined

主题优先级顺序（第一个匹配的生效）:

用户显式指定的主题（CLI参数
```
--theme
```
或对话中指定）
EXTEND.md中的
```
default_theme
```
配置（本skill的EXTEND.md，在步骤0中已检查）
```
tuzi-post-to-wechat
```
的EXTEND.md中的
```
default_theme
```
配置（跨skill fallback）
以上都未找到 → 使用AskUserQuestion向用户确认

跨skill EXTEND.md检查（仅当本skill的EXTEND.md没有

default_theme

配置时执行）:

bash

undefined

Check tuzi-post-to-wechat EXTEND.md for default_theme

检查tuzi-post-to-wechat的EXTEND.md中是否有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"


**If theme is resolved from EXTEND.md**: Use it directly, do NOT ask the user.

**If no default found**: Use AskUserQuestion to confirm:

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

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` 还原传统红金风格） |

Step 2: Convert

步骤2：转换

bash

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

bash

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

Step 3: Report Result

步骤3：返回结果

Display the output path from JSON result. If backup was created, mention it.

展示JSON结果中的输出路径。如果生成了备份文件，也要告知用户。

Usage

使用方法

bash

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

Options:

Option	Description	Default
`--theme <name>`	Theme name (default, grace, simple, modern)	default
`--color <name\|hex>`	Primary color: preset name or hex value	theme default
`--font-family <name>`	Font: sans, serif, serif-cjk, mono, or CSS value	theme default
`--font-size <N>`	Font size: 14px, 15px, 16px, 17px, 18px	16px
`--title <title>`	Override title from frontmatter
`--keep-title`	Keep the first heading in content	false (removed)
`--help`	Show help

Color Presets:

Name	Hex	Label
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 default)

Examples:

bash

undefined

bash

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`	展示帮助信息

颜色预设:

名称	十六进制值	标签
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主题默认)

使用示例:

bash

undefined

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"

undefined

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

undefined

Output

输出结果

File location: Same directory as input markdown file.

Input:
```
/path/to/article.md
```
Output:
```
/path/to/article.html
```

Conflict handling: If HTML file already exists, it will be backed up first:

Backup:

/path/to/article.html.bak-YYYYMMDDHHMMSS

JSON output to 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"
    }
  ]
}

文件位置: 和输入的markdown文件同目录。

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

冲突处理: 如果HTML文件已存在，会先进行备份:

备份路径:

/path/to/article.html.bak-YYYYMMDDHHMMSS

输出到stdout的JSON格式：

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

Themes

主题

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

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

Supported Markdown Features

支持的Markdown特性

Feature	Syntax
Headings	`# H1` to `###### H6`
Bold/Italic	`bold` , `italic`
Code blocks	```lang with syntax highlighting
Inline code	`code`
Tables	GitHub-flavored markdown tables
Images	`![alt](src)`
Links	`[text](url)` with footnote references
Blockquotes	`> quote`
Lists	`-` unordered, `1.` ordered
Alerts	`> [!NOTE]` , `> [!WARNING]` , etc.
Footnotes	`[^1]` references
Ruby text	`{base
Mermaid	```mermaid diagrams
PlantUML	```plantuml diagrams

特性	语法
标题	`# H1` 到 `###### H6`
加粗/斜体	`bold` , `italic`
代码块	```lang 带语法高亮
行内代码	`code`
表格	GitHub风格markdown表格
图片	`![alt](src)`
链接	`[text](url)` 支持脚注引用
引用块	`> quote`
列表	`-` 无序列表, `1.` 有序列表
提示框	`> [!NOTE]` , `> [!WARNING]` 等
脚注	`[^1]` 引用
注音文字	`{base
Mermaid	```mermaid 图表
PlantUML	```plantuml 图表

Frontmatter

Frontmatter元数据

Supports YAML frontmatter for metadata:

yaml

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

If no title is found, extracts from first H1/H2 heading or uses filename.

支持YAML格式的frontmatter元数据:

yaml

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

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

Extension Support

扩展支持

Custom configurations via EXTEND.md. See Preferences section for paths and supported options.

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