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)

coverImage

Check if imgs/cover.png exists in same directory; if so, use relative path (also accepted: featureImage )

Step 4: Title Handling

Logic:

• If frontmatter already has title → use it, no H1 in body

• If first line is H1 → extract to frontmatter title , remove H1 from body

• If neither exists → generate candidate titles

Title generation flow:

• Generate 3 candidate titles based on content

• Use AskUserQuestion tool:

Select a title:

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

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

• Fix CJK emphasis/bold punctuation issues (default: enabled)

• Add CJK/English mixed text spacing via autocorrect (default: enabled)

• Replace ASCII quotes "..." with fullwidth quotes "..." (default: disabled)

• 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.