dsh-markdown-lint

dsh-markdown-lint

Markdown 检查插件（v0.3.0）：四类规则检查 + 可修复项自动修复。代码块内容全程跳过（围栏内 #、链接、表格都不误报）。

功能说明

dsh-markdown-lint 面向 Markdown 文档的质量检查与格式修复，提供"检查 + 修复"两个工具。

规则检查（lint_markdown）

规则	检查内容	可自动修复
heading-hierarchy	标题跳级（如 H1→H3）、文件级多个 H1	跳级可，多 H1 不可
list-indent	列表缩进使用 Tab、嵌套步长不一致（取出现 ≥2 次的最小宽度为标准）	可
link-exists	相对链接（./x.md、../a.md、sub/x.md）目标文件不存在	不可
table-format	表格缺分隔行、分隔行/数据行与表头列数不一致	不可

每条问题带行号与规则名，可修复项显式标注。

自动修复（fix_markdown）

• 跳级标题降级补齐
• Tab 缩进转 4 空格
• 嵌套列表步长统一
• 多 H1 降级为 H2（需显式传 demote_h1=true）
• 默认仅预览，write=true 才写回文件

主要特性

• 代码块全程跳过：围栏内的 #、链接等不会被误判为问题
• 两种输入方式：text 直接传内容，或 file 传入工作目录内的文件路径
• 解析基准明确：file 模式以文件所在目录解析相对链接，text 模式以 cwd 解析
• 可选外链检查：开启 check_http_links 后对 http(s) 链接做可达性校验（HEAD 优先、405 回退 GET、5s 超时、单次最多 20 条）
• 零 npm 依赖：仅使用 Node 内置模块

安装

npm install dsh-markdown-lint

工具

lint_markdown

参数	类型	说明
text / file	string	源内容二选一（file 须在工作目录内）

四类规则：

规则	内容	可自动修复
heading-hierarchy	标题跳级（H1→H3）；多个 H1（文件级）	跳级可，多 H1 需 demote_h1=true
list-indent	列表缩进用 Tab；嵌套步长不一致（≥2 次出现的宽度中取最小为标准）	可
link-exists	相对链接（./x.md、../a.md、sub/x.md）目标文件不存在；file 模式以文件所在目录解析，text 模式以 cwd 解析	不可
table-format	表格缺分隔行（第二行不是 `	---

http(s)/mailto/锚点链接不做联网检查。输出每条问题带行号、规则名与可修复标注。

fix_markdown

参数	类型	说明
text / file	string	源内容二选一
write	boolean	file 模式下 true 直接覆盖写回文件（默认 false 仅预览）
demote_h1	boolean	true 时把第 2 个及之后的 H1 降级为 H2（默认 false，多 H1 问题不会被动修改）

自动修复内容：跳级标题降级补齐、Tab 缩进转 4 空格、嵌套步长统一、多 H1 降级（需显式开启）。修复后残余的不可修复问题（多 H1、死链、表格格式）会提示用 lint_markdown 查看。

表格检查说明：连续含竖线的行视为一个表格块；单行含竖线的普通文本不判为表格；\| 转义竖线不做特殊处理。

安全与限制

• 文件路径必须在工作目录内；输入上限 1MB
• write=true 直接覆盖文件，建议先预览（默认行为）
• 相对链接检查只验证存在性，不验证指向内容正确性
• 零 npm 依赖

测试

npm test

覆盖四类规则的命中与不误报、代码块跳过、file/text 两种解析基准、修复写回（含多 H1 降级）、路径越界拒绝等 44 项断言。

版本历史

0.3.0（2026-09-30）

• 新增 table-format 规则：表格缺分隔行、分隔行/数据行与表头列数不一致
• fix_markdown 新增 demote_h1 参数：把第 2 个及之后的 H1 降级为 H2（默认关闭，避免静默改动标题层级）
• lint_markdown 的多 H1 提示中给出 demote_h1 用法
• 测试断言 28 → 44

0.2.0（2026-09-13）

• lint_markdown 新增 check_http_links 参数：http(s) 链接联网检查可用性（HEAD 优先、405 回退 GET、超时 5 秒、单次最多 20 个）

Roadmap（v0.4 候选）

• 自定义规则集（按需启停规则）
• 表格列宽对齐检查与自动整理
• 与 dsh-table-render 联动：把宽表格规范化为渲染友好格式

源码与发布地址

• 源码：https://github.com/geeklei/dsh-plugins/tree/main/dsh-markdown-lint
• npm：https://www.npmjs.com/package/dsh-markdown-lint

典型场景

1. 文档提交前检查

用户：这篇 README 有没有格式问题

lint_markdown 报告标题层级跳跃、列表缩进、代码块未闭合等问题。

2. 链接可达性检查

用户：文档里的链接还有效吗

lint_markdown 开启 check_http_links 联网校验（HEAD 优先、405 回退 GET、5s 超时、最多 20 条）。

3. 格式问题自动修复

用户：帮我把这些格式问题改掉

fix_markdown 修复可安全自动处理的项，其余仍以问题清单形式列出。

4. 发布前的文档体检

用户：这批文档发出去前统一检查一遍

对每个文件分别 lint，汇总问题清单。

安全边界

• 默认不联网：只有显式开启 check_http_links 才会发起网络请求，且限时（5s）、限量（最多 20 条）。
• fix_markdown 只改格式：不改写正文语义，不做破坏性重排。
• 只读检查：lint_markdown 不修改文件。
• 链接检查非权威：部分站点对 HEAD/自动请求返回 403/405，结果会区分"不可达"与"被拒绝"，需人工复核。

其他插件集成说明

协作插件	集成方式
dsh-http-client	链接检查的底层请求能力与 http-client 同源，需要更复杂的请求（带 header/鉴权）时改用 http-client
dsh-text-stats	检查通过后再统计字数/行数，产出文档质量与规模双指标
dsh-diff-writer	fix_markdown 之外的定制修改由 diff-writer 精确落地
dsh-table-render	文档中的表格可用 render_table 统一生成，避免手工对齐出错
dsh-workspace-journal	文档体检结果可写入工作区日志，跟踪长期质量趋势

FAQ

Q：为什么默认不检查外链？ 外链检查需要联网且可能较慢，默认关闭以免影响纯离线检查的确定性；需要时显式开启即可。

Q：链接返回 403 是不是就失效了？ 不一定。很多站点会拒绝自动化请求，插件会区分"不可达"与"被拒绝"，请人工复核。

Q：会自动修改我的文档吗？ 只有 fix_markdown 会写回，且仅限可安全自动处理的格式项。

Q：支持 GFM 表格/任务列表吗？ 支持常见 GFM 语法解析；复杂扩展语法（脚注、自定义容器）可能只做基础校验。