baoyu-format-markdown Checked

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