1---
2name: baoyu-markdown-to-html
3description: Converts Markdown to styled HTML with WeChat-compatible themes. Supports code highlighting, math, PlantUML, footnotes, alerts, infographics, and optional bottom citations for external links. Use when user asks for "markdown to html", "convert md to html", "md 转 html", "微信外链转底部引用", or needs styled HTML output from markdown.
4version: 1.56.1
5metadata:
6  openclaw:
7    homepage: https://github.com/JimLiu/baoyu-skills#baoyu-markdown-to-html
8    requires:
9      anyBins:
10        - bun
11        - npx
12---
13 
14# Markdown to HTML Converter
15 
16Converts Markdown files to beautifully styled HTML with inline CSS, optimized for WeChat Official Account and other platforms.
17 
18## User Input Tools
19 
20When this skill prompts the user, follow this tool-selection rule (priority order):
21 
221. **Prefer built-in user-input tools** exposed by the current agent runtime — e.g., `AskUserQuestion`, `request_user_input`, `clarify`, `ask_user`, or any equivalent.
232. **Fallback**: if no such tool exists, emit a numbered plain-text message and ask the user to reply with the chosen number/answer for each question.
243. **Batching**: if the tool supports multiple questions per call, combine all applicable questions into a single call; if only single-question, ask them one at a time in priority order.
25 
26Concrete `AskUserQuestion` references below are examples — substitute the local equivalent in other runtimes.
27 
28## Script Directory
29 
30**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.
31 
32| Script | Purpose |
33|--------|---------|
34| `scripts/main.ts` | Main entry point |
35 
36## Preferences (EXTEND.md)
37 
38Check EXTEND.md in priority order — the first one found wins:
39 
40| Priority | Path | Scope |
41|----------|------|-------|
42| 1 | `.baoyu-skills/baoyu-markdown-to-html/EXTEND.md` | Project |
43| 2 | `${XDG_CONFIG_HOME:-$HOME/.config}/baoyu-skills/baoyu-markdown-to-html/EXTEND.md` | XDG |
44| 3 | `$HOME/.baoyu-skills/baoyu-markdown-to-html/EXTEND.md` | User home |
45 
46If none found, use defaults.
47 
48**EXTEND.md supports**: default theme, custom CSS variables, code block style.
49 
50## Workflow
51 
52### Step 0: Pre-check (Chinese Content)
53 
54**Condition**: Only execute if input file contains Chinese text.
55 
56**Detection**:
571. Read input markdown file
582. Check if content contains CJK characters (Chinese/Japanese/Korean)
593. If no CJK content → skip to Step 1
60 
61**Format Suggestion**:
62 
63If CJK content detected AND `baoyu-format-markdown` skill is available:
64 
65Use `AskUserQuestion` to ask whether to format first. Formatting can fix:
66- Bold markers with punctuation inside causing `**` parse failures
67- CJK/English spacing issues
68 
69**If user agrees**: Invoke `baoyu-format-markdown` skill to format the file, then use formatted file as input.
70 
71**If user declines**: Continue with original file.
72 
73### Step 1: Determine Theme
74 
75**Theme resolution order** (first match wins):
761. User explicitly specified theme (CLI `--theme` or conversation)
772. EXTEND.md `default_theme` (this skill's own EXTEND.md, checked in Step 0)
783. `baoyu-post-to-wechat` EXTEND.md `default_theme` (cross-skill fallback)
794. If none found → use AskUserQuestion to confirm
80 
81**Cross-skill EXTEND.md check** (only if this skill's EXTEND.md has no `default_theme`):
82 
83Read `$HOME/.baoyu-skills/baoyu-post-to-wechat/EXTEND.md` if it exists and look for a `default_theme:` line. Use the value if present; otherwise fall through.
84 
85**If theme is resolved from EXTEND.md**: Use it directly, do NOT ask the user.
86 
87**If no default found**: use `AskUserQuestion` to confirm a theme from the [Themes](#themes) table below.
88 
89### Step 1.5: Determine Citation Mode
90 
91**Default**: Off. Do not ask by default.
92 
93**Enable only if the user explicitly asks** for "微信外链转底部引用", "底部引用", "文末引用", or passes `--cite`.
94 
95**Behavior when enabled**:
96- Ordinary external links are rendered with numbered superscripts and collected under a final `引用链接` section.
97- `https://mp.weixin.qq.com/...` links stay as direct links and are not moved to the bottom.
98- Bare links where link text equals URL stay inline.
99 
100### Step 2: Convert
101 
102```bash
103${BUN_X} {baseDir}/scripts/main.ts <markdown_file> --theme <theme> [--cite]
104```
105 
106### Step 3: Report Result
107 
108Display the output path from JSON result. If backup was created, mention it.
109 
110## Usage
111 
112```bash
113${BUN_X} {baseDir}/scripts/main.ts <markdown_file> [options]
114```
115 
116**Options:**
117 
118| Option | Description | Default |
119|--------|-------------|---------|
120| `--theme <name>` | Theme name (default, grace, simple, modern) | default |
121| `--color <name\|hex>` | Primary color: preset name or hex value | theme default |
122| `--font-family <name>` | Font: sans, serif, serif-cjk, mono, or CSS value | theme default |
123| `--font-size <N>` | Font size: 14px, 15px, 16px, 17px, 18px | 16px |
124| `--title <title>` | Override title from frontmatter | |
125| `--cite` | Convert external links to bottom citations, append `引用链接` section | false (off) |
126| `--keep-title` | Keep the first heading in content | false (removed) |
127| `--help` | Show help | |
128 
129**Color Presets:**
130 
131| Name | Hex | Label |
132|------|-----|-------|
133| blue | #0F4C81 | Classic Blue |
134| green | #009874 | Emerald Green |
135| vermilion | #FA5151 | Vibrant Vermilion |
136| yellow | #FECE00 | Lemon Yellow |
137| purple | #92617E | Lavender Purple |
138| sky | #55C9EA | Sky Blue |
139| rose | #B76E79 | Rose Gold |
140| olive | #556B2F | Olive Green |
141| black | #333333 | Graphite Black |
142| gray | #A9A9A9 | Smoke Gray |
143| pink | #FFB7C5 | Sakura Pink |
144| red | #A93226 | China Red |
145| orange | #D97757 | Warm Orange (modern default) |
146 
147**Examples:**
148 
149```bash
150# Basic conversion (uses default theme, removes first heading)
151${BUN_X} {baseDir}/scripts/main.ts article.md
152 
153# With specific theme
154${BUN_X} {baseDir}/scripts/main.ts article.md --theme grace
155 
156# Theme with custom color
157${BUN_X} {baseDir}/scripts/main.ts article.md --theme modern --color red
158 
159# Enable bottom citations for ordinary external links
160${BUN_X} {baseDir}/scripts/main.ts article.md --cite
161 
162# Keep the first heading in content
163${BUN_X} {baseDir}/scripts/main.ts article.md --keep-title
164 
165# Override title
166${BUN_X} {baseDir}/scripts/main.ts article.md --title "My Article"
167```
168 
169## Output
170 
171**File location**: Same directory as input markdown file.
172- Input: `/path/to/article.md`
173- Output: `/path/to/article.html`
174 
175**Conflict handling**: If HTML file already exists, it will be backed up first:
176- Backup: `/path/to/article.html.bak-YYYYMMDDHHMMSS`
177 
178**JSON output to stdout:**
179 
180```json
181{
182  "title": "Article Title",
183  "author": "Author Name",
184  "summary": "Article summary...",
185  "htmlPath": "/path/to/article.html",
186  "backupPath": "/path/to/article.html.bak-20260128180000",
187  "contentImages": [
188    {
189      "placeholder": "MDTOHTMLIMGPH_1",
190      "localPath": "/path/to/img.png",
191      "originalPath": "imgs/image.png"
192    }
193  ]
194}
195```
196 
197## Themes
198 
199| Theme | Description |
200|-------|-------------|
201| `default` | Classic - traditional layout, centered title with bottom border, H2 with white text on colored background |
202| `grace` | Elegant - text shadow, rounded cards, refined blockquotes (by @brzhang) |
203| `simple` | Minimal - modern minimalist, asymmetric rounded corners, clean whitespace (by @okooo5km) |
204| `modern` | Modern - large radius, pill-shaped titles, relaxed line height (pair with `--color red` for traditional red-gold style) |
205 
206## Supported Markdown Features
207 
208| Feature | Syntax |
209|---------|--------|
210| Headings | `# H1` to `###### H6` |
211| Bold/Italic | `**bold**`, `*italic*` |
212| Code blocks | ` ```lang ` with syntax highlighting |
213| Inline code | `` `code` `` |
214| Tables | GitHub-flavored markdown tables |
215| Images | `![alt](src)` |
216| Links | `[text](url)`; add `--cite` to move ordinary external links into bottom references |
217| Blockquotes | `> quote` |
218| Lists | `-` unordered, `1.` ordered |
219| Alerts | `> [!NOTE]`, `> [!WARNING]`, etc. |
220| Footnotes | `[^1]` references |
221| Ruby text | `{base|annotation}` |
222| Mermaid | ` ```mermaid ` diagrams |
223| PlantUML | ` ```plantuml ` diagrams |
224 
225## Frontmatter
226 
227Supports YAML frontmatter for metadata:
228 
229```yaml
230---
231title: Article Title
232author: Author Name
233description: Article summary
234---
235```
236 
237If no title is found, extracts from first H1/H2 heading or uses filename.
238 
239## Extension Support
240 
241Custom configurations via EXTEND.md. See **Preferences** section for paths and supported options.
242