Show HN: 使用 ESLint 进行 Markdown 代码检查

来源：Hacker News 主题：开发者工具 / 静态代码分析 / Markdown 规范化

背景

在软件工程实践中，代码质量保障（Code Quality Assurance）早已不再局限于编程语言本身。随着文档即代码（Documentation as Code）理念的普及，Markdown 文件在技术文档、README、Changelog 以及博客内容中占据了核心地位。然而，Markdown 的灵活性也带来了维护难题：格式不一致、链接失效、标题层级混乱等问题往往在后期才被发现，导致团队协作成本增加。

传统的 Markdown 检查通常依赖于独立的 Linter（如 markdownlint）或编辑器插件，这些工具往往与项目的整体构建流程和代码规范体系割裂。ESLint 作为 JavaScript 生态中最流行的静态代码分析工具，其插件化架构使其具备了扩展到其他文本格式的能力。@eslint/markdown 的出现标志着 ESLint 正式支持 Markdown 语法检查，但为了提供更丰富、更定制化的规则集，社区开发者推出了 eslint-markdown 插件，旨在填补官方内置规则之外的空白，实现更精细化的文档质量控制。

核心内容

该项目 eslint-markdown 是一个 ESLint 插件，专门用于对 Markdown 文件进行静态分析和代码检查。其核心设计理念是作为 @eslint/markdown（ESLint 官方提供的 Markdown 支持包）的补充，而非替代。

1. 插件定位与关系 该插件明确指出，其包含的规则与 @eslint/markdown 提供的内置规则没有重叠。这意味着两者在功能上是互补的。官方强烈建议用户将 eslint-markdown 与 ESLint 内置的 Markdown 支持（即 @eslint/markdown）结合使用。这种组合策略允许开发者同时利用官方维护的基础规则和社区提供的扩展规则，从而构建一个全面、无死角的 Markdown 检查体系。

2. 功能特性 虽然原文未详细列举具体规则，但作为 ESLint 插件，它继承了 ESLint 的核心优势：

• 标准化配置：通过 .eslintrc 或 eslint.config.js 统一配置，无需引入额外的命令行工具。
• 自动化集成：可轻松集成到 CI/CD 流水线中，在代码提交或合并前自动拦截格式错误。
• 可扩展性：遵循 ESLint 的插件开发规范，开发者可以自定义规则或复用现有规则逻辑。

3. 项目规范与透明度 项目 README 中强调了开源社区的标准实践：

• 行为准则（Code of Conduct）：遵循开源社区的行为规范，确保协作环境友好。
• 变更日志（Change Log）：提供版本更新的详细记录，便于用户追踪功能迭代和 Bug 修复。
• 版本控制（Versioning）：遵循语义化版本控制（Semantic Versioning），确保依赖管理的稳定性。
• 安全性（Security）：公开安全策略，鼓励用户报告潜在的安全漏洞。

4. 社区互动 项目维护者呼吁用户如果在 GitHub 上喜欢该包，请给予 Star 支持。这种支持不仅是对开发者的鼓励，也有助于项目的可见性，从而促进项目的持续维护和迭代。

关键要点

• 互补而非替代：eslint-markdown 不包含与 @eslint/markdown 重叠的规则，建议两者配合使用以获得最佳效果。
• 统一工作流：允许开发者在同一个 ESLint 配置文件中管理代码和文档的检查规则，简化工具链。
• 官方背书的基础：依托于 @eslint/markdown 这一官方支持的底层解析能力，保证了语法的正确解析和兼容性。
• 完整的开源治理：项目提供了行为准则、变更日志、版本策略和安全政策，符合企业级开源项目的标准。
• 社区驱动：项目通过 Hacker News 等渠道推广，依赖社区反馈和 Star 支持来维持活力。

意义与影响

1. 推动“文档即代码”的规范化 将 Markdown 检查纳入 ESLint 体系，标志着技术文档正式进入“工程化”阶段。它打破了代码与文档之间的工具壁垒，使得文档格式规范（如标题层级、链接检查、拼写错误）能够像代码缩进、变量命名一样，被自动化地强制执行。

2. 提升团队协作效率 在大型开源项目或企业级开发中，多人协作导致的文档风格不一致是常见痛点。通过 ESLint 插件统一检查标准，可以消除人工审查格式的时间成本，让开发者专注于内容本身，同时确保输出文档的专业性和一致性。

3. 丰富 ESLint 生态 eslint-markdown 的成功实践进一步证明了 ESLint 插件架构的通用性和强大生命力。它展示了静态分析工具如何从单一的编程语言分析扩展到多格式文本处理，为未来支持其他标记语言（如 YAML, TOML 等）的检查提供了参考范式。

4. 降低维护门槛 对于维护者而言，将文档检查集成到现有的 CI/CD 流程中，无需额外配置独立的 Linter 环境，降低了工具链的复杂度和维护成本。这对于希望建立高质量技术文档体系的团队来说，是一个轻量级且高效的解决方案。