Index of every page on this site: llms.txt
All skills
jimliu avatar

/baoyu-markdown-to-html

@bf1ff07 official
by Jim Liu 宝玉jimliu/baoyu-skills28k stars
3,011
Run it yourself

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 转 html", "微信外链转底部引用", or needs styled HTML output from markdown.

Use this Skill: https://skilld.dev/gh/jimliu/baoyu-skills/baoyu-markdown-to-html

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈104 tokens for metadata: the name and description. ≈1.9k when used: this file. ≈43 more on demand in 1 file.

Description uses 5.0% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈396 characters, or 5.0%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

Markdown to HTML Converter

Output is HTML with inline CSS, optimized for WeChat Official Account.

User Input Tools

When this skill prompts the user, follow this tool-selection rule (priority order):

  1. Prefer built-in user-input tools exposed by the current agent runtime — e.g., AskUserQuestion, request_user_input, clarify, ask_user, or any equivalent.
  2. 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.
  3. 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.

Concrete AskUserQuestion references below are examples — substitute the local equivalent in other runtimes.

Script Directory

{baseDir} = this SKILL.md's directory. Resolve ${BUN_X}: bun if installed → else npx -y bun → else suggest installing bun.

Script Purpose
scripts/main.ts Main entry point

Preferences (EXTEND.md)

First found wins:

Priority Path Scope
1 .baoyu-skills/baoyu-markdown-to-html/EXTEND.md Project
2 ${XDG_CONFIG_HOME:-$HOME/.config}/baoyu-skills/baoyu-markdown-to-html/EXTEND.md XDG
3 $HOME/.baoyu-skills/baoyu-markdown-to-html/EXTEND.md User home

None found → use defaults.

Supported: default theme, custom CSS variables, code block style, mermaid defaults (mermaid_theme, mermaid_scale, mermaid_background).

Workflow

Step 0: Pre-check (CJK Content)

Only if the input contains CJK characters AND the baoyu-format-markdown skill is available: ask (AskUserQuestion) whether to format first — it fixes ** bold markers broken by inner punctuation and CJK/English spacing. Agree → run baoyu-format-markdown, use the formatted file. Decline → use the original. No CJK → skip to Step 1.

Step 1: Determine Theme

First match wins:

  1. User-specified (CLI --theme or conversation)
  2. This skill's EXTEND.md default_theme
  3. Cross-skill fallback (only if step 2 has none): default_theme: line in $HOME/.baoyu-skills/baoyu-post-to-wechat/EXTEND.md, if it exists
  4. None → ask (AskUserQuestion) with the Themes table

Theme from EXTEND.md → use it directly, do NOT ask.

Step 1.5: Determine Citation Mode

Default off; don't ask. Enable (--cite) only if the user explicitly asks for "微信外链转底部引用", "底部引用", "文末引用", or passes --cite. 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

Show htmlPath from the JSON result; mention backupPath if a backup was created.

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)
--mermaid-theme <name> Mermaid theme: default, forest, dark, neutral, base default
--mermaid-scale <N> Mermaid render scale (positive number ≤ 4) 2
--mermaid-width <N> Mermaid target display width in CSS px; PNG is rendered at width × scale pixels when the diagram is narrower than this 860
--mermaid-bg <value> Mermaid background: white, transparent, or #hex white
--no-mermaid Skip Mermaid PNG rendering; emit <pre class="mermaid"> fallback false
--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:

${BUN_X} {baseDir}/scripts/main.ts article.md                                  # default theme, first heading removed
${BUN_X} {baseDir}/scripts/main.ts article.md --theme modern --color red
${BUN_X} {baseDir}/scripts/main.ts article.md --cite --keep-title --title "My Article"

Output

/path/to/article.md → /path/to/article.html (same directory). An existing HTML file is first backed up to /path/to/article.html.bak-YYYYMMDDHHMMSS.

JSON 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"
    }
  ],
  "mermaidImages": [
    {
      "hash": "a1b2c3d4e5f6",
      "localPath": "/path/to/imgs/.mermaid-cache/mermaid-a1b2c3d4e5f6.png",
      "cached": false
    }
  ]
}

Mermaid: ```mermaid blocks are rendered to PNG via headless Chrome (CDP), cached at imgs/.mermaid-cache/mermaid-<hash>.png (key: code, theme, scale, target width, background, mermaid version; suggest adding the dir to .gitignore). Needs Chrome/Chromium/Edge; if unavailable or rendering fails, falls back to <pre class="mermaid">…</pre> and conversion still succeeds.

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

Standard GFM (headings, emphasis, lists, tables, images, links, blockquotes, inline code) plus:

Feature Syntax
Code blocks ```lang with syntax highlighting
Links [text](url); add --cite to move ordinary external links into bottom references
Alerts > [!NOTE], > [!WARNING], etc.
Footnotes [^1] references
Ruby text `{base
Mermaid ```mermaid (see Output)
PlantUML ```plantuml diagrams

Frontmatter

title, author, description (summary). No title → first H1/H2, else filename.

Extension Support

Custom configuration via EXTEND.md — see Preferences.

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

1 warning18d5 checks · Risk SAFE
  • Gen Agent Trust Hub18d

    The skill converts Markdown to HTML using local TypeScript scripts and external libraries. It performs file system operations including reading inputs, writing outputs, and managing configuration files. The process of rendering user-provided Markdown presents a surface for indirect prompt injection, and the rendering of Mermaid diagrams utilizes a headless browser environment.

  • Socket18d

    No alerts

  • Snyk18d

    Risk: LOW · No issues

  • Runlayer8mo

    72/111 files flagged

  • ZeroLeaks7mo

    1 finding · Score: 86/100

Signed by skilld at bf1ff07. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 3 weeks ago
version
1.117.3
Other metadata
metadata
{
  "openclaw": {
    "homepage": "https://github.com/JimLiu/baoyu-skills#baoyu-markdown-to-html",
    "requires": {
      "anyBins": [
        "bun",
        "npx"
      ]
    }
  }
}
  • markdown
  • html
  • wechat
  • css
  • mermaid
  • plantuml
  • syntax-highlighting
  • conversion

README badge

README badge for jimliu/baoyu-skills/baoyu-markdown-to-html

Converts Markdown files to styled HTML with inline CSS, supporting code highlighting, Mermaid diagrams (rendered to PNG via headless Chrome), PlantUML, footnotes, alerts, and optional bottom citations for external links. Optimized for WeChat Official Accounts with multiple built-in themes (default, grace, simple, modern) and customizable colors and fonts.

Generated from the current SKILL.md.

Does this skill work with Chinese content?
Yes. It detects CJK characters and can optionally format the markdown first using the baoyu-format-markdown skill to fix spacing and punctuation issues before conversion.
What output formats are supported?
The skill converts Markdown to a single HTML file with inline CSS. Mermaid diagrams are rendered to PNG and cached; PlantUML diagrams are also supported.
Can I move external links to the bottom of the page?
Yes, use the `--cite` flag or ask for 'bottom citations' or '微信外链转底部引用'. This converts external links to numbered superscripts and appends a '引用链接' section; WeChat links stay inline.
What themes are available?
Four themes: default (classic centered layout), grace (elegant with shadows), simple (minimalist), and modern (large radius). Each supports custom colors via presets or hex values.
Does this require Chrome or Chromium?
Chrome/Chromium/Edge is required to render Mermaid diagrams to PNG. If unavailable, Mermaid blocks fall back to `<pre class="mermaid">` and conversion still succeeds.

Generated from the current SKILL.md. These answers refresh after source changes.