Back to Details

baoyu-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 
{baseDir}
. Resolve 
${BUN_X}
runtime: if 
bun
installed → 
bun
; if 
npx
available → 
npx -y bun
; else suggest installing bun. Replace 
{baseDir}
and 
${BUN_X}
with actual values.
ScriptPurpose
scripts/main.ts
Main entry point
Agent 执行逻辑：将本SKILL.md所在目录确定为
{baseDir}
。解析
${BUN_X}
运行时：如果已安装
bun
则使用
bun
；如果可用
npx
则使用
npx -y bun
；否则建议用户安装bun。将
{baseDir}
和
${BUN_X}
替换为实际值。
脚本用途
scripts/main.ts
主入口文件

Preferences (EXTEND.md)

偏好配置 (EXTEND.md)

Check EXTEND.md existence (priority order):
bash
undefined
按以下优先级顺序检查EXTEND.md是否存在：
bash
undefined

macOS, Linux, WSL, Git Bash

macOS, Linux, WSL, Git Bash

test -f .baoyu-skills/baoyu-markdown-to-html/EXTEND.md && echo "project" test -f "${XDG_CONFIG_HOME:-$HOME/.config}/baoyu-skills/baoyu-markdown-to-html/EXTEND.md" && echo "xdg" test -f "$HOME/.baoyu-skills/baoyu-markdown-to-html/EXTEND.md" && echo "user"

```powershell
test -f .baoyu-skills/baoyu-markdown-to-html/EXTEND.md && echo "project" test -f "${XDG_CONFIG_HOME:-$HOME/.config}/baoyu-skills/baoyu-markdown-to-html/EXTEND.md" && echo "xdg" test -f "$HOME/.baoyu-skills/baoyu-markdown-to-html/EXTEND.md" && echo "user"

```powershell

PowerShell (Windows)

PowerShell (Windows)

if (Test-Path .baoyu-skills/baoyu-markdown-to-html/EXTEND.md) { "project" } $xdg = if ($env:XDG_CONFIG_HOME) { $env:XDG_CONFIG_HOME } else { "$HOME/.config" } if (Test-Path "$xdg/baoyu-skills/baoyu-markdown-to-html/EXTEND.md") { "xdg" } if (Test-Path "$HOME/.baoyu-skills/baoyu-markdown-to-html/EXTEND.md") { "user" }

┌──────────────────────────────────────────────────────────────┬───────────────────┐
│                             Path                             │     Location      │
├──────────────────────────────────────────────────────────────┼───────────────────┤
│ .baoyu-skills/baoyu-markdown-to-html/EXTEND.md               │ Project directory │
├──────────────────────────────────────────────────────────────┼───────────────────┤
│ $HOME/.baoyu-skills/baoyu-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
if (Test-Path .baoyu-skills/baoyu-markdown-to-html/EXTEND.md) { "project" } $xdg = if ($env:XDG_CONFIG_HOME) { $env:XDG_CONFIG_HOME } else { "$HOME/.config" } if (Test-Path "$xdg/baoyu-skills/baoyu-markdown-to-html/EXTEND.md") { "xdg" } if (Test-Path "$HOME/.baoyu-skills/baoyu-markdown-to-html/EXTEND.md") { "user" }

┌──────────────────────────────────────────────────────────────┬───────────────────┐
│                             路径                             │      位置         │
├──────────────────────────────────────────────────────────────┼───────────────────┤
│ .baoyu-skills/baoyu-markdown-to-html/EXTEND.md               │ 项目目录          │
├──────────────────────────────────────────────────────────────┼───────────────────┤
│ $HOME/.baoyu-skills/baoyu-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:
  1. Read input markdown file
  2. Check if content contains CJK characters (Chinese/Japanese/Korean)
  3. If no CJK content → skip to Step 1
Format Suggestion:
If CJK content detected AND 
baoyu-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 
baoyu-format-markdown
skill to format the file, then use formatted file as input.
If user declines: Continue with original file.
触发条件：仅当输入文件包含中文文本时执行本步骤。
检测逻辑：
  1. 读取输入的Markdown文件
  2. 检查内容是否包含CJK字符（中文/日文/韩文）
  3. 如果没有CJK内容 → 直接跳转到步骤1
格式优化建议：
如果检测到CJK内容，且
baoyu-format-markdown
skill可用：
调用
AskUserQuestion
询问用户是否先执行格式化。格式化可以修复以下问题：
  • 加粗标记内部包含标点导致的
    **
    解析失败
  • 中日韩字符与英文之间的空格问题
