# Markdownlint 集成掌握将 markdownlint 集成到开发工作流程中，包括 CLI 使用、编程 API（同步/异步/承诺）、CI/CD 管道、预提交挂钩和编辑器集成。 ## 概述 Markdownlint 可以集成到开发工作流程的各个部分中，以确保一致的 Markdown 质量。这包括命令行工具、Node.js 中的编程使用、持续集成管道、Git 挂钩和编辑器插件。 ## 命令行界面 ### markdownlint-cli 安装 npm install -g markdownlint-cli # 或者作为开发依赖 npm install --save-dev markdownlint-cli ### CLI 基本用法 # Lint 当前目录中的所有 Markdown 文件 markdownlint '**/*.md' # Lint 特定文件 markdownlint README.md CONTRIBUTING.md # 使用配置文件进行 Lint markdownlint -c .markdownlint.json '**/*.md' # 忽略特定文件 markdownlint '**/*.md' --忽略node_modules # 自动修复违规行为 markdownlint -f '**/*.md' # 输出到文件 markdownlint '**/*.md' -o linting-results.txt ### 高级 CLI 选项 # 使用自定义配置 markdownlint --config config/markdown-lint.json 文档/ # 忽略文件中的模式 markdownlint --ignore-path .gitignore '**/*.md' # 使用多种忽略模式 markdownlint --忽略node_modules --忽略 dist '**/*.md' # 仅启用特定规则 markdownlint --规则 MD001、MD003、MD013 '**/*.md' # 禁用特定规则 markdownlint --禁用 MD013 '**/*.md' # 以 JSON 格式显示输出 markdownlint --json '**/*.md' # 安静模式（仅退出代码） markdownlint -q '**/*.md' # 详细输出 markdownlint --verbose '**/*.md' ### CLI 配置文件 `.markdownlint-cli.json`: { “配置”：{ “默认”：真， “MD013”：{ “行长”：100 } }, "文件": ["**/*.md"], “忽略”：[ “节点模块/**”， “距离/**”， “构建/**” ] } 与以下产品一起使用： markdownlint --config .markdownlint-cli.json ## 编程 API ### 基于回调的 API const markdownlint = require('markdownlint'); 常量选项 = { 文件：['好.md'，'坏.md']，配置：{ 默认值：真， '行长': { 行长：100 } } }; markdownlint(选项, (错误, 结果) => { 如果（！错误）{ console.log(结果.toString()); } 否则{ 控制台.错误（错误）； } }); ### 基于 Promise 的 API 从 'markdownlint/promise' 导入 { lint as lintPromise }；常量选项 = { 文件：['README.md', 'docs/**/*.md'], 配置：{ 默认值：真， '无内联-html'：{ 允许的元素：['br'，'img'] } } }; 尝试{ const 结果 = 等待 lintPromise(选项); console.dir(结果, { 颜色: true, 深度: null }); } 捕获（错误）{ 控制台.错误（错误）； } ### 同步API 从 'markdownlint/sync' 导入 { lint as lintSync }；常量选项 = { 文件：['README.md']，字符串：{ 'inline-content': '# 测试\n\n此处内容。' }, 配置：{ 默认值：true } }; const 结果 = lintSync(选项); console.log(结果.toString()); ### 字符串检查 const markdownlint = require('markdownlint'); 常量选项 = { 字符串：{ 'content-1': '# 标题\n\n段落文本。', 'content-2': '## 另一个标题\n\n更多内容。' }, 配置：{ 默认值：真， '第一行标题': { 等级：1 } } }; markdownlint(选项, (错误, 结果) => { 如果（！错误）{ const resultString = result.toString(); console.log(结果字符串); } }); ### 处理结果从 'markdownlint/promise' 导入 { lint } ； const 结果 = 等待 lint({ 文件：['docs/**/*.md'], 配置：{默认值：true} }); // 结果是一个由文件名键控的对象 Object.keys(结果).forEach(文件 => { const fileResults = 结果[文件]; fileResults.forEach(结果 => { console.log(`${file}:${result.lineNumber} ${result.ruleNames.join('/')} ${result.ruleDescription}`); if (结果.errorDetail) { console.log(`详细信息：${result.errorDetail}`); } if (结果.errorContext) { console.log(` 上下文: ${result.errorContext}`); } }); }); ### 读取配置 const markdownlint = require('markdownlint'); const { readConfigSync } = require('markdownlint/sync'); // 从文件中读取配置 const config = readConfigSync('.markdownlint.json'); 常量选项 = { 文件：['**/*.md'], 配置：配置 }; const 结果 = markdownlint.sync(options); console.log(结果.toString()); ### 使用自定义规则 const markdownlint = require('markdownlint'); const customRule = require('./custom-rules/heading-capitalization'); 常量选项 = { 文件：['README.md']，配置：{ 默认值：真， “标题大写”：true }, 自定义规则：[自定义规则] }; markdownlint(选项, (错误, 结果) => { 如果（！错误）{ console.log(结果.toString()); } }); ## 以编程方式应用修复 ### applyFix 函数 const { applyFix } = require('markdownlint'); const line = '带有额外空格的文本'; 常量修复信息 = { 编辑栏：1，删除次数：2，插入文本：'' }; const 固定 = applyFix(line, fixInfo); 控制台.log（已修复）； // '带有额外空格的文本' ### applyFixes 函数 const { applyFixes } = require('markdownlint'); const input = '# 标题\n\n\n段落'; 常量错误 = [ { 行号: 3, 规则名称：['MD012']， RuleDescription: '多个空行', 修复信息：{ 行号: 3, 删除次数：-1 } } ]; const 固定 = applyFixes(输入, 错误); 控制台.log（已修复）； // '# 标题\n\n段落' ### 自动修复工作流程 const fs = require('fs'); const markdownlint = require('markdownlint'); const { applyFixes } = require('markdownlint'); const 文件 = 'README.md'; const content = fs.readFileSync(file, 'utf8'); 常量选项 = { 字符串：{ [文件]：内容 }, 配置：{ 默认值：true } }; markdownlint(选项, (错误, 结果) => { 如果（！错误）{ 常量错误 = 结果[文件] || []； if (errors.length > 0) { const 固定 = applyFixes(内容, 错误); fs.writeFileSync(文件, 固定, 'utf8'); console.log(`修复了 ${file} 中的 ${errors.length} 问题`); } } }); ## CI/CD 集成 ### GitHub 操作 `.github/workflows/markdownlint.yml`：名称：Markdownlint 用户可调用： false 于：推：分支：[主要、开发] 拉请求：分支：[主要] 职位：棉绒：运行：ubuntu-latest 步骤： - 名称：结帐代码使用：actions/checkout@v3 - 名称：安装 Node.js 使用：actions/setup-node@v3 与：节点版本：'18' - 名称：安装依赖项运行：npm ci - 名称：运行 markdownlint 运行： npx markdownlint '**/*.md' --ignore node_modules - 名称：用结果注释 PR 如果：失败（）运行： | npx markdownlint '**/*.md' --忽略node_modules -o markdownlint-results.txt 猫 markdownlint-results.txt ### 使用 markdownlint-cli2 进行 GitHub Actions 名称：Markdownlint 用户可调用： false 上：[推，拉请求] 职位：棉绒：运行：ubuntu-latest 步骤： - 使用：actions/checkout@v3 - 名称：运行 markdownlint-cli2 使用：DavidAnson/markdownlint-cli2-action@v9 与：路径：'**/*.md' ### GitLab CI `.gitlab-ci.yml`：标记：图片：节点：18-alpine 阶段：测试之前的脚本： - npm install -g markdownlint-cli 脚本： - markdownlint '**/*.md' --忽略node_modules 仅： - 合并请求 - 主要文物：何时：on_failure 路径： - markdownlint-结果.txt ### CircleCI `.circleci/config.yml`：版本：2.1 职位：标记：泊坞窗： - 图像：cimg/节点：18.0 步骤： - 结帐 - 运行：名称：安装markdownlint 命令： npm install -g markdownlint-cli - 运行：名称：运行 linter 命令：markdownlint '**/*.md' --忽略node_modules 工作流程：版本：2 构建和测试：职位： -markdownlint ### 詹金斯管道 `詹金斯文件`：管道{ 代理任何阶段{ 阶段（'Lint Markdown'）{ 步骤{ sh 'npm install -g markdownlint-cli' sh 'markdownlint "**/*.md" --忽略node_modules' } } } 发布{ 总是{ 清理Ws() } 失败{ echo 'Markdownlint 发现问题！' } } } ### Azure 管道 `azure-pipelines.yml`：触发： - 主要池： vmImage: 'ubuntu-最新' 步骤： - 任务：NodeTool@0 输入：版本规格：'18.x' displayName: '安装 Node.js' - 脚本：| npm install -g markdownlint-cli displayName: '安装 markdownlint' - 脚本：| markdownlint '**/*.md' --忽略node_modules displayName: '运行 markdownlint' ## 预提交挂钩 ### 使用哈士奇安装哈士奇： npm install --save-dev husky npx 哈士奇安装创建预提交钩子： npx husky 添加 .husky/预提交“npm run lint:md” 将脚本添加到“package.json”： { “脚本”：{ "lint:md": "markdownlint '**/*.md' --忽略 node_modules", "lint:md:fix": "markdownlint -f '**/*.md' --忽略 node_modules" } } ### 使用 lint-staged 安装 lint-staged： npm install --save-dev lint-staged 在 `package.json` 中配置： { “lint-staged”：{ “*.md”：[ “markdownlint——修复”， “git 添加” ] } } 更新预提交挂钩： npx husky 添加 .husky/预提交“npx lint-staged” ### 使用预提交框架 `.pre-commit-config.yaml`：回购协议： - 仓库：https://github.com/igorshubovych/markdownlint-cli 修订版：v0.37.0 挂钩： - ID：markdownlint 参数：['--修复'] - 仓库：https://github.com/DavidAnson/markdownlint-cli2 修订版：v0.10.0 挂钩： - ID：markdownlint-cli2 参数：['--修复'] 安装及使用： pip install 预提交预提交安装预提交运行 --all-files ## 编辑器集成 ### Visual Studio 代码安装 markdownlint 扩展： 1.打开VSCode 2. 转到扩展（Cmd+Shift+X） 3.搜索“markdownlint” 4. 安装 David Anson 的“markdownlint” 在`.vscode/settings.json`中配置： { “markdownlint.config”：{ “默认”：真， “MD013”：{ “行长”：100 } }, “markdownlint.ignore”：[ “节点模块/**”， “距离/**” ], “editor.codeActionsOnSave”：{ “source.fixAll.markdownlint”：true } } ### Vim/Neovim 使用 ALE（异步 Lint 引擎）： " 在 .vimrc 或 init.vim 中让 g:ale_linters = { \ 'markdown': ['markdownlint'], \} 让 g:ale_fixers = { \ 'markdown': ['markdownlint'], \} 让 g:ale_markdown_markdownlint_options = '-c .markdownlint.json' " 启用保存时修复让 g:ale_fix_on_save = 1 ### 崇高文本通过包控制安装： 1.安装包控制 2.安装“SublimeLinter” 3.安装“SublimeLinter-contrib-markdownlint” 在首选项中配置： { “短绒”：{ “markdownlint”：{ “args”：[“-c”，“.markdownlint.json”] } } } ### 原子安装包： apm 安装 linter-markdownlint 在 Atom 设置或 `.atom/config.cson` 中配置： “linter-markdownlint”：配置路径：“.markdownlint.json” ## npm 脚本集成 ### package.json 脚本 { “脚本”：{ "lint": "npm run lint:md", "lint:md": "markdownlint '**/*.md' --忽略 node_modules", "lint:md:fix": "markdownlint -f '**/*.md' --忽略 node_modules", "lint:md:ci": "markdownlint '**/*.md' --忽略node_modules -o markdownlint-report.txt", "test": "npm run lint && npm run test:unit", “预提交”：“lint-staged” } } ### 跨平台兼容性使用 cross-env 来设置环境变量： { “脚本”：{ "lint:md": "跨环境 NODE_ENV=development markdownlint '**/*.md'" }, “开发依赖项”：{ “跨环境”：“^7.0.3” } } ## Docker 集成 ### Dockerfile FROM节点：18-alpine 工作目录/应用程序 # 全局安装 markdownlint 运行 npm install -g markdownlint-cli # 复制 markdown 文件复制。。 # 运行短绒检查 CMD [“markdownlint”，“**/*.md”，“--ignore”，“node_modules”] ### docker-compose.yml 版本：'3.8' 服务：标记：图片：节点：18-alpine 工作目录：/应用程序卷： - .:/应用程序命令：> sh -c "npm install -g markdownlint-cli && markdownlint '**/*.md' --忽略node_modules" 运行： docker-compose 运行 markdownlint ## Monorepo 集成 ### 工作区配置根`.markdownlint.json`： { “默认”：真， “行长”：{ “行长”：100 } } 根`package.json`： { “脚本”：{ "lint:md": "markdownlint '**/*.md' --忽略 node_modules", "lint:md:packages": "lerna run lint:md", "lint:md:all": "npm run lint:md && npm run lint:md:packages" } } 包级 `packages/api/package.json`: { “脚本”：{ "lint:md": "markdownlint '**/*.md'" } } ### 使用 Lerna { “脚本”：{ "lint:md": "lerna 运行 lint:md --stream" } } ### 使用 Turborepo `turbo.json`： { “管道”：{ “棉绒：md”：{ “输出”：[] } } } ## 报告和指标 ### 生成 HTML 报告使用自定义脚本： const fs = require('fs'); const markdownlint = require('markdownlint'); 常量选项 = { 文件：['**/*.md'], 配置：{默认值：true} }; markdownlint（选项，（错误，结果）=> { 如果（！错误）{ const html =generateHtmlReport(结果); fs.writeFileSync('markdownlint-report.html', html); } }); 函数generateHtmlReport（结果）{ let html = 'Markdownlint 报告'; html += '

