Markdown Formatter

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

Script Directory

Scripts in

scripts/

${SKILL_DIR}

scripts/main.ts

scripts/quotes.ts

scripts/autocorrect.ts

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:

---

#

##

###

**bold**

*italic*

- 

1. 

> 

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 (

---

Meta field handling:

title

slug

posts/2026/01/10/vibe-coding/

vibe-coding

summary

coverImage

imgs/cover.png

featureImage

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:

#

##

###

**bold**

-

1.

`inline`

```block```

>

---

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

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

--quotes

-q

"..."

--no-quotes

--spacing

-s

--no-spacing

--emphasis

-e

--no-emphasis

--help

-h

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.