如果用户同意：调用
baoyu-format-markdown
skill格式化文件，使用格式化后的文件作为后续输入。
如果用户拒绝：继续使用原始文件处理。

Step 1: Determine Theme

步骤1：确定主题

Theme resolution order (first match wins):
  1. User explicitly specified theme (CLI 
    --theme
    or conversation)
  2. EXTEND.md 
    default_theme
    (this skill's own EXTEND.md, checked in Step 0)
  3. baoyu-post-to-wechat
    EXTEND.md 
    default_theme
    (cross-skill fallback)
  4. 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
主题解析优先级（匹配到第一个即生效）：
  1. 用户明确指定的主题（CLI 
    --theme
    参数或者对话中指定）
  2. EXTEND.md中配置的
    default_theme
    （本skill的EXTEND.md，已在步骤0中检查）
  3. baoyu-post-to-wechat
    的EXTEND.md中配置的
    default_theme
    （跨skill fallback）
  4. 如果都未找到 → 调用
    AskUserQuestion
    向用户确认
跨skill EXTEND.md检查（仅当本skill的EXTEND.md没有配置
default_theme
时执行）：
bash
undefined

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

检查baoyu-post-to-wechat的EXTEND.md中的default_theme配置

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

```powershell
test -f "$HOME/.baoyu-skills/baoyu-post-to-wechat/EXTEND.md" && grep -o 'default_theme:.*' "$HOME/.baoyu-skills/baoyu-post-to-wechat/EXTEND.md"

```powershell

PowerShell (Windows)

PowerShell (Windows)

if (Test-Path "$HOME/.baoyu-skills/baoyu-post-to-wechat/EXTEND.md") { Select-String -Pattern 'default_theme:.*' -Path "$HOME/.baoyu-skills/baoyu-post-to-wechat/EXTEND.md" | ForEach-Object { $_.Matches.Value } }

**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) | Classic - traditional layout, centered title with bottom border, H2 with white text on colored background |
| `grace` | Elegant - text shadow, rounded cards, refined blockquotes |
| `simple` | Minimal - modern minimalist, asymmetric rounded corners, clean whitespace |
| `modern` | Modern - large radius, pill-shaped titles, relaxed line height (pair with `--color red` for traditional red-gold style) |
if (Test-Path "$HOME/.baoyu-skills/baoyu-post-to-wechat/EXTEND.md") { Select-String -Pattern 'default_theme:.*' -Path "$HOME/.baoyu-skills/baoyu-post-to-wechat/EXTEND.md" | ForEach-Object { $_.Matches.Value } }

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

**如果未找到默认主题**：调用`AskUserQuestion`向用户确认可选主题：

| 主题 | 说明 |
|-------|-------------|
| `default`（推荐） | 经典款 - 传统布局，居中标题带下划线，H2标题为有色背景白字 |
| `grace` | 优雅款 - 文字阴影，圆角卡片，精致的引用块样式 |
| `simple` | 极简款 - 现代极简风，不对称圆角，干净的留白 |
| `modern` | 现代款 - 大圆角，胶囊形标题，宽松行高（搭配`--color red`可实现传统红金风格） |

Step 1.5: Determine Citation Mode

步骤1.5：确定引用模式

Default: Off. Do not ask by default.
Enable only if the user explicitly asks for "微信外链转底部引用", "底部引用", "文末引用", or passes 
--cite
.
Behavior when enabled:
  • Ordinary external links are rendered with numbered superscripts and collected under a final 
    引用链接
    section.
  • https://mp.weixin.qq.com/...
    links stay as direct links and are not moved to the bottom.
  • Bare links where link text equals URL stay inline.
默认状态：关闭，默认不需要询问用户。
仅当用户明确要求「微信外链转底部引用」、「底部引用」、「文末引用」，或者传入
--cite
参数时才启用。
启用后行为：
  • 普通外部链接会渲染为带编号的上标，统一收集到文末的
    引用链接
    章节
  • https://mp.weixin.qq.com/...
    的链接保留为直接链接，不会移动到底部
  • 链接文本与URL相同的裸链保留在行内

Step 2: Convert

步骤2：执行转换

bash
${BUN_X} {baseDir}/scripts/main.ts <markdown_file> --theme <theme> [--cite]
bash
${BUN_X} {baseDir}/scripts/main.ts <markdown_file> --theme <theme> [--cite]

Step 3: Report Result

步骤3：上报结果

