Markdown docs

Markdown Formatter

Transforms plain text or markdown into well-structured, reader-friendly markdown. The goal is to help readers quickly grasp key points, highlights, and structure — without changing any original content.

Core principle: Only adjust formatting and fix obvious typos. Never add, delete, or rewrite content.

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

Scripts in scripts/ subdirectory. {baseDir} = this SKILL.md's directory path. 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 with CLI options (uses remark-cjk-friendly for CJK emphasis)
scripts/quotes.ts	Replace ASCII quotes with fullwidth quotes
scripts/autocorrect.ts	Add CJK/English spacing via autocorrect

Preferences (EXTEND.md)

Check EXTEND.md in priority order — the first one found wins:

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

If none found, use defaults — no first-time setup required for this skill.

EXTEND.md supports:

Setting	Values	Default	Description
auto_select	true/false	false	Skip both title and summary selection, auto-pick best
auto_select_title	true/false	false	Skip title selection only
auto_select_summary	true/false	false	Skip summary selection only
Other	—	—	Default formatting options, typography preferences

Usage

The workflow has two phases: Analyze (understand the content) then Format (apply formatting). Claude performs content analysis and formatting (Steps 1-5), then runs the script for typography fixes (Step 6).

Workflow

Step 1: Read & Detect Content Type

Read the user-specified file, then detect content type:

Indicator	Classification
Has --- YAML frontmatter	Markdown
Has #, ##, ### headings	Markdown
Has **bold**, *italic*, lists, code blocks, blockquotes	Markdown
None of above	Plain text

If Markdown detected, use AskUserQuestion to ask:

Detected existing markdown formatting. What would you like to do?

1. Optimize formatting (Recommended)
   - Analyze content, improve headings, bold, lists for readability
   - Run typography script (spacing, emphasis fixes)
   - Output: {filename}-formatted.md

2. Keep original formatting
   - Preserve existing markdown structure
   - Run typography script only
   - Output: {filename}-formatted.md

3. Typography fixes only
   - Run typography script on original file in-place
   - No copy created, modifies original file directly

Based on user choice:

• Optimize: Continue to Step 2 (full workflow)
• Keep original: Skip to Step 5, copy file then run Step 6
• Typography only: Skip to Step 6, run on original file directly

