Format Markdown

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.

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:

If Markdown is detected, ask the user:

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:

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

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:

Present to the user:

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:

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:

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