{"slug":"baoyu-markdown-to-html","title":"Markdown \u8f6c\u516c\u4f17\u53f7 HTML","description":"\u628a Markdown \u8f6c\u6210\u9002\u914d\u516c\u4f17\u53f7\u7684\u4e3b\u9898\u5316 HTML\uff0c\u652f\u6301\u4ee3\u7801\u9ad8\u4eae\u3001\u516c\u5f0f\u4e0e Mermaid\u3002","category":"\u53d1\u5e03\u4e0e\u8fd0\u8425","tags":["\u516c\u4f17\u53f7","\u6392\u7248","HTML"],"author":"\u5b9d\u7389","source_url":"https://github.com/JimLiu/baoyu-skills/blob/main/skills/baoyu-markdown-to-html/SKILL.md","license":"MIT","status":"published","verification":"source_reviewed","verification_notes":"\u6765\u6e90 JimLiu/baoyu-skills\uff08skills/baoyu-markdown-to-html/SKILL.md\uff09\uff0c\u672c\u5730\u6253\u5305\u4e0a\u4f20\uff1b\u672a\u6267\u884c\u5305\u5185\u811a\u672c\u3002","revision":"c284b0523b7741bf82b678862d367ca6","created_at":"2026-10-28T08:05:09+00:00","updated_at":"2026-10-28T08:05:16+00:00","source_repo":"","source_path":"","source_commit":"","source_updated_at":"","stars":0,"proxy_score":null,"score":null,"grade":null,"dimensions":{},"evaluation":{},"installs":0,"platforms":[],"formats":[],"category_slug":"publishing","category_name":"\u53d1\u5e03\u4e0e\u8fd0\u8425","usage_guide":{},"read_url":"https://shiliuai.cn/api/v2/skills/baoyu-markdown-to-html","skill_url":"https://shiliuai.cn/api/v2/skills/baoyu-markdown-to-html/files/SKILL.md","download_url":"https://shiliuai.cn/api/v2/skills/baoyu-markdown-to-html/download","install_url":"https://shiliuai.cn/api/v2/skills/baoyu-markdown-to-html/install","files":[{"path":"SKILL.md","bytes":10060,"url":"https://shiliuai.cn/api/v2/skills/baoyu-markdown-to-html/files/SKILL.md"},{"path":"scripts/bun.lock","bytes":23718,"url":"https://shiliuai.cn/api/v2/skills/baoyu-markdown-to-html/files/scripts/bun.lock"},{"path":"scripts/main.test.ts","bytes":3587,"url":"https://shiliuai.cn/api/v2/skills/baoyu-markdown-to-html/files/scripts/main.test.ts"},{"path":"scripts/main.ts","bytes":12398,"url":"https://shiliuai.cn/api/v2/skills/baoyu-markdown-to-html/files/scripts/main.ts"},{"path":"scripts/package.json","bytes":170,"url":"https://shiliuai.cn/api/v2/skills/baoyu-markdown-to-html/files/scripts/package.json"}],"content":"---\nname: baoyu-markdown-to-html\ndescription: Converts Markdown to styled HTML with WeChat-compatible themes. Supports code highlighting, math, Mermaid (rendered to PNG via headless Chrome), PlantUML, footnotes, alerts, infographics, and optional bottom citations for external links. Use when user asks for \"markdown to html\", \"convert md to html\", \"md \u8f6c html\", \"\u5fae\u4fe1\u5916\u94fe\u8f6c\u5e95\u90e8\u5f15\u7528\", or needs styled HTML output from markdown.\nversion: 1.117.3\nmetadata:\n  openclaw:\n    homepage: https://github.com/JimLiu/baoyu-skills#baoyu-markdown-to-html\n    requires:\n      anyBins:\n        - bun\n        - npx\n---\n\n# Markdown to HTML Converter\n\nConverts Markdown files to beautifully styled HTML with inline CSS, optimized for WeChat Official Account and other platforms.\n\n## User Input Tools\n\nWhen this skill prompts the user, follow this tool-selection rule (priority order):\n\n1. **Prefer built-in user-input tools** exposed by the current agent runtime \u2014 e.g., `AskUserQuestion`, `request_user_input`, `clarify`, `ask_user`, or any equivalent.\n2. **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.\n3. **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.\n\nConcrete `AskUserQuestion` references below are examples \u2014 substitute the local equivalent in other runtimes.\n\n## Script Directory\n\n**Agent Execution**: Determine this SKILL.md directory as `{baseDir}`. Resolve `${BUN_X}` runtime: if `bun` installed \u2192 `bun`; if `npx` available \u2192 `npx -y bun`; else suggest installing bun. Replace `{baseDir}` and `${BUN_X}` with actual values.\n\n| Script | Purpose |\n|--------|---------|\n| `scripts/main.ts` | Main entry point |\n\n## Preferences (EXTEND.md)\n\nCheck EXTEND.md in priority order \u2014 the first one found wins:\n\n| Priority | Path | Scope |\n|----------|------|-------|\n| 1 | `.baoyu-skills/baoyu-markdown-to-html/EXTEND.md` | Project |\n| 2 | `${XDG_CONFIG_HOME:-$HOME/.config}/baoyu-skills/baoyu-markdown-to-html/EXTEND.md` | XDG |\n| 3 | `$HOME/.baoyu-skills/baoyu-markdown-to-html/EXTEND.md` | User home |\n\nIf none found, use defaults.\n\n**EXTEND.md supports**: default theme, custom CSS variables, code block style, mermaid defaults (`mermaid_theme`, `mermaid_scale`, `mermaid_background`).\n\n## Workflow\n\n### Step 0: Pre-check (Chinese Content)\n\n**Condition**: Only execute if input file contains Chinese text.\n\n**Detection**:\n1. Read input markdown file\n2. Check if content contains CJK characters (Chinese/Japanese/Korean)\n3. If no CJK content \u2192 skip to Step 1\n\n**Format Suggestion**:\n\nIf CJK content detected AND `baoyu-format-markdown` skill is available:\n\nUse `AskUserQuestion` to ask whether to format first. Formatting can fix:\n- Bold markers with punctuation inside causing `**` parse failures\n- CJK/English spacing issues\n\n**If user agrees**: Invoke `baoyu-format-markdown` skill to format the file, then use formatted file as input.\n\n**If user declines**: Continue with original file.\n\n### Step 1: Determine Theme\n\n**Theme resolution order** (first match wins):\n1. User explicitly specified theme (CLI `--theme` or conversation)\n2. EXTEND.md `default_theme` (this skill's own EXTEND.md, checked in Step 0)\n3. `baoyu-post-to-wechat` EXTEND.md `default_theme` (cross-skill fallback)\n4. If none found \u2192 use AskUserQuestion to confirm\n\n**Cross-skill EXTEND.md check** (only if this skill's EXTEND.md has no `default_theme`):\n\nRead `$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.\n\n**If theme is resolved from EXTEND.md**: Use it directly, do NOT ask the user.\n\n**If no default found**: use `AskUserQuestion` to confirm a theme from the [Themes](#themes) table below.\n\n### Step 1.5: Determine Citation Mode\n\n**Default**: Off. Do not ask by default.\n\n**Enable only if the user explicitly asks** for \"\u5fae\u4fe1\u5916\u94fe\u8f6c\u5e95\u90e8\u5f15\u7528\", \"\u5e95\u90e8\u5f15\u7528\", \"\u6587\u672b\u5f15\u7528\", or passes `--cite`.\n\n**Behavior when enabled**:\n- Ordinary external links are rendered with numbered superscripts and collected under a final `\u5f15\u7528\u94fe\u63a5` section.\n- `https://mp.weixin.qq.com/...` links stay as direct links and are not moved to the bottom.\n- Bare links where link text equals URL stay inline.\n\n### Step 2: Convert\n\n```bash\n${BUN_X} {baseDir}/scripts/main.ts <markdown_file> --theme <theme> [--cite]\n```\n\n### Step 3: Report Result\n\nDisplay the output path from JSON result. If backup was created, mention it.\n\n## Usage\n\n```bash\n${BUN_X} {baseDir}/scripts/main.ts <markdown_file> [options]\n```\n\n**Options:**\n\n| Option | Description | Default |\n|--------|-------------|---------|\n| `--theme <name>` | Theme name (default, grace, simple, modern) | default |\n| `--color <name\\|hex>` | Primary color: preset name or hex value | theme default |\n| `--font-family <name>` | Font: sans, serif, serif-cjk, mono, or CSS value | theme default |\n| `--font-size <N>` | Font size: 14px, 15px, 16px, 17px, 18px | 16px |\n| `--title <title>` | Override title from frontmatter | |\n| `--cite` | Convert external links to bottom citations, append `\u5f15\u7528\u94fe\u63a5` section | false (off) |\n| `--keep-title` | Keep the first heading in content | false (removed) |\n| `--mermaid-theme <name>` | Mermaid theme: `default`, `forest`, `dark`, `neutral`, `base` | default |\n| `--mermaid-scale <N>` | Mermaid render scale (positive number \u2264 4) | 2 |\n| `--mermaid-width <N>` | Mermaid target display width in CSS px; PNG is rendered at `width \u00d7 scale` pixels when the diagram is narrower than this | 860 |\n| `--mermaid-bg <value>` | Mermaid background: `white`, `transparent`, or `#hex` | white |\n| `--no-mermaid` | Skip Mermaid PNG rendering; emit `<pre class=\"mermaid\">` fallback | false |\n| `--help` | Show help | |\n\n**Color Presets:**\n\n| Name | Hex | Label |\n|------|-----|-------|\n| blue | #0F4C81 | Classic Blue |\n| green | #009874 | Emerald Green |\n| vermilion | #FA5151 | Vibrant Vermilion |\n| yellow | #FECE00 | Lemon Yellow |\n| purple | #92617E | Lavender Purple |\n| sky | #55C9EA | Sky Blue |\n| rose | #B76E79 | Rose Gold |\n| olive | #556B2F | Olive Green |\n| black | #333333 | Graphite Black |\n| gray | #A9A9A9 | Smoke Gray |\n| pink | #FFB7C5 | Sakura Pink |\n| red | #A93226 | China Red |\n| orange | #D97757 | Warm Orange (modern default) |\n\n**Examples:**\n\n```bash\n# Basic conversion (uses default theme, removes first heading)\n${BUN_X} {baseDir}/scripts/main.ts article.md\n\n# With specific theme\n${BUN_X} {baseDir}/scripts/main.ts article.md --theme grace\n\n# Theme with custom color\n${BUN_X} {baseDir}/scripts/main.ts article.md --theme modern --color red\n\n# Enable bottom citations for ordinary external links\n${BUN_X} {baseDir}/scripts/main.ts article.md --cite\n\n# Keep the first heading in content\n${BUN_X} {baseDir}/scripts/main.ts article.md --keep-title\n\n# Override title\n${BUN_X} {baseDir}/scripts/main.ts article.md --title \"My Article\"\n```\n\n## Output\n\n**File location**: Same directory as input markdown file.\n- Input: `/path/to/article.md`\n- Output: `/path/to/article.html`\n\n**Conflict handling**: If HTML file already exists, it will be backed up first:\n- Backup: `/path/to/article.html.bak-YYYYMMDDHHMMSS`\n\n**JSON output to stdout:**\n\n```json\n{\n  \"title\": \"Article Title\",\n  \"author\": \"Author Name\",\n  \"summary\": \"Article summary...\",\n  \"htmlPath\": \"/path/to/article.html\",\n  \"backupPath\": \"/path/to/article.html.bak-20260128180000\",\n  \"contentImages\": [\n    {\n      \"placeholder\": \"MDTOHTMLIMGPH_1\",\n      \"localPath\": \"/path/to/img.png\",\n      \"originalPath\": \"imgs/image.png\"\n    }\n  ],\n  \"mermaidImages\": [\n    {\n      \"hash\": \"a1b2c3d4e5f6\",\n      \"localPath\": \"/path/to/imgs/.mermaid-cache/mermaid-a1b2c3d4e5f6.png\",\n      \"cached\": false\n    }\n  ]\n}\n```\n\n**Mermaid rendering**: Code blocks fenced as ` ```mermaid ` are rendered to PNGs via headless Chrome (CDP) and cached at `imgs/.mermaid-cache/mermaid-<hash>.png`. The cache key includes the code, theme, scale, target width, background, and mermaid version. Add `imgs/.mermaid-cache/` to `.gitignore` if you do not want generated diagrams checked in. Requires Chrome/Chromium/Edge on the system; otherwise the block falls back to `<pre class=\"mermaid\">\u2026</pre>` and conversion still succeeds.\n\n## Themes\n\n| Theme | Description |\n|-------|-------------|\n| `default` | Classic - traditional layout, centered title with bottom border, H2 with white text on colored background |\n| `grace` | Elegant - text shadow, rounded cards, refined blockquotes (by @brzhang) |\n| `simple` | Minimal - modern minimalist, asymmetric rounded corners, clean whitespace (by @okooo5km) |\n| `modern` | Modern - large radius, pill-shaped titles, relaxed line height (pair with `--color red` for traditional red-gold style) |\n\n## Supported Markdown Features\n\n| Feature | Syntax |\n|---------|--------|\n| Headings | `# H1` to `###### H6` |\n| Bold/Italic | `**bold**`, `*italic*` |\n| Code blocks | ` ```lang ` with syntax highlighting |\n| Inline code | `` `code` `` |\n| Tables | GitHub-flavored markdown tables |\n| Images | `![alt](src)` |\n| Links | `[text](url)`; add `--cite` to move ordinary external links into bottom references |\n| Blockquotes | `> quote` |\n| Lists | `-` unordered, `1.` ordered |\n| Alerts | `> [!NOTE]`, `> [!WARNING]`, etc. |\n| Footnotes | `[^1]` references |\n| Ruby text | `{base|annotation}` |\n| Mermaid | ` ```mermaid ` blocks rendered to local PNG via headless Chrome (cached under `imgs/.mermaid-cache/`); falls back to `<pre class=\"mermaid\">` if Chrome is unavailable or rendering fails |\n| PlantUML | ` ```plantuml ` diagrams |\n\n## Frontmatter\n\nSupports YAML frontmatter for metadata:\n\n```yaml\n---\ntitle: Article Title\nauthor: Author Name\ndescription: Article summary\n---\n```\n\nIf no title is found, extracts from first H1/H2 heading or uses filename.\n\n## Extension Support\n\nCustom configurations via EXTEND.md. See **Preferences** section for paths and supported options.\n","usage":"\u8bfb\u53d6 SKILL.md\uff0c\u5e76\u6309\u9700\u8bfb\u53d6\u914d\u5957\u6587\u4ef6\uff1b\u4e0b\u8f7d ZIP \u83b7\u53d6\u5b8c\u6574\u5305\u3002\u6280\u80fd\u662f\u4efb\u52a1\u65b9\u6cd5\uff0c\u4e0d\u6388\u4e88\u65b0\u589e\u8d26\u6237\u3001\u4ed8\u8d39\u6216\u7cfb\u7edf\u6743\u9650\u3002"}