@lint-md/cli

English | 简体中文

@lint-md/cli 是 Lint Markdown 的命令行工具，用于检查和修复中文 Markdown 文档中的格式问题。

项目定位

• 面向对象：中文技术文档、博客、知识库等 Markdown 内容。
• 核心能力：批量扫描、规则校验、自动修复（--fix）、CI 失败拦截。
• 运行方式：本包提供 CLI；规则引擎由 @lint-md/core 提供。

上下游关系

• 上游（依赖）：@lint-md/core（规则定义与 lint/fix 能力）。
• 当前仓库职责：参数解析、文件收集、并行执行、结果汇总与退出码控制。
• 下游（使用方）：文档仓库、写作流水线、CI/CD（如 GitHub Actions）中调用 lint-md。

安装

npm i -D @lint-md/cli

或全局安装：

npm i -g @lint-md/cli

快速开始

# 检查单个文件
lint-md README.md

# 检查目录内所有 Markdown 文件
lint-md "docs/**/*.md"

# 自动修复
lint-md "docs/**/*.md" --fix

Docker 使用

先构建镜像：

docker build -t lint-md .

只读检查场景：

docker run --rm \
  -v "$PWD:/work:ro" \
  -w /work \
  lint-md "docs/**/*.md"

对挂载目录执行 --fix 时，建议显式传入当前用户，避免把宿主文件写成容器内用户的属主：

docker run --rm \
  -u "$(id -u):$(id -g)" \
  -v "$PWD:/work" \
  -w /work \
  lint-md "docs/**/*.md" --fix

镜像默认使用非 root 用户运行；如果挂载目录权限较严格，--user 是最稳妥的用法。

常用参数

• -c, --config [configure-file]：指定配置文件（默认 ./.lintmdrc）
• -f, --fix：自动修复可修复问题
• -t, --threads [thread-count]：设置并发线程数
• -s, --suppress-warnings：忽略 warning 对退出码的影响（便于 CI 渐进接入）
• -i, --stdin：从标准输入读取 Markdown 内容
• -d, --dev：开发调试模式
• -v, --version：查看版本

配置示例（.lintmdrc）

{
  "excludeFiles": ["**/node_modules/**", "**/.git/**"],
  "extensions": [".md", ".markdown", ".mdx"],
  "rules": {
    "no-empty-code": true
  }
}

配置项说明

字段	类型	默认值	说明
excludeFiles	string[]	["**/node_modules/**", "**/.git/**"]	排除的文件 glob 模式
extensions	string[]	[".md", ".markdown", ".mdx"]	要 lint 的文件扩展名
rules	object	{}	规则配置，详见 @lint-md/core 文档

Core 2.3 新规则

以下规则默认关闭。请在项目根目录的 ./.lintmdrc 中启用它们。

{
  "rules": {
    "require-trailing-spaces": 2,
    "space-around-link": 2,
    "no-multiple-blank-lines": 2
  }
}

CLI 默认读取 ./.lintmdrc。 也可以使用 lint-md --config <文件路径> 指定配置文件。

直接使用 Core API 时，请在 fixMarkdown() 的 rules 中配置规则。

import { fixMarkdown, RULE_SEVERITY } from "@lint-md/core";

const markdown = "第一行\n第二行";
const result = fixMarkdown(markdown, {
  rules: {
    "require-trailing-spaces": RULE_SEVERITY.ERROR,
    "space-around-link": RULE_SEVERITY.ERROR,
    "no-multiple-blank-lines": RULE_SEVERITY.ERROR,
  },
});

console.log(result.fixedResult.result);

RULE_SEVERITY.ERROR 等同于规则级别 2。 fixMarkdown() 始终执行自动修复。 只检查时，请使用 lintMarkdown(markdown, rules, false)。

space-around-link 处理普通链接、自动链接和引用链接。 它不处理独立图片。 全角标点、其他 Unicode 标点、已有空白和块边界不需要空格。 连续链接之间只添加一个空格。

no-multiple-blank-lines 将连续空白行修复为一个空白行。 它删除文档开头的空白行。 它保留文档末尾的一个换行。 空格和 Tab 组成的行也算空白行。 代码块内部内容不受影响。

退出码约定

• 0：无错误（或仅 warning 且启用了 --suppress-warnings）
• 1：存在错误，或存在 warning 且未启用 --suppress-warnings