prologic/remark-lint

remark-lint Docker镜像

概述

remark-lint Docker镜像是基于https://github.com/remarkjs/remark%E7%94%9F%E6%80%81%E7%B3%BB%E7%BB%9F%E7%9A%84Markdown%E9%A3%8E%E6%A0%BC%E6%A3%80%E6%9F%A5%E5%B7%A5%E5%85%B7%E5%AE%B9%E5%99%A8%E5%8C%96%E5%AE%9E%E7%8E%B0%E3%80%82%E5%AE%83%E9%80%9A%E8%BF%87%E4%B8%80%E7%B3%BB%E5%88%97%E6%8F%92%E4%BB%B6%E8%A7%84%E5%88%99%E6%A3%80%E6%9F%A5Markdown%E6%96%87%E6%A1%A3%EF%BC%8C%E7%A1%AE%E4%BF%9D%E5%86%85%E5%AE%B9%E5%9C%A8%E4%B8%8D%E5%90%8C%E8%A7%A3%E6%9E%90%E5%99%A8%E4%B8%AD%E6%B8%B2%E6%9F%93%E4%B8%80%E8%87%B4%EF%BC%8C%E5%87%8F%E5%B0%91%E5%90%8E%E7%BB%AD%E9%87%8D%E6%9E%84%E9%9C%80%E6%B1%82%EF%BC%8C%E5%B9%B6%E5%B8%AE%E5%8A%A9%E5%9B%A2%E9%98%9F%E7%BB%B4%E6%8A%A4%E7%BB%9F%E4%B8%80%E7%9A%84%E6%96%87%E6%A1%A3%E8%A7%84%E8%8C%83%E3%80%82

核心功能

• 多规则支持：提供丰富的内置规则，检查列表缩进、未定义引用、重复标题等常见问题
• 预设系统：包含推荐规则集、一致性规则集和Markdown风格指南规则集
• 高度可配置：支持启用/禁用特定规则，通过配置文件或内联注释自定义检查行为
• 自动修复：结合remark-stringify可自动格式化Markdown语法，统一样式
• 集成能力：可与CI/CD流程、编辑器（Atom、Sublime、Vim）和构建工具（Gulp、Grunt）无缝集成

使用场景

• 个人项目Markdown文档质量控制
• 团队协作中统一文档格式规范
• 开源项目贡献者提交前的文档验证
• CI/CD流程中自动检查文档格式问题
• 技术文档库的批量质量审计

使用方法

基本使用（Docker Run）

检查当前目录下所有Markdown文件：

bash
docker run --rm -v $(pwd):/app remark-lint:latest remark .

安装预设并配置

1. 创建package.json配置文件：

json
{
  "scripts": {
    "lint-md": "remark ."
  },
  "remarkConfig": {
    "plugins": ["remark-preset-lint-recommended"]
  }
}

2. 运行容器安装依赖并执行检查：

bash
docker run --rm -v $(pwd):/app remark-lint:latest sh -c "npm install remark-cli remark-preset-lint-recommended && npm run lint-md"

自定义规则配置

通过.remarkrc文件配置规则：

json
{
  "plugins": [
    "remark-preset-lint-recommended",
    ["remark-lint-list-item-indent", false],
    ["remark-lint-maximum-line-length", 80]
  ]
}

挂载配置文件运行：

bash
docker run --rm -v $(pwd):/app -v $(pwd)/.remarkrc:/app/.remarkrc remark-lint:latest remark .

自动修复文档格式

使用-o参数覆盖原文件并修复格式问题：

bash
docker run --rm -v $(pwd):/app remark-lint:latest remark example.md -o

Docker Compose配置

创建docker-compose.yml：

yaml
version: '3'
services:
  remark-lint:
    image: remark-lint:latest
    volumes:
      - .:/app
    command: sh -c "npm install remark-preset-lint-markdown-style-guide && remark . --use remark-preset-lint-markdown-style-guide"

运行检查：

bash
docker-compose up

预设列表

• remark-preset-lint-consistent：强制一致性的规则集（如统一列表标记、强调符号）
• remark-preset-lint-markdown-style-guide：遵循Markdown风格指南的规则集
• remark-preset-lint-recommended：防止错误和跨解析器兼容性问题的规则集

外部规则扩展

可通过npm安装外部规则插件扩展检查能力，常用外部规则包括：

• remark-lint-no-dead-urls：检查外部链接有效性
• remark-lint-alphabetize-lists：确保列表项按字母顺序排列
• remark-lint-heading-length：限制标题长度
• remark-lint-code：检查代码块语法（支持ESLint）
• remark-lint-write-good：集成写作建议工具

安全注意事项

• 本镜像仅对Markdown文档进行静态分析，不会修改文档内容结构，无XSS***风险
• 规则检查结果可能影响构建流程（如CI失败），需合理配置规则严格程度
• 敏感信息不应通过配置文件或命令行参数传递

集成示例

• CI/CD集成：在GitHub Actions中添加检查步骤
• 编辑器集成：通过Atom的linter-remark插件实时检查
• 提交前检查：结合husky在git commit前自动运行检查