用途:在项目中安装、配置和使用 markdownlint,对 Markdown 文件进行规则检查(linting),并处理检查发现的问题。
主要能力:支持规则名称、代码与选项的启用或禁用;支持忽略文件、文件夹与匹配模式;支持诊断违规、自动修复与剩余手动修复;可与脚本、hooks、CI 及编辑器集成;并提供安装配置与故障排查参考。
必要用法:操作前先检测项目的包管理器。依据锁文件判断:pnpm-lock.yaml 用 pnpm,yarn.lock 用 yarn,package-lock.json 用 npm,bun.lockb 用 bun;也可检查 package.json 的 packageManager 字段。若无法判断,应询问用户偏好。示例命令使用 pnpm,实际需替换为检测到的包管理器,例如 pnpm add -D 对应 npm install --save-dev / yarn add -D / bun add -d。安装命令:pnpm add -D markdownlint markdownlint-cli。运行:pnpm run lint:markdown。自动修复:vpx markdownlint '/*.md' --fix。检查单个文件:vpx markdownlint README.md。检查目录:vpx markdownlint 'docs//*.md'。
配置:在项目根目录创建 .markdownlint.yaml,可引用 $schema 指向 ./node_modules/markdownlint/schema/markdownlint-config-schema.json。示例:line-length: false(禁用)、no-duplicate-heading: true(启用)、heading-style: style: "atx"(配置)。忽略文件使用 .markdownlintignore,语法同 gitignore,如 node_modules、dist/、build/、CHANGELOG.md。
默认配置思路:保留标准规则,禁用 line-length,理由是编辑器和查看器会自动换行、固定行长度多数项目会造成摩擦、语义问题比呈现问题更有价值。可按需另行定制规则。
适用场景:需要为项目统一 Markdown 风格、在 CI 或 hooks 中检查 Markdown、或修复已有违规时。
限制:资料未提供具体的版本兼容、性能数据、全部规则清单及平台差异,这些内容暂未提供。