format-markdown

---
name: format-markdown
description: 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.
metadata: { "version": 1.0.0 }
---

# 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 (`# {{title}}`)**. Do not remove it. If frontmatter already has `title`, include it as context but still generate fresh candidates unless skipped by configuration.

#### Summary Generation

Generate 3 candidate summaries with different angles. Present to the user:

```text
Pick a summary:

1. [Summary A] — [focus note]
2. [Summary B] — [focus note]
3. [Summary C] — [focus note]

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

**Summary principles:**

- 80-150 characters, precise and information-rich
- Convey the **core value** to the reader, not just the topic
- Vary angles: problem-driven, result-driven, insight-driven
- **Hook the reader**: make them want to read the full article
- Use concrete details (numbers, outcomes, specific methods) over vague descriptions

**Prohibited patterns:**

- "本文介绍了..."、"本文探讨了..."
- Pure topic description without value proposition
- Repeating the title in different words

If frontmatter already has `summary`, skip selection and use it.

To make the summary appear visibly, generate it following the **Admonition Syntax Rules**. Place it after the H1 title:

```markdown
!!! example "Summary"

    Here is the summary you generated.
```

**EXTEND.md skip behavior:** If `auto_select: true` is set in `EXTEND.md`, skip title and summary selection and generate the best candidate directly without asking. The user may also set `auto_select_title: true` or `auto_select_summary: true` independently.

---

### Step 4: Format Content

Apply formatting guided by the Step 2 analysis. The goal is to make the content scannable and the key points easy to grasp.

#### Formatting toolkit

| Element         | When to use                                                 | Format                                                 |
| --------------- | ----------------------------------------------------------- | ------------------------------------------------------ |
| Headings        | Natural topic boundaries, section breaks                    | `##`, `###` hierarchy                                  |
| Bold            | Key conclusions, important terms, core takeaways            | `**bold**`                                             |
| Unordered lists | Parallel items, feature lists, examples                     | `- item`                                               |
| Ordered lists   | Sequential steps, ranked items, procedures                  | `1. item`                                              |
| Highlights      | Critical details, important comparisons for quick attention | `==text==`                                             |
| Color highlight | Colored emphasis where standard bold is insufficient        | `<span style="color:red;font-weight:bold">text</span>` |
| Tables          | Comparisons, structured data, option matrices               | Markdown table                                         |
| Code            | Commands, file paths, technical terms, variable names       | `` `inline` `` or fenced blocks                        |
| Blockquotes     | Notable quotes, important warnings, cited text              | `> blockquote`                                         |
| Admonition      | Definitions, examples, notable warnings, conclusions        | Follow **Admonition Syntax Rules** below               |
| Separators      | Major topic transitions                                     | `---`                                                  |

#### Admonition Syntax Rules

Strict enforcement. When using MkDocs-style admonitions (e.g. `!!! note`, `!!! example`, `!!! warning`), you must follow these indentation rules strictly. Markdown parsers require content inside the block to be indented.

**Correct format:**

```markdown
!!! note "Title Text"

    This is the content. It must start with 4 spaces, and the above line is empty.

    This is a second paragraph. It also needs **4** spaces indentation.

    - List items also follow. The end line should have an empty line with no indent below.

This is the line outside admonition (correct).
```

**Incorrect format (DO NOT DO THIS):**

```markdown
!!! note "Title Text"
This content has no indent. (Wrong - breaks indentation rule)

!!! note "Title Text"

    First paragraph ok.

Second paragraph has no indent. (Wrong - breaks the block)
```

**Syntax rules:**

1. **Indentation**: All content belonging to the admonition must be indented **4 spaces** relative to the `!!!` line.
2. **Paragraph breaks**: Blank lines inside the block must also preserve block structure; ensure the next paragraph starts with 4 spaces.
3. **Nested lists/code**: If using lists or code inside an admonition, indent them **8 spaces** total.
4. **Consistency**: Do not mix tabs and spaces. Use 4 spaces consistently.

#### Formatting principles — what NOT to do

- Do NOT add invented facts, explanations, or commentary
- Do NOT delete or shorten valid original content without user intent
- Do NOT rephrase or rewrite the author's wording unless the task explicitly requires it
- Do NOT add headings that editorialize (e.g. "Amazing Discovery"); use neutral descriptive headings
- Do NOT over-format: not every sentence needs bold, and not every paragraph needs a heading

#### Formatting principles — what TO do

- Preserve the author's voice, tone, and wording as much as possible
- **Bold key conclusions and core takeaways** — the sentences a reader would likely highlight
- Extract parallel items from prose into lists when the structure is clearly present
- Add headings where the topic genuinely shifts
- Use tables for comparisons or structured data buried in prose
- Use blockquotes for golden quotes, memorable statements, or important warnings
- Fix obvious typos **only when the correction is unambiguous**

---