Markdownlint 结果

'; Object.keys(结果).forEach(文件 => { html += `

${文件}

`; html += '

行 ${result.lineNumber}: ${result.ruleDescription}

'; }); html += ''; 返回 html； } ### 工具的 JSON 输出 markdownlint '**/*.md' --json > results.json 使用 jq 处理： markdownlint '**/*.md' --json | jq '.[] |选择（长度> 0）' ## 何时使用此技能 * 在新项目中设置markdownlint * 将 linting 集成到 CI/CD 管道中 * 配置预提交钩子 * 自动化文档质量检查 * 设置编辑器集成 * 构建自定义 linting 工作流程 * 创建自动修复脚本 * 实施文档标准 ## 最佳实践 1. **CI/CD 集成** \- 始终在持续集成中运行 linting 2. **预提交挂钩** \- 在问题到达版本控制之前捕获问题 3. **编辑器集成** \- 写作时获取实时反馈 4. **一致的配置** \- 在所有环境中使用相同的配置 5. **可能时自动修复** \- 使用 -f 标志自动修复违规 6. **快速失败** \- 配置 CI 在 linting 错误时失败 7. **忽略生成的文件** \- 排除构建工件和依赖项 8. **版本锁定** \- 在 package.json 中固定 markdownlint 版本 9. **文档标准** \- 保留有关 linting 规则的文档 10. **渐进增强** \- 从宽松的规则开始，随着时间的推移收紧 11. **团队沟通** \- 在申请之前讨论规则变更 12. **定期更新** \- 保持 markdownlint 更新以修复错误 13. **性能优化** \- 使用适当的 glob 模式 14. **错误报告** \- 配置有意义的错误输出 15. **自动修复前备份** \- 始终在运行修复之前提交 ## 常见陷阱 1. **缺少忽略模式** \- Linting node_modules 或构建目录 2. **错误的全局模式** \- CLI 中的文件匹配不正确 3. **找不到配置** \- 配置文件位置错误 4. **异步/同步不匹配** \- 将同步 API 与异步规则结合使用 5. **CI Timeout** \- Linting 太多文件而没有优化 6. **无退出代码检查** \- 不会因 linting 错误而导致 CI 失败 7. **覆盖文件** \- 使用自动修复而不进行版本控制 8. **缺少依赖项** \- 未在 CI 中安装 markdownlint 9. **平台差异** \- 操作系统之间的路径分隔符不同 10. **大型二进制文件** \- 意外地检查非 Markdown 文件 11. **过时的缓存** \- 使用旧的 markdownlint 缓存 node_modules 12. **静默失败** \- 未捕获 CI 中的错误输出 13. **配置冲突** \- 多个配置文件冲突 14. **缺少编辑器配置** \- 本地 linting 与 CI 不同 15. **无预提交挂钩** \- 提交前未捕获的问题 ## 资源 * [markdownlint GitHub 存储库]() * [markdownlint-cli]() * [markdownlint-cli2]() * [markdownlint VS 代码扩展]() * [GitHub Actions 集成]() * [API 文档]()

Markdownlint 集成

包含技能