Markdown格式优化工具 - 美化您的Markdown文档

Vernox实用技能 - 让您的Markdown文档呈现专业外观

概述

Markdown格式优化工具是一款功能强大的工具，用于格式化、检查及美化Markdown文档。支持多种样式规范（CommonMark、GitHub风格Markdown、自定义规则），并能处理从简单清理到复杂重构的所有任务。

功能特性

✅ 格式化引擎

• 支持多种样式规范（CommonMark、GitHub风格、自定义规则）
• 保持文档结构完整性
• 处理嵌套列表、代码块、表格
• 可配置行宽与缩进参数
• 智能标题规范化
• 链接引用优化

✅ 代码检查与清理

• 清除行尾空白字符
• 统一换行符格式（LF与CRLF）
• 修正不一致的列表标记
• 删除文档末尾空行
• 修复连续多行空白问题

✅ 文档美化

• 改善标题层级结构
• 优化列表格式
• 用适当的间距格式化代码块
• 按配置宽度换行长行
• 在强调内容周围添加适当间距

✅ 验证

• 检查Markdown语法有效性
• 报告代码检查错误
• 建议改进方案
• 验证链接和引用

安装

clawhub install markdown-formatter

快速开始

格式化文档

const result = await formatMarkdown({
  markdown: '# My Document\n\n\n## Section 1\nContent here...',
  style: 'github',
  options: {
    maxWidth: 80,
    headingStyle: 'atx'
  }
});

console.log(result.formattedMarkdown);

美化多个文件

const results = await formatBatch({
  markdownFiles: ['./doc1.md', './doc2.md', './README.md'],
  style: 'github',
  options: { wrapWidth: 80 }
});

results.forEach(result => {
  console.log(`${result.file}: ${result.warnings} warnings`);
});

代码检查与修复

const result = await lintMarkdown({
  markdown: '# My Document\n\n\nBad list\n\n- item 1\n- item 2',
  style: 'github'
});

console.log(`Errors found: ${result.errors}`);
console.log(`Fixed: ${result.fixed}`);

工具函数

formatMarkdown

根据样式指南格式化Markdown内容

参数：

• markdown（字符串，必需）：要格式化的Markdown内容
• style（字符串，必需）：样式指南名称（'commonmark', 'github', 'commonmark', 'custom'）
• 选项（对象，可选）：
  • 最大宽度（数字）：换行宽度（默认值：80）
  • 标题样式（字符串）：'atx' | 'setext' | 'underlined' | 'consistent'（默认值：'atx'）
  • 列表样式（字符串）：'consistent' | 'dash' | 'asterisk' | 'plus'（默认值：'consistent'）
  • 代码样式（字符串）：'fenced' | 'indented'（默认值：'fenced'）
  • 强调样式（字符串）：'underscore' | 'asterisk'（默认值：'asterisk'）
  • 加粗样式（字符串）：'asterisk' | 'underline'（默认值：'asterisk'）
  • 链接样式（字符串）：'inline' | 'reference' | 'full'（默认值：'inline'）
  • 保留HTML（布尔值）：保持HTML原样（默认值：false）
  • 修复列表(布尔值): 修复不一致的列表标记 (默认值: true)
  • normalizeSpacing(布尔值): 修复格式周围的间距 (默认值: true)

返回:

• formattedMarkdown(字符串): 格式化后的markdown
• warnings(数组): 警告信息数组
• stats(对象): 格式化统计信息
• lintResult(对象): 代码检查错误及修复
• originalLength(数字): 原始字符数
• formattedLength(数字): 格式化后的字符数

formatBatch

一次性格式化多个markdown文件。

参数:

• markdownFiles(数组, 必需): 文件路径数组
• style(字符串): 样式指南名称
• 选项（对象，可选）：与 formatMarkdown 选项相同

返回值：

• 结果（数组）：格式化结果数组
• 处理文件总数（数字）：处理的文件数量
• 总警告数（数字）：所有文件中的警告总数
• 处理时间（数字）：以毫秒为单位的时间

lintMarkdown

检查 Markdown 的问题而不进行格式化。

参数：

• markdown（字符串，必需）：要检查的 Markdown 内容
• style（字符串）：样式指南名称
• options（对象，可选）：附加的检查选项
  • checkLinks（布尔值）：验证链接（默认值：true）
  • checkHeadingLevels(布尔值): 检查标题层级 (默认值: true)
  • checkListConsistency(布尔值): 检查列表标记一致性 (默认值: true)
  • checkEmphasisBalance(布尔值): 检查强调符号配对 (默认值: false)

