baoyu-format-markdown

仓库: jimliu/baoyu-skills
安装量: 8.8K
排名: #291

安装

npx skills add https://github.com/jimliu/baoyu-skills --skill baoyu-format-markdown

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.

| scripts/main.ts | Main entry point with CLI options

| scripts/cjk-emphasis.ts | Fix CJK emphasis/bold punctuation issues

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

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

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

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

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

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

← 返回排行榜