jimliu avatar

Baoyu Markdown To Html

jimliu/baoyu-skills
8.9k

This skill converts Markdown files into visually appealing HTML with inline CSS, optimized for platforms like WeChat Official Accounts. It supports theme customization, citation handling, and formatting adjustments, making it suitable for content creators and developers who need to produce styled HTML from Markdown. The tool offers flexible configuration options, including language-specific formatting and preservation of key content elements.

npx skills add https://github.com/jimliu/baoyu-skills --skill baoyu-markdown-to-html

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:

  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.

Step 1: Determine Theme

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):
# 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 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.

GitHub Owner

Owner: jimliu

GitHub Links

SKILL.md

name: baoyu-markdown-to-html description: 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. version: 1.56.1 metadata: openclaw: homepage: https://github.com/JimLiu/baoyu-skills#baoyu-markdown-to-html requires: anyBins: - bun - npx

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.

ScriptPurpose
scripts/main.tsMain 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:

  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.

Step 1: Determine Theme

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

ThemeDescription
default (Recommended)Classic - traditional layout, centered title with bottom border, H2 with white text on colored background
graceElegant - text shadow, rounded cards, refined blockquotes
simpleMinimal - modern minimalist, asymmetric rounded corners, clean whitespace
modernModern - 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:

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
--citeConvert external links to bottom citations, append 引用链接 sectionfalse (off)
--keep-titleKeep the first heading in contentfalse (removed)
--helpShow 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:
# 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

ThemeDescription
defaultClassic - traditional layout, centered title with bottom border, H2 with white text on colored background
graceElegant - text shadow, rounded cards, refined blockquotes (by @brzhang)
simpleMinimal - modern minimalist, asymmetric rounded corners, clean whitespace (by @okooo5km)
modernModern - large radius, pill-shaped titles, relaxed line height (pair with --color red for traditional red-gold style)

Supported Markdown Features

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

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.

More skills

J
Baoyu Post To Weibo

jimliu

J
Baoyu Compress Image

jimliu

J
Baoyu Danger Gemini Web

jimliu