返回:

• errors(数组): 错误对象数组
• warnings(数组): 警告对象数组
• stats(对象): 代码检查统计信息
• suggestions(数组): 建议的修复方案

样式指南

CommonMark (默认)

• 标准 CommonMark 规范
• ATX 标题 (ATX 风格)
• 参考式链接 [文本]
• 下划线强调
• 星号强调

GitHub 风格的 Markdown

• 使用 ``` 的围栏式代码块
• 使用管道符的表格
• 带有 x 的任务列表 [ ]
• 删除线~~文本~~
• 带有自动链接https://网址

保持一致（默认）

• 保持一致的 ATX 标题层级
• 保持一致的列表标记
• 保持一致的强调样式
• 保持一致的代码块样式

自定义

• 用户定义的规则
• 基于正则表达式的转换
• 自定义标题样式

使用案例

文档清理

• 修复 README 文件中不一致的格式
• 标准化标题样式
• 修复列表标记
• 清理多余的空格

内容创作

• 统一文章格式风格
• 发布前美化博客文章
• 确保标题层级结构一致

技术文档撰写

• 格式化代码文档
• 美化API规范文档
• 清理大语言模型生成的杂乱Markdown

README文件生成

• 格式化并美化项目README文件
• 确保结构一致性
• 开源项目的专业外观呈现

Markdown格式转换

• HTML转Markdown格式
• 不同样式间的重新格式化
• 从其他格式提取并格式化Markdown

配置

编辑config.json配置文件：

{
  "defaultStyle": "github",
  "maxWidth": 80,
  "headingStyle": "atx",
  "listStyle": "consistent",
  "codeStyle": "fenced",
  "emphasisStyle": "asterisk",
  "linkStyle": "inline",
  "customRules": [],
  "linting": {
    "checkLinks": true,
    "checkHeadingLevels": true,
    "checkListConsistency": true
  }
}

示例

基础格式调整

const result = await formatMarkdown({
  markdown: '# My Title\n\n\nThis is content.',
  style: 'github'
});

console.log(result.formattedMarkdown);

复杂美化处理

const result = await formatMarkdown({
  markdown: '# Header 1\n## Header 2\n\nParagraph...',
  style: 'github',
  options: {
    fixLists: true,
    normalizeSpacing: true,
    wrapWidth: 80
  }
});

console.log(result.formattedMarkdown);

代码规范检查与修复

const result = await lintMarkdown({
  markdown: '# Title\n\n- Item 1\n- Item 2\n\n## Section 2',
  style: 'github'
});

console.log(`Errors: ${result.errors.length}`);
result.errors.forEach(err => {
  console.log(`  - ${err.message} at line ${err.line}`);
});

// Fix automatically
const fixed = await formatMarkdown({
  markdown: result.fixed,
  style: 'github'
});

批量处理

const results = await formatBatch({
  markdownFiles: ['./doc1.md', './doc2.md', './README.md'],
  style: 'github'
});

console.log(`Processed ${results.totalFiles} files`);
console.log(`Total warnings: ${results.totalWarnings}`);

性能

速度

• 小型文档（<1000字）：<50毫秒
• 中型文档（1000-5000字）：50-200毫秒
• 大型文档（5000+字）：200-500毫秒

准确度

• 结构保留：100%
• 风格指南遵从度：95%以上
• 空白字符规范化：100%

错误处理

无效输入

• 清晰错误信息
• 建议检查文件路径
• 格式化前验证Markdown内容

Markdown解析错误

• 清晰报告解析问题
• 建议手动修复
• 优雅降级处理错误

文件输入/输出错误

• 明确显示文件路径错误
• 检查文件是否存在
• 建议权限修复
• 批处理在出错时继续执行

故障排除

格式未应用

• 检查样式是否正确
• 验证选项是否被遵守
• 检查是否存在冲突规则
• 使用简单示例进行测试

代码检查显示过多错误

• 部分错误属于风格选择，并非实质问题
• 考虑禁用特定检查项
• 根据特定需求使用自定义规则

实用建议

最佳效果

• 采用一致的风格指南
• 启用fixLists（列表修复）与normalizeSpacing（间距规范化）选项
• 根据输出媒介设置合适的maxWidth（最大宽度）
• 先通过小样本进行测试

性能优化

• 分批处理大型文件
• 禁用未使用的代码检查规则
• 对常见模式使用更简单的规则

许可证

MIT

---

格式化Markdown。让你的文档保持美观。🔮

部分文章来自各大搜索引擎，如有侵权，请与我联系删除。