Step 2: Analyze Content (Reader's Perspective)

Read the entire content carefully. Think from a reader's perspective: what would help them quickly understand and remember the key information?

Produce an analysis covering these dimensions:

2.1 Highlights & Key Insights

• Core arguments or conclusions the author makes
• Surprising facts, data points, or counterintuitive claims
• Memorable quotes or well-phrased sentences (golden quotes)

2.2 Structure Assessment

• Does the content have a clear logical flow? What is it?
• Are there natural section boundaries that lack headings?
• Are there long walls of text that could benefit from visual breaks?

2.3 Reader-Important Information

• Actionable advice or takeaways
• Definitions, explanations of key concepts
• Lists or enumerations buried in prose
• Comparisons or contrasts that would be clearer as tables

2.4 Formatting Issues

• Missing or inconsistent heading hierarchy
• Paragraphs that mix multiple topics
• Parallel items written as prose instead of lists
• Code, commands, or technical terms not marked as code
• Obvious typos or formatting errors

Save analysis to file: {original-filename}-analysis.md

The analysis file serves as the blueprint for Step 3. Use this format:

# Content Analysis: {filename}

## Highlights & Key Insights
- [list findings]

## Structure Assessment
- Current flow: [describe]
- Suggested sections: [list heading candidates with brief rationale]

## Reader-Important Information
- [list actionable items, key concepts, buried lists, potential tables]

## Formatting Issues
- [list specific issues with location references]

## Typos Found
- [list any obvious typos with corrections, or "None found"]

Step 3: Check/Create Frontmatter, Title & Summary

Check for YAML frontmatter (--- block). Create if missing.

Field	Processing
title	See Title Generation below
slug	Infer from file path or generate from title
summary	One-sentence concise summary (see Summary Generation below)
description	Longer descriptive summary (see Summary Generation below)
coverImage	Check if imgs/cover.png exists in same directory; if so, use relative path

Title Generation

Whether or not a title already exists, run the title optimization flow unless auto_select_title is set.

Preparation — read the full text and extract:

• Core argument (one sentence: "what is this article about?")
• Most impactful opinion or conclusion
• Reader pain point or curiosity trigger
• Most memorable metaphor or golden quote

Generate candidates using formulas from references/title-formulas.md:

1. Select the 2-3 best-matching hook formulas based on the article's content, tone, and structure (see "When to pick each formula" in the reference)
2. Generate 1-2 straightforward titles (descriptive or declarative, no formula — clear and accurate)
3. If the user specifies a direction (e.g., "make it suspenseful"), prioritize that direction
4. Total: 4-5 candidates

Present via AskUserQuestion:

Pick a title:

1. [Hook title A] — (recommended) [formula name]
2. [Hook title B] — [formula name]
3. [Hook title C] — [formula name]
4. [Straightforward title D] — straightforward
5. [Straightforward title E] — straightforward

Enter number, or type a custom title:

Put the strongest hook first and mark it (recommended). See references/title-formulas.md for principles and prohibited patterns.

If the first line is an H1, extract it to frontmatter and remove it from the body. If frontmatter already has a title, include it as context but still generate fresh candidates — the existing title may be weak.

Skip behavior: If auto_select: true or auto_select_title: true, skip the user prompt and use the top candidate directly.

Summary Generation

Generate two versions directly (no user selection), both stored in frontmatter:

Field	Length	Purpose
summary	1 sentence, ~50-80 chars	Concise hook — for feeds, social sharing, SEO meta
description	2-3 sentences, ~100-200 chars	Richer context — for article previews, newsletter blurbs

Principles:

• Convey core value to the reader, not just the topic
• Use concrete details (numbers, outcomes, specific methods) over vague descriptions
• summary should be punchy and self-contained; description can expand with supporting details
• If frontmatter already has summary or description, keep the existing one and only generate the missing field

Prohibited patterns:

• "This article introduces...", "This article explores..."
• Pure topic description without value proposition
• Repeating the title in different words

Once the title is in frontmatter, the body should NOT contain an H1 (avoid duplication).

Step 4: Format Content

Apply formatting guided by the Step 2 analysis. The goal is making the content scannable and the key points impossible to miss.

Formatting toolkit:

Element	When to use	Format
Headings	Natural topic boundaries, section breaks	##, ### hierarchy
Bold	Key conclusions, important terms, core takeaways	**bold**
Unordered lists	Parallel items, feature lists, examples	- item
Ordered lists	Sequential steps, ranked items, procedures	1. item
Tables	Comparisons, structured data, option matrices	Markdown table
Code	Commands, file paths, technical terms, variable names	`inline` or fenced blocks
Blockquotes	Notable quotes, important warnings, cited text	> quote
Separators	Major topic transitions	---

Formatting principles — what NOT to do:

• Do NOT add sentences, explanations, or commentary
• Do NOT delete or shorten any content
• Do NOT rephrase or rewrite the author's words
• Do NOT add headings that editorialize (e.g., "Amazing Discovery" — use neutral descriptive headings)
• Do NOT over-format: not every sentence needs bold, not every paragraph needs a heading

Formatting principles — what TO do:

• Preserve the author's voice, tone, and every word
• Bold key conclusions and core takeaways — the sentences a reader would highlight
• Extract parallel items from prose into lists only when the structure is clearly there
• Add headings where the topic genuinely shifts — prefer vivid, specific headings over generic ones (e.g."3 vs " over )
• Use tables for comparisons or structured data buried in prose
• Use blockquotes for golden quotes, memorable statements, or important warnings
• Fix obvious typos (based on Step 2 findings)

Step 5: Save Formatted File

Save as {original-filename}-formatted.md

Backup existing file:

if [ -f "{filename}-formatted.md" ]; then
  mv "{filename}-formatted.md" "{filename}-formatted.backup-$(date +%Y%m%d-%H%M%S).md"
fi

Step 6: Execute Typography Script

Run the formatting script on the output file:

${BUN_X} {baseDir}/scripts/main.ts {output-file-path} [options]

Script Options:

Option	Short	Description	Default
--quotes	-q	Replace ASCII quotes with fullwidth quotes "..."	false
--no-quotes		Do not replace quotes
--spacing	-s	Add CJK/English spacing via autocorrect	true
--no-spacing		Do not add CJK/English spacing
--emphasis	-e	Fix CJK emphasis punctuation issues	true
--no-emphasis		Do not fix CJK emphasis issues

Examples:

# Default: spacing + emphasis enabled, quotes disabled
${BUN_X} {baseDir}/scripts/main.ts article.md

# Enable all features including quote replacement
${BUN_X} {baseDir}/scripts/main.ts article.md --quotes

# Only fix emphasis issues, skip spacing
${BUN_X} {baseDir}/scripts/main.ts article.md --no-spacing

Script performs (based on options):

1. Fix CJK emphasis/bold punctuation issues (default: enabled)
2. Add CJK/English mixed text spacing via autocorrect (default: enabled)
3. Replace ASCII quotes with fullwidth quotes (default: disabled)
4. Format frontmatter YAML (always enabled)

Step 7: Completion Report

Display a report summarizing all changes made:

**Formatting Complete**

**Files:**
- Analysis: {filename}-analysis.md
- Formatted: {filename}-formatted.md

**Content Analysis Summary:**
- Highlights found: X key insights
- Golden quotes: X memorable sentences
- Formatting issues fixed: X items

**Changes Applied:**
- Frontmatter: [added/updated] (title, slug, summary)
- Headings added: X (##: N, ###: N)
- Bold markers added: X
- Lists created: X (from prose → list conversion)
- Tables created: X
- Code markers added: X
- Blockquotes added: X
- Typos fixed: X [list each: "original" → "corrected"]

**Typography Script:**
- CJK spacing: [applied/skipped]
- Emphasis fixes: [applied/skipped]
- Quote replacement: [applied/skipped]

Adjust the report to reflect actual changes — omit categories where no changes were made.

Notes

• Preserve original writing style and tone
• Specify correct language for code blocks (e.g., python, javascript)
• Maintain CJK/English spacing standards
• The analysis file is a working document — it helps maintain consistency between what was identified and what was formatted

Extension Support

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

---

Merged from: 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.

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

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 in priority order — the first one 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

If none found, use defaults.

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

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

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

If theme is resolved from EXTEND.md: Use it directly, do NOT ask the user.

If no default found: use AskUserQuestion to confirm a theme from the Themes table below.

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

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

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">…</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

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	
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 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
PlantUML	```plantuml diagrams

Frontmatter

Supports YAML frontmatter for metadata:

---
title: Article Title
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.