### Step 5: Save Formatted File

Save the formatted content as a new file. The output filename is built from the original filename plus a suffix defined in `EXTEND.md`.

- **Default suffix**: `_formatted` → `{original-filename}_formatted.md`
- **Override via `EXTEND.md`**: set `output_suffix: _formatted` → `{original-filename}_formatted.md`

**Backup existing file before overwrite:**

```bash
if [ -f "{filename}_formatted.md" ]; then
  mv "{filename}_formatted.md" "{filename}_formatted.backup-$(date +%Y%m%d-%H%M%S).md"
fi
```

After Step 5 saves the formatted file, Step 6 must run on that saved output file **in-place**.

---

### Step 6: Execute Structural Rendering Compatibility Script

Scripts are stored in the `scripts/` subdirectory. `${SKILL_DIR}` is the root directory containing this `SKILL.md`.

This script is designed for **MkDocs + Material** rendering compatibility. It fixes structural spacing around math, list, and table blocks while preserving document content.

#### Runtime Requirements

- **Node.js 18+**
- Local npm dependencies installed once in `${SKILL_DIR}`

If dependencies are not installed yet:

```bash
cd ${SKILL_DIR}
npm install
```

If `package-lock.json` already exists, prefer:

```bash
cd ${SKILL_DIR}
npm ci
```

#### Script

| Script                         | Purpose                                                               |
| ------------------------------ | --------------------------------------------------------------------- |
| `scripts/format-structure.mjs` | Fixes mkdocs/material-sensitive spacing around math/list/table blocks |

#### Command

```bash
node ${SKILL_DIR}/scripts/format-structure.mjs <file.md> [options]
```

#### CLI Options

| Option        | Short | Description                         | Default  |
| ------------- | ----- | ----------------------------------- | -------- |
| `--output`    | `-o`  | Specify output file path            | In-place |
| `--dry-run`   | `-n`  | Preview changes without writing     | false    |
| `--no-backup` |       | Skip backup of existing output file | false    |

#### What the script fixes

1. **Math block spacing**
   - Ensures block math has blank lines before and after
   - Handles standalone single-line block math such as `$$E = mc^2$$`
   - Removes illegal inner blank lines immediately after opening `$$` or before closing `$$`

2. **List block spacing**
   - Ensures blank lines before and after markdown lists

3. **Table block spacing**
   - Ensures blank lines before and after markdown tables

4. **Safety**
   - Uses Markdown AST to detect structural blocks
   - Applies minimal text patches instead of re-stringifying the full document
   - Preserves text content and existing writing style as much as possible

#### EXTEND.md Rule Toggles

The script reads simple `key: value` settings from `EXTEND.md`.

Supported keys:

```md
output_suffix: \_formatted
fix_math_blocks: true
fix_list_blocks: true
fix_table_blocks: true
trim_math_inner_blank_lines: true
```

#### Usage in Workflow

- **Full workflow**: after Step 5 saves the formatted file, run the script **in-place** on that output file.
- **Structural-fixes-only mode**: run the script directly on the original file in-place.

Examples:

```bash
# In-place fix on already formatted output
node ${SKILL_DIR}/scripts/format-structure.mjs "{output-file-path}"

# Write to a custom file
node ${SKILL_DIR}/scripts/format-structure.mjs article.md -o article_fixed.md

# Preview only
node ${SKILL_DIR}/scripts/format-structure.mjs article.md --dry-run

# Skip backup
node ${SKILL_DIR}/scripts/format-structure.mjs article.md --no-backup
```

#### Output and Backup Behavior

| Condition                                     | Output Path                    |
| --------------------------------------------- | ------------------------------ |
| Default                                       | Input file modified in-place   |
| With `--output custom.md`                     | `custom.md`                    |
| Step 5 + default suffix                       | `{original-name}_formatted.md` |
| With `output_suffix: _formatted` in EXTEND.md | `{original-name}_formatted.md` |

If the target output file already exists and `--no-backup` is **not** set, the script creates a timestamped backup before writing.

---

## 📋 Step 7: Completion Report

```text
**Formatting Complete**

**Files:**
- Analysis: {filename}-analysis.md
- Formatted: {filename}_formatted.md

**Content Analysis Summary:**
- Highlights found: X key insights
- Golden quotes: X memorable sentences
- Formatting issues fixed: X items

**Changes Applied:**
- Frontmatter: [added/updated] (title, slug, summary)
- Headings added: X (##: N, ###: N)
- Bold markers added: X
- Lists created: X (from prose → list conversion)
- Tables created: X
- Admonitions added: X
- Typos fixed: X [list each: "original" → "corrected"]

**Structural Compatibility Script:**
- Math blocks processed: X
- List blocks processed: X
- Table blocks processed: X
- Empty lines added: X
- Math inner blank lines removed: X
- Backup created: [yes/no]
```