mage-md-to-html

name	mage-md-to-html
description	Converts Markdown to styled HTML with WeChat-compatible themes. Supports code highlighting, math, PlantUML, footnotes, alerts, and infographics. Use when user asks for "markdown to html", "convert md to html", "md转html", or needs styled HTML output from markdown.

Markdown to HTML Converter

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

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

Preferences (EXTEND.md)

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

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

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

┌──────────────────────────────────────────────────────────────┬───────────────────┐ │ Path │ Location │ ├──────────────────────────────────────────────────────────────┼───────────────────┤ │ .mage-skills/mage-md-to-html/EXTEND.md │ Project directory │ ├──────────────────────────────────────────────────────────────┼───────────────────┤ │ $HOME/.mage-skills/mage-md-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

Workflow

Step 0: Pre-check (Chinese Content)

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 mage-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 mage-format-markdown skill to format the file, then use formatted file as input.

If user declines: Continue with original file.

Step 1: Confirm Theme

Before converting, use AskUserQuestion to confirm the theme (unless user already specified):

Theme	Description
default (Recommended)	经典主题 - 传统排版，标题居中带底边，二级标题白字彩底
grace	优雅主题 - 文字阴影，圆角卡片，精致引用块
simple	简洁主题 - 现代极简风，不对称圆角，清爽留白

Step 2: Convert

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

Step 3: Report Result

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

Usage

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

Options:

Option	Description	Default
--theme <name>	Theme name (default, grace, simple)	default
--title <title>	Override title from frontmatter
--keep-title	Keep the first heading in content	false (removed)
--help	Show help

Examples:

# 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"

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:

{
  "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)

样式文件与依赖（公众号兼容）

样式文件（scripts/md/themes/）：

文件	作用
base.css	基础：容器字体、字号、行高、#output 与 blockquote 的 reset；依赖 CSS 变量 --md-font-family、--md-font-size
default.css	经典主题：h1/h2 居中与底边/彩底、h3 左边框、段落/引用/代码/表格/alert 等完整排版
grace.css	优雅主题：阴影、圆角、引用块样式
simple.css	简洁主题：极简、不对称圆角、留白

CSS 变量（由 render 内联时替换为默认值）：--md-primary-color（默认 #0F4C81）、--md-font-family、--md-font-size（默认 16px）、--blockquote-background（默认 #f7f7f7）、--foreground。

输出：使用 juice 将上述 CSS 内联到 HTML，便于微信公众号等环境正确显示（不依赖外部样式表）。

npm 依赖（需在 scripts/md 下执行 npm install）：

依赖	用途
front-matter	解析 YAML frontmatter
marked	Markdown → HTML
highlight.js	代码高亮
juice	样式内联（公众号兼容关键）
reading-time	阅读时间
unified / remark-parse / remark-stringify / remark-cjk-friendly	CJK 加粗等预处理
fflate	部分扩展（如 PlantUML）可能用到

Supported Markdown Features

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	
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

Frontmatter

Supports YAML frontmatter for metadata:

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

若 frontmatter 无 title，main 会从正文第一个 #/## 标题提取并写入传给 render 的临时文件 frontmatter，保证最终 HTML 的 <title> 正确；否则 render 会退化为临时文件名（如 temp-article）。

Extension Support

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