szeyu/baoyu-format-markdown

Markdown Formatter

Transforms plain text or markdown files into well-structured markdown with proper frontmatter, formatting, and typography.

Script Directory

Scripts in scripts/ subdirectory. Replace ${SKILL_DIR} with this SKILL.md's directory path.

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

Use Bash to check EXTEND.md existence (priority order):

# Check project-level first
test -f .baoyu-skills/baoyu-format-markdown/EXTEND.md && echo "project"

# Then user-level (cross-platform: $HOME works on macOS/Linux/WSL)
test -f "$HOME/.baoyu-skills/baoyu-format-markdown/EXTEND.md" && echo "user"

┌──────────────────────────────────────────────────────────┬───────────────────┐ │ Path │ Location │ ├──────────────────────────────────────────────────────────┼───────────────────┤ │ .baoyu-skills/baoyu-format-markdown/EXTEND.md │ Project directory │ ├──────────────────────────────────────────────────────────┼───────────────────┤ │ $HOME/.baoyu-skills/baoyu-format-markdown/EXTEND.md │ User home │ └──────────────────────────────────────────────────────────┴───────────────────┘

┌───────────┬───────────────────────────────────────────────────────────────────────────┐ │ Result │ Action │ ├───────────┼───────────────────────────────────────────────────────────────────────────┤ │ Found │ Read, parse, apply settings │ ├───────────┼───────────────────────────────────────────────────────────────────────────┤ │ Not found │ Use defaults │ └───────────┴───────────────────────────────────────────────────────────────────────────┘

EXTEND.md Supports: Default formatting options | Summary length preferences

Usage

Claude performs content analysis and formatting (Steps 1-6), then runs the script for typography fixes (Step 7).

Workflow

Step 1: Read Source File

Read the user-specified markdown or plain text file.

Step 1.5: Detect Content Type & Confirm

Content Type Detection:

| Indicator | Classification | |-----------|----------------| | Has --- YAML frontmatter | Markdown | | Has #, ##, ### headings | Markdown | | Has **bold**, *italic* | Markdown | | Has - or 1. lists | Markdown | | Has ``` code blocks | Markdown | | Has > blockquotes | Markdown | | None of above | Plain text |

Decision Flow:

┌─────────────────┬────────────────────────────────────────────────┐ │ Content Type │ Action │ ├─────────────────┼────────────────────────────────────────────────┤ │ Plain text │ Proceed to Step 2 (format to markdown) │ ├─────────────────┼────────────────────────────────────────────────┤ │ Markdown │ Use AskUserQuestion to confirm optimization │ └─────────────────┴────────────────────────────────────────────────┘

If Markdown detected, ask user:

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

1. Optimize formatting (Recommended)
   - Add/improve frontmatter, headings, bold, lists
   - Run typography script (spacing, emphasis fixes)
   - Output: {filename}-formatted.md

2. Keep original formatting
   - Preserve existing markdown structure
   - Run typography script (spacing, emphasis fixes)
   - 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-8 (full workflow)
• Keep original: Skip Steps 2-5, copy file → Step 6-8 (run script on copy)
• Typography only: Skip Steps 2-6, run Step 7 on original file directly

Step 2: Analyze Content Structure

Identify:

• Existing title (H1 #)
• Paragraph separations
• Keywords suitable for bold
• Parallel content convertible to lists
• Code snippets
• Quotations

Step 3: Check/Create Frontmatter

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

Meta field handling:

| Field | Processing | |-------|------------| | title | See Step 4 | | slug | Infer from file path (e.g., posts/2026/01/10/vibe-coding/ → vibe-coding) or generate from title | | summary | Generate engaging summary (100-150 characters) | | featureImage | Check if imgs/cover.png exists in same directory; if so, use relative path |

Step 4: Title Handling

Logic:

1. If frontmatter already has title → use it, no H1 in body
2. If first line is H1 → extract to frontmatter title, remove H1 from body
3. If neither exists → generate candidate titles

Title generation flow:

1. Generate 3 candidate titles based on content
2. Use AskUserQuestion tool:

Select a title:

1. [Title A] (Recommended)
2. [Title B]
3. [Title C]

3. If no selection within a few seconds, use recommended (option 1)

Title principles:

• Concise, max 20 characters
• Captures core message
• Engaging, sparks reading interest
• Accurate, avoids clickbait

Important: Once title is in frontmatter, body should NOT have H1 (avoid duplication)

Step 5: Format Processing

Formatting rules:

| Element | Format | |---------|--------| | Titles | Use #, ##, ### hierarchy | | Key points | Use **bold** | | Parallel items | Convert to - unordered or 1. ordered lists | | Code/commands | Use `inline` or ```block``` | | Quotes/sayings | Use > blockquote | | Separators | Use --- where appropriate |

Formatting principles:

• Preserve original content and viewpoints
• Add formatting only, do not modify text
• Formatting serves readability
• Avoid over-formatting

Step 6: Save Formatted File

Save as {original-filename}-formatted.md

Examples:

• final.md → final-formatted.md
• draft-v1.md → draft-v1-formatted.md

If user chose "Keep original formatting" (from Step 1.5):

• Copy original file to {filename}-formatted.md without modifications
• Proceed to Step 7 for typography fixes only

Backup existing file:

If {filename}-formatted.md already exists, backup before overwriting:

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

Example:

• final-formatted.md exists → backup to final-formatted.backup-20260128-143052.md

Step 7: Execute Text Formatting Script

After saving, must run the formatting script:

npx -y bun ${SKILL_DIR}/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 | | | --help | -h | Show help message | |

Examples:

# Default: spacing + emphasis enabled, quotes disabled
npx -y bun ${SKILL_DIR}/scripts/main.ts article.md

# Enable all features including quote replacement
npx -y bun ${SKILL_DIR}/scripts/main.ts article.md --quotes

# Only fix emphasis issues, skip spacing
npx -y bun ${SKILL_DIR}/scripts/main.ts article.md --no-spacing

# Disable all processing except frontmatter formatting
npx -y bun ${SKILL_DIR}/scripts/main.ts article.md --no-spacing --no-emphasis

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 8: Display Results

**Formatting complete**

File: posts/2026/01/09/example/final-formatted.md

Changes:
- Added title: [title content]
- Added X bold markers
- Added X lists
- Added X code blocks

Formatting Example

Before:

This is plain text. First point is efficiency improvement. Second point is cost reduction. Third point is experience optimization. Use npm install to install dependencies.

After:

---
title: Three Core Advantages
slug: three-core-advantages
summary: Discover the three key benefits that drive success in modern projects.
---

This is plain text.

**Main advantages:**
- Efficiency improvement
- Cost reduction
- Experience optimization

Use `npm install` to install dependencies.

Notes

• Preserve original writing style and tone
• Specify correct language for code blocks (e.g., python, javascript)
• Maintain CJK/English spacing standards
• Do not add content not present in original

Extension Support

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