Display the output path from JSON result. If backup was created, mention it.
展示JSON结果中的输出路径。如果创建了备份，需要告知用户。

Usage

使用方法

bash
${BUN_X} {baseDir}/scripts/main.ts <markdown_file> [options]
Options:
OptionDescriptionDefault
--theme <name>
Theme name (default, grace, simple, modern)default
--color <name|hex>
Primary color: preset name or hex valuetheme default
--font-family <name>
Font: sans, serif, serif-cjk, mono, or CSS valuetheme default
--font-size <N>
Font size: 14px, 15px, 16px, 17px, 18px16px
--title <title>
Override title from frontmatter
--cite
Convert external links to bottom citations, append 
引用链接
section		false (off)
--keep-title
Keep the first heading in contentfalse (removed)
--help
Show help
Color Presets:
NameHexLabel
blue#0F4C81Classic Blue
green#009874Emerald Green
vermilion#FA5151Vibrant Vermilion
yellow#FECE00Lemon Yellow
purple#92617ELavender Purple
sky#55C9EASky Blue
rose#B76E79Rose Gold
olive#556B2FOlive Green
black#333333Graphite Black
gray#A9A9A9Smoke Gray
pink#FFB7C5Sakura Pink
red#A93226China Red
orange#D97757Warm Orange (modern default)
Examples:
bash
undefined
bash
${BUN_X} {baseDir}/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、18px16px
--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主题默认）
使用示例：
bash
undefined

Basic conversion (uses default theme, removes first heading)

基础转换（使用默认主题，移除第一个标题）

${BUN_X} {baseDir}/scripts/main.ts article.md
${BUN_X} {baseDir}/scripts/main.ts article.md

With specific theme

指定主题转换

${BUN_X} {baseDir}/scripts/main.ts article.md --theme grace
${BUN_X} {baseDir}/scripts/main.ts article.md --theme grace

Theme with custom color

指定主题和自定义颜色

${BUN_X} {baseDir}/scripts/main.ts article.md --theme modern --color red
${BUN_X} {baseDir}/scripts/main.ts article.md --theme modern --color red

Enable bottom citations for ordinary external links

启用普通外部链接底部引用

${BUN_X} {baseDir}/scripts/main.ts article.md --cite
${BUN_X} {baseDir}/scripts/main.ts article.md --cite

Keep the first heading in content

保留内容中的第一个标题

${BUN_X} {baseDir}/scripts/main.ts article.md --keep-title
${BUN_X} {baseDir}/scripts/main.ts article.md --keep-title

Override title

覆盖文章标题

${BUN_X} {baseDir}/scripts/main.ts article.md --title "My Article"
undefined
${BUN_X} {baseDir}/scripts/main.ts article.md --title "我的文章"
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
标准输出JSON格式：
json
{
  "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"
    }
  ]
}

Themes

主题说明

ThemeDescription
default
Classic - traditional layout, centered title with bottom border, H2 with white text on colored background
grace
Elegant - text shadow, rounded cards, refined blockquotes (by @brzhang)
simple
Minimal - modern minimalist, asymmetric rounded corners, clean whitespace (by @okooo5km)
modern
Modern - large radius, pill-shaped titles, relaxed line height (pair with 
--color red
for traditional red-gold style)
主题说明
default
经典款 - 传统布局，居中标题带下划线，H2标题为有色背景白字
grace
优雅款 - 文字阴影，圆角卡片，精致的引用块样式（作者 @brzhang）
simple
极简款 - 现代极简风，不对称圆角，干净的留白（作者 @okooo5km）
modern
现代款 - 大圆角，胶囊形标题，宽松行高（搭配
--color red
可实现传统红金风格）

Supported Markdown Features

支持的Markdown特性

FeatureSyntax
Headings
# H1
to 
###### H6
Bold/Italic
**bold**
, 
*italic*
Code blocks
```lang
with syntax highlighting
Inline code
`code`
TablesGitHub-flavored markdown tables
Images
![alt](src)
Links
[text](url)
; add 
--cite
to move ordinary external links into bottom 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)
；添加
--cite
参数可将普通外部链接移动到底部引用
引用块
> 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: 文章标题
author: 作者名称
description: 文章摘要
---
如果未找到标题，会从第一个H1/H2标题提取或者使用文件名作为标题。

Extension Support

扩展支持

Custom configurations via EXTEND.md. See Preferences section for paths and supported options.
可通过EXTEND.md自定义配置，路径和支持的选项参考偏好配置章节。