codacy/codacy-remark-lint

codacy-remark-lint

镜像概述

codacy-remark-lint是Codacy代码审查平台提供的Docker镜像，集成了remark-lint静态分析工具，专门用于对Markdown（.md）文件进行自动化检查。该镜像通过预设规则对Markdown文档的语法正确性、格式一致性及风格规范进行验证，帮助开发团队在文档开发流程中维护统一的格式标准，提升文档质量。

核心功能与特性

• Markdown语法校验：自动识别并报告Markdown文件中的语法错误，如未闭合的标题标记、错误的列表嵌套、无效链接格式等
• 格式规范检查：基于行业通用标准（如CommonMark）及可自定义规则，检查文档格式一致性，包括标题层级、列表缩进、代码块格式等
• Codacy平台集成：无缝对接Codacy代码审查流程，检查结果可直接反馈至Codacy dashboard，支持问题追踪与修复
• 轻量高效：镜像体积优化，可快速部署并执行检查，适合集成至CI/CD流水线

使用场景

• 开发团队文档管理：在团队协作中确保技术文档（如README、API文档、使用手册）格式统一
• CI/CD流程集成：作为代码提交或合并前的检查环节，自动拦截格式不规范的Markdown文件
• 开源项目文档维护：帮助开源项目维护者对贡献者提交的文档进行自动化格式校验
• 本地开发辅助：开发者本地运行镜像，在提交代码前预先检查文档格式问题

使用方法与配置说明

基本使用（本地检查）

通过docker run命令挂载包含Markdown文件的目录，执行检查：

bash
# 挂载当前目录（包含.md文件）至容器的/src目录，运行检查
docker run -v $(pwd):/src codacy-remark-lint

执行后，镜像将扫描/src目录下所有.md文件，并在控制台输出检查结果（含错误类型、文件路径及行号）。

集成至Codacy平台

在Codacy项目中启用该镜像，需在项目根目录添加.codacy.yml配置文件：

yaml
# .codacy.yml
engines:
  remark-lint:
    enabled: true  # 启用remark-lint检查引擎
    exclude_paths:  # 可选：排除无需检查的文件/目录
      - "docs/vendor/**"

Codacy将自动拉取codacy-remark-lint镜像，在代码提交时执行检查，并将结果显示在项目的"Issues"面板中。

自定义检查规则

通过项目根目录的remark.config.js或.remarkrc文件自定义检查规则，例如：

javascript
// remark.config.js（示例：强制标题使用ATX风格，列表项缩进为2空格）
module.exports = {
  plugins: [
    require('remark-lint-heading-style')['atx'],  // 标题使用#标记（ATX风格）
    require('remark-lint-list-item-indent')['space'],  // 列表项缩进使用空格
    require('remark-lint-no-duplicate-headings')  // 禁止重复标题
  ]
};

规则配置支持所有remark-lint官方插件，详见https://github.com/remarkjs/remark-lint/blob/main/doc/rules.md%E3%80%82

注意事项

• 确保挂载目录包含待检查的Markdown文件（扩展名为.md），否则可能无检查结果
• 自定义规则文件（remark.config.js等）需放置在挂载目录的根路径下，容器可自动识别
• 独立运行时（非Codacy集成）仅输出检查结果，需手动查看并修复问题；集成Codacy后支持问题分配与跟踪
• 镜像规则默认遵循CommonMark规范，复杂场景需通过配置文件覆盖默认规则

依赖说明

该镜像基于官方Node.js基础镜像构建，内置remark（Markdown处理器）及remark-lint生态插件，无需额外安装依赖。