Markdown to HTML Converter Skill

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

| Script | Purpose | |--------|---------| | scripts/main.ts | Main entry point |

Preferences (EXTEND.md)

Check EXTEND.md existence (priority order):

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

Workflow

Step 0: Pre-check (Chinese Content)

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

Step 1: Determine Theme

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)
baoyu-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):

# Check baoyu-post-to-wechat EXTEND.md for 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 (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) |

Step 1.5: Determine Citation Mode

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.

Step 2: Convert

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

Step 3: Report Result

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

Usage

${BUN_X} {baseDir}/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 | | | --cite | Convert external links to bottom citations, append 引用链接 section | false (off) | | --keep-title | Keep the first heading in content | false (removed) | | --help | Show help | |

Color Presets:

| Name | Hex | Label | |------|-----|-------| | blue | #0F4C81 | Classic Blue | | green | #009874 | Emerald Green | | vermilion | #FA5151 | Vibrant Vermilion | | yellow | #FECE00 | Lemon Yellow | | purple | #92617E | Lavender Purple | | sky | #55C9EA | Sky Blue | | rose | #B76E79 | Rose Gold | | olive | #556B2F | Olive Green | | black | #333333 | Graphite Black | | gray | #A9A9A9 | Smoke Gray | | pink | #FFB7C5 | Sakura Pink | | red | #A93226 | China Red | | orange | #D97757 | Warm Orange (modern default) |

Examples:

# Basic conversion (uses default theme, removes first heading)
${BUN_X} {baseDir}/scripts/main.ts article.md

# With specific theme
${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

# Enable bottom citations for ordinary external links
${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

# Override title
${BUN_X} {baseDir}/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 | 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) |

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 | ![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|annotation} | | Mermaid | ```mermaid diagrams | | PlantUML | ```plantuml diagrams |

Frontmatter

Supports YAML frontmatter for metadata:

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

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

Extension Support

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

Agent Skills: Markdown to HTML Converter

Install this agent skill to your local

Skill Files