markdown-formatter

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Markdown Formatter

Markdown 格式化器

This skill provides modular, categorized formatting guidance for markdown documents. Load resources by formatting area as needed.

本Skill为Markdown文档提供模块化、分类化的格式化指导。可根据格式化需求加载对应领域的资源文件。

Quick Reference: When to Load Which Resource

快速参考：何时加载对应资源

Formatting Area	Load Resource	Common Issues
Headers, document structure, hierarchy	`resources/headers-hierarchy.md`	Skipped levels, underline-style, spacing
Lists, nesting, indentation	`resources/lists-nesting.md`	Inconsistent markers, wrong indentation
Code blocks, inline code, emphasis	`resources/code-emphasis.md`	Missing language IDs, wrong markers
Links, images, references, alt text	`resources/links-images.md`	Bad link text, missing alt text
Spacing, tables, final polish	`resources/spacing-tables.md`	Inconsistent spacing, table alignment

格式化领域	加载资源	常见问题
标题、文档结构、层级	`resources/headers-hierarchy.md`	层级跳跃、下划线格式、间距问题
列表、嵌套、缩进	`resources/lists-nesting.md`	标记不一致、缩进错误
代码块、行内代码、强调格式	`resources/code-emphasis.md`	缺少语言标识、标记错误
链接、图片、引用、替代文本	`resources/links-images.md`	链接文本描述性差、缺少替代文本
间距、表格、最终优化	`resources/spacing-tables.md`	间距不一致、表格对齐问题

Core Rules at a Glance

核心规则概览

Headers

标题

ATX-style: Use
```
#
```
notation, not underlines
One per document: Single H1 at start
No skips: Go H1 → H2 → H3, never skip levels
Spacing: Blank line before (except first) and after each header

ATX格式：使用
```
#
```
标记，而非下划线
单文档唯一：文档开头仅保留一个H1标题
无层级跳跃：遵循H1 → H2 → H3的顺序，禁止跳过层级
间距规范：每个标题前后需空一行（第一个标题前除外）

Lists

列表

Marker: Use
```
-
```
consistently (not
```
*
```
or
```
+
```
)
Indentation: 2 spaces per nesting level
Spacing: Blank line before and after list blocks

标记统一：统一使用
```
-
```
作为列表标记（不使用
```
*
```
或
```
+
```
）
缩进规则：每级嵌套使用2个空格缩进
间距规范：列表块前后需空一行

Code

代码

Inline: Single backticks for code references
Blocks: Fenced (not indented) with language ID
Spacing: Blank line before and after blocks

行内代码：使用单个反引号包裹代码引用
代码块：使用围栏式（而非缩进式）并添加语言标识
间距规范：代码块前后需空一行

Links & Images

链接与图片

Links: Descriptive text (no "click here")
References: Use reference-style for repeated URLs
Images: Always include meaningful alt text

链接：使用描述性文本（避免使用“点击这里”）
引用格式：重复URL使用引用式链接
图片：始终添加有意义的替代文本

Spacing

间距

Between blocks: One blank line
No trailing whitespace: Remove all line-end spaces
End of file: Single newline

块级元素间：保留一个空行
无尾随空格：删除所有行尾空格
文件结尾：保留单个换行符

Spacing

间距

Between blocks: One blank line
No trailing whitespace: Remove all line-end spaces
End of file: Single newline

块级元素间：保留一个空行
无尾随空格：删除所有行尾空格
文件结尾：保留单个换行符

Formatting Workflow

格式化工作流

Phase 1: Structural Scan

阶段1：结构扫描

Check high-level structure first:

Read entire file to understand flow
Load
```
resources/headers-hierarchy.md
```
if issues found
Verify H1 count, levels, and spacing

首先检查高层级结构：

通读整个文件以理解内容逻辑
若发现问题，加载
```
resources/headers-hierarchy.md
```
验证H1标题数量、层级及间距

Phase 2: Block-Level Formatting

阶段2：块级格式化

Process each formatting category in sequence:

Headers →
```
headers-hierarchy.md
```
Lists →
```
lists-nesting.md
```
Code →
```
code-emphasis.md
```
Links/Images →
```
links-images.md
```

按顺序处理各格式化分类：

标题 →
```
headers-hierarchy.md
```
列表 →
```
lists-nesting.md
```
代码 →
```
code-emphasis.md
```
链接/图片 →
```
links-images.md
```

Phase 3: Final Polish

阶段3：最终优化

Complete document-level formatting:

Load
```
resources/spacing-tables.md
```
Fix spacing around all blocks
Validate tables (if present)
Check line length and trailing whitespace
Verify single trailing newline

完成文档级格式化：

加载
```
resources/spacing-tables.md
```
修正所有块级元素的间距
验证表格格式（若存在）
检查行长度及尾随空格
验证文件结尾是否为单个换行符

Phase 4: Validation

