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 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 .baoyu-skills/baoyu-markdown-to-html/EXTEND.md && echo "project"

Then user-level (cross-platform: $HOME works on macOS/Linux/WSL)

test -f "$HOME/.baoyu-skills/baoyu-markdown-to-html/EXTEND.md" && echo "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`):

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

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 Theme - Traditional layout, centered title with bottom border, secondary headings in white text on colored background
`grace`	Elegant Theme - Text shadow, rounded card, refined blockquote
`simple`	Minimal Theme - Modern minimalist style, asymmetrical rounded corners, clean whitespace
`modern`	Modern Theme - Large rounded corners, pill-shaped headings, loose line spacing (paired with `--color red` to recreate the traditional red-gold style)

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, 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
`--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 Orange
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	Misty Gray
pink	#FFB7C5	Cherry Blossom Pink
red	#A93226	China Red
orange	#D97757	Warm Orange (modern default)

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

# Theme with custom color
npx -y bun ${SKILL_DIR}/scripts/main.ts article.md --theme modern --color red

# 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`	Classic Theme - Traditional layout, centered title with bottom border, secondary headings in white text on colored background
`grace`	Elegant Theme - Text shadow, rounded card, refined blockquote (by @brzhang)
`simple`	Minimal Theme - Modern minimalist style, asymmetrical rounded corners, clean whitespace (by @okooo5km)
`modern`	Modern Theme - Large rounded corners, pill-shaped headings, loose line spacing (paired with `--color red` to recreate the 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)` 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
---

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.

OpenClaw Migration Notes

Migration mode: OpenClaw native first
Preserved directories:
- scripts: yes
- references: no
- prompts: no
External dependencies: bun, social-platform-access
Risk level: high
Environment variables (detected): HOME
Config compatibility: keep original .baoyu-skills/<skill>/EXTEND.md behavior and add OpenClaw-compatible path in runtime wrappers when needed.

OpenClaw Preflight Checks

Confirm bun is available when script examples use npx -y bun ....
Confirm account session/cookies are valid before posting or scraping operations.

Detected env vars: HOME

OpenClaw Failure Fallback

If runtime dependency is missing, stop execution and return exact install/setup command.
If platform blocks automation, return manual publish/export instructions instead of retry loops.
For high-risk workflows, require explicit user confirmation before irreversible actions.