核心用法
markdown-lint 是一个面向仓库级的 Markdown 格式治理工具链配置技能，核心解决三类场景：新仓库初始化（首次建立 markdownlint + pre-commit 标准）、检查/修复（批量检测并自动修复现有文件）、迁移（将配置复制到其他仓库）。
技能采用 markdownlint-cli2 作为核心引擎，配合自定义的 scripts/check-horizontal-rules.sh 脚本实现水平线完全禁止的特殊规则（保留 YAML frontmatter 的 ---）。通过 .markdownlint.json 预置了针对 CJK 文本优化的规则集：关闭 MD013（行长度限制）、MD033（内联 HTML）、MD036（强调标题）、MD041（首行标题）等不适合中文内容的规则。
显著优点
1. 开箱即用的 CJK 优化：预设配置已针对中文、日文、韩文内容调整，避免大量无意义报错
2. 双层防护机制：markdownlint 规则检查 + 独立脚本拦截水平线，覆盖工具链盲区
3. monorepo 友好：支持 #repos #node_modules 排除语法，适配大型仓库结构
4. 渐进式修复策略：提供 --fix 自动修复 + 错误分布统计 + 按需禁用规则的三层降级方案
5. pre-commit 集成：本地钩子拦截不合规提交，避免 CI 阶段才发现问题
潜在缺点与局限性
- 环境依赖较重：需要 Node.js + 可选的 pre-commit，Windows 用户需 Git Bash/WSL 支持
.sh脚本 - 部分规则无法自动修复：MD040（代码块缺语言标识）等需人工介入，批量修复时可能产生大量待处理项
- 水平线检测脚本的脆弱性：依赖 awk 处理 frontmatter，极端格式（如 YAML 内容含
---）可能误删 - 非通用写作辅助：明确不适用于单文件检查、文章内容审校、YAML/JSON 独立校验等场景
适合人群
- 维护技术文档库、开源 Wiki、产品文档站点的工程师/文档负责人
- 需要建立 Markdown 规范标准的团队架构师
- 处理遗留 Markdown 仓库批量治理的开发者
常规风险
| 风险场景 | 说明 |
|---------|------|
| 误删内容 | `check-horizontal-rules.sh` 的 awk 脚本若遇异常 frontmatter 格式，可能误删正文 `---` |
| 规则过度宽松 | 为通过检查而禁用 MD025/MD045/MD051/MD056 等规则，可能降低文档质量底线 |
| 依赖漂移 | `pre-commit autoupdate` 未执行导致 rev 版本落后，可能错过安全修复 |
| Windows 兼容性 | `.sh` 脚本在纯 CMD/PowerShell 环境无法执行，需额外配置 Git Bash 或 WSL |
安全建议
- 首次运行前在 git 干净状态下执行，便于 diff 审查变更
- 批量修复前先用
--fix配合统计命令评估影响范围 - 对
scripts/check-horizontal-rules.sh产生的大范围修改，建议分文件人工抽查