阶段4：验证

Use validation tools to catch remaining issues:

bash

./skills/markdown-formatter/scripts/validate-markdown.sh file.md

使用验证工具排查剩余问题：

bash

./skills/markdown-formatter/scripts/validate-markdown.sh file.md

How to Use Resources

资源使用方法

Each resource file is self-contained and covers one formatting area:

Headers: Read full file once for complete header guidance
Lists: Reference indentation rules and spacing requirements
Code: Check inline vs. block syntax and language identifiers
Links/Images: Verify alt text guidelines and reference styles
Spacing: Apply final polish and table formatting

每个资源文件都是独立完整的，覆盖一个格式化领域：

标题：通读文件获取完整的标题使用指南
列表：参考缩进规则和间距要求
代码：确认行内与块级代码的语法及语言标识
链接/图片：验证替代文本规范和引用格式
间距：应用最终优化和表格格式化规则

Resource Structure

资源结构

Each resource includes:

Syntax examples (correct and incorrect)
Rules and guidelines (with explanations)
Common issues and fixes (before/after)
Validation checklist (quick verification)

每个资源包含：

语法示例（正确与错误示范）
规则与指南（含解释）
常见问题与修复方案（前后对比）
验证清单（快速校验）

Resource Structure

资源结构

Each resource includes:

Syntax examples (correct and incorrect)
Rules and guidelines (with explanations)
Common issues and fixes (before/after)
Validation checklist (quick verification)

每个资源包含：

语法示例（正确与错误示范）
规则与指南（含解释）
常见问题与修复方案（前后对比）
验证清单（快速校验）

Common Formatting Issues

常见格式化问题

Issue: Inconsistent List Markers

问题：列表标记不一致

markdown

<!-- Before: mixed markers -->
* Item 1
+ Item 2
- Item 3

<!-- After: consistent -->
- Item 1
- Item 2
- Item 3

→ Load

resources/lists-nesting.md

for full guidance

markdown

<!-- Before: mixed markers -->
* Item 1
+ Item 2
- Item 3

<!-- After: consistent -->
- Item 1
- Item 2
- Item 3

→ 加载

resources/lists-nesting.md

获取完整指南

Issue: Missing Code Block Language

问题：代码块缺少语言标识

markdown

<!-- Before -->

npm install


<!-- After -->
```bash
npm install

→ Load `resources/code-emphasis.md`

markdown

<!-- Before -->

npm install


<!-- After -->
```bash
npm install

→ 加载`resources/code-emphasis.md`

Issue: Skipped Header Levels

问题：标题层级跳跃

markdown

<!-- Before -->

markdown

<!-- Before -->

Title

Subsection (skipped H2!)

Title

Section

Subsection

→ Load `resources/headers-hierarchy.md`

→ 加载`resources/headers-hierarchy.md`

Issue: Bad Link Text

问题：链接文本描述性差

markdown

<!-- Before -->
Click [here](url) for details

<!-- After -->
See the [installation guide](url)

→ Load

resources/links-images.md

markdown

<!-- Before -->
Click [here](url) for details

<!-- After -->
See the [installation guide](url)

→ 加载

resources/links-images.md

Issue: Missing Alt Text

问题：缺少图片替代文本

markdown

<!-- Before -->
![](screenshot.png)

<!-- After -->
![Dashboard showing user metrics](screenshot.png)

→ Load

resources/links-images.md

markdown

<!-- Before -->
![](screenshot.png)

<!-- After -->
![Dashboard showing user metrics](screenshot.png)

→ 加载

resources/links-images.md

Output Format

输出格式

When formatting files, provide:

Summary

Original line count
New line count
Primary issues fixed

Issues Fixed

List each category of corrections
Count of fixes per category

Recommendations

Content improvements (if any)
Consistency notes
Accessibility enhancements

格式化文件时，需提供：

总结

原始行数
新行数
修复的主要问题

已修复问题

列出每类修正内容
每类修复的数量

建议

内容改进建议（若有）
一致性说明
可访问性增强建议

Formatting Decision Table

格式化决策表

Use this table to decide what to fix and in what order:

Priority	Category	When to Address	Load Resource
1	Structure	First pass—headers, hierarchy	headers-hierarchy.md
2	Lists	Check consistency, indentation	lists-nesting.md
3	Code	Verify blocks have language IDs	code-emphasis.md
4	Links/Images	Descriptive text, alt text	links-images.md
5	Spacing	Final polish, cleanup	spacing-tables.md

使用此表确定修复顺序和内容：

优先级	分类	处理时机	加载资源
1	结构	首次处理——标题、层级	headers-hierarchy.md
2	列表	检查一致性、缩进	lists-nesting.md
3	代码	验证代码块是否有语言标识	code-emphasis.md
4	链接/图片	描述性文本、替代文本	links-images.md
5	间距	最终优化、清理	spacing-tables.md

Best Practices

最佳实践

Preserve Content

保留内容完整性

Never change the meaning or information—only format structure.

绝不修改内容的含义或信息——仅调整结构格式。

Be Consistent

保持一致性

Apply rules uniformly throughout the document.

在整个文档中统一应用规则。

Respect Context

尊重上下文

Some projects may have specific conventions. Ask if unclear.

部分项目可能有特定约定，若不确定请询问用户。

Document Changes

记录变更

Clearly explain what was modified and why.

清晰说明修改内容及原因。

Limitations

局限性

This skill does not:

Check spelling or grammar
Validate external links
Optimize images
Enforce strict line length

本Skill不支持：

拼写或语法检查
外部链接有效性验证
图片优化
强制严格的行长度限制

Integration Points

集成点

Works with:

Linters (markdownlint, etc.)
CI/CD pipelines (pre-commit hooks)
Documentation generators
Static site builders

Pairs well with:

GitHub issue templates
README standards
Style guides
Documentation style checkers

兼容工具：

代码检查器（markdownlint等）
CI/CD流水线（提交前钩子）
文档生成器
静态站点构建工具

搭配使用更佳：

GitHub issue模板
README标准
风格指南
文档风格检查器

Resource Index

资源索引

Resource	Lines	Coverage
headers-hierarchy.md	250+	Headers, hierarchy, structure
lists-nesting.md	350+	Lists, nesting, indentation
code-emphasis.md	300+	Code blocks, inline code, emphasis
links-images.md	400+	Links, images, alt text, references
spacing-tables.md	350+	Spacing, tables, document polish

资源	行数	覆盖范围
headers-hierarchy.md	250+	标题、层级、结构
lists-nesting.md	350+	列表、嵌套、缩进
code-emphasis.md	300+	代码块、行内代码、强调格式
links-images.md	400+	链接、图片、替代文本、引用
spacing-tables.md	350+	间距、表格、文档优化

Validation Tools

验证工具

Script: validate-markdown.sh

脚本：validate-markdown.sh

bash

./skills/markdown-formatter/scripts/validate-markdown.sh file.md

Checks for:

Missing newline at end
Trailing whitespace
Code blocks without language ID
Inconsistent list markers
Bad link text
Missing alt text
Multiple blank lines

bash

./skills/markdown-formatter/scripts/validate-markdown.sh file.md

检查内容：

文件结尾是否缺少换行符
尾随空格
无语言标识的代码块
不一致的列表标记
描述性差的链接文本
缺失的图片替代文本
多个连续空行

Guidelines for Complex Documents

复杂文档处理指南

Large Documents (1000+ lines)

大型文档（1000+行）

Process by section (headers first)
Validate each section before moving on
Run full validation at end

按章节处理（先处理标题）
验证当前章节后再进行下一章节
最后运行完整验证

Documents with Code

含代码的文档

Ensure all code blocks have language IDs
Verify inline code uses backticks correctly
Check code examples for syntax errors

确保所有代码块都有语言标识
验证行内代码正确使用反引号
检查代码示例的语法错误

Documents with Heavy Linking

大量链接的文档

Use reference-style for repeated URLs
Verify all links are descriptive
Validate internal anchors work

重复URL使用引用式链接
验证所有链接都有描述性文本
验证内部锚点有效

Documents with Tables

含表格的文档

Align columns for readability
Ensure header row present
Verify separator row has 3+ dashes

对齐列以提升可读性
确保存在表头行
验证分隔行至少有3个破折号

When Uncertain

不确定时的处理方式

Multiple conventions present? Ask the user for project preference
Non-standard markdown? Check rendering before proceeding
Content ambiguous? Clarify with user before formatting
Extensive changes needed? Show before/after samples first

存在多种约定？ 询问用户的项目偏好
非标准Markdown？ 处理前先检查渲染效果
内容模糊？ 格式化前先与用户确认
需大量修改？ 先展示前后对比样例

Quick Checklist

快速校验清单

After formatting, verify:

Single H1 at document start
ATX-style headers with proper spacing
Consistent list markers (all
```
-
```
)
Code blocks have language IDs
All code formatted correctly
Links have descriptive text
Images have alt text
Proper spacing around all blocks
No trailing whitespace
Single newline at end
Document renders correctly

Next Steps: Load the appropriate resource file from the Quick Reference table above based on the formatting issues you've identified in the document.

格式化完成后，验证以下内容：

文档开头仅有一个H1标题
使用ATX格式标题并保持正确间距
列表标记统一（均为
```
-
```
）
代码块带有语言标识
所有代码格式正确
链接使用描述性文本
图片带有替代文本
所有块级元素间距正确
无尾随空格
文件结尾为单个换行符
文档渲染正常

下一步：根据你在文档中发现的格式化问题，从上方快速参考表格中加载对应的资源文件。