format-markdown

Summarize and format markdown files, then apply mkdocs/material-compatible structural spacing fixes for math, list, and table blocks. Outputs to {filename}_formatted.md by default.

# Markdown Formatter

Markdown formatting skill with two layers of processing:

1. **Content formatting**: analyze content, improve readability, and add metadata or structural aids when needed.
2. **Structural compatibility fixing**: apply mkdocs/material-safe spacing fixes for math, list, and table blocks without rewriting text content.

You MUST follow the workflow in the `Workflow` section below and must not skip required steps.

## Core Principles

- Preserve original meaning and wording as much as possible.
- In **content-formatting mode** (Steps 2-5), metadata and structural aids may be added, such as title, summary, headings, emphasis, lists, tables, and admonitions.
- In **Step 6 structural-fix mode**, the script performs whitespace-only changes and never rewrites text content.

| Principle                  | Requirement                                                                              |
| -------------------------- | ---------------------------------------------------------------------------------------- |
| **Meaning Preservation**   | Preserve the author's meaning, tone, and wording as much as possible.                    |
| **Structural Additions**   | In formatting mode, only add metadata or formatting structures that improve readability. |
| **Whitespace-Only Script** | Step 6 may only modify whitespace, empty lines, and structural spacing.                  |
| **Rendering Safety**       | Ensure all changes improve markdown rendering stability in mkdocs/material style.        |
| **Traceability**           | Every meaningful change must be summarized in the final report.                          |

---

## Usage

The workflow has two phases:

1. **Analyze and format content** (Steps 1-5)
2. **Apply structural compatibility fixes** for mkdocs/material rendering (Step 6)

Claude performs content analysis and formatting first, then runs the structural compatibility script as the final cleanup step.

## 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 is detected, ask the user:**

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

1. Optimize formatting (Recommended)
   - Analyze content, improve headings, bold, lists, tables, and readability
   - Run structural compatibility script afterward
   - Output: {filename}_formatted.md

2. Keep original formatting
   - Preserve existing markdown structure
   - Run structural compatibility script only on the copied file
   - Output: {filename}_formatted.md

3. Structural fixes only
   - Run the structural compatibility script on the original file in-place
   - No copy created; modifies the 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
- **Structural fixes only**: Skip to Step 6 and run on the 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 and 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:

```markdown
# 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 it if missing.

| Field        | Processing                                                                       |
| ------------ | -------------------------------------------------------------------------------- |
| `title`      | See **Title Generation** below                                                   |
| `slug`       | Infer from file path or generate from title                                      |
| `summary`    | See **Summary Generation** below                                                 |
| `coverImage` | Check if `imgs/cover.png` exists in the same directory; if so, use relative path |

#### Title Generation

Whether or not a title already exists, always 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 3-4 style-differentiated candidates:**

| Style           | Characteristics                         | Example                                                 |
| --------------- | --------------------------------------- | ------------------------------------------------------- |
| Subversive      | Deny common practice, create conflict   | "All de-AI-flavor prompts are wrong"                    |
| Solution        | Give the answer directly, promise value | "One recipe to make AI write in your voice"             |
| Suspense        | Reveal half, spark curiosity            | "It took me six months to find how to remove AI flavor" |
| Concrete number | Use numbers for credibility             | "150 lines of docs taught AI my writing style"          |

Present to the user:

```text
Pick a title:

1. [Title A] — (recommended)
2. [Title B] — [style note]
3. [Title C] — [style note]

Enter number, or type a custom title:
```

Put the strongest hook first and mark it as recommended.

**Title principles:**

- **Hook in the first 5 chars**: create an information gap or cognitive conflict
- **Specific > abstract**: "150 lines" beats "a document"
- **Negation > affirmation**: "you're doing it wrong" beats "the right way"
- **Conversational**: like chatting with a friend, not a paper title
- **Max ~25 chars**: longer titles get truncated in feeds
- **Accurate, not clickbait**: the article must deliver what the title promises

**Prohibited patterns:**

- "浅谈 XX"、"关于 XX 的思考"、"XX 的探索与实践"
- "震惊！"、"万字长文"、"建议收藏"
- Pure questions without direction: "AI 写作的未来在哪里？"

If `title` exists in frontmatter and there is no H1 in the body content, **YOU MUST insert the title as the first H1 (`#