| name | markdown-lint |
| description | MindIE-SD 仓库 Markdown 格式 lint 规则。当编写、修改或审查 Markdown 文件（README、文档、 变更日志等）、或 CI 门禁报出 markdownlint 违规时使用此 skill。 即使用户只提到"格式问题"或"MD040报错"而未说 markdownlint，也应触发。 通常由 dev-workflow 和 code-standards 在编码/审查阶段指引加载。 |
Markdown 格式 Lint 规范
本 skill 汇总 MindIE-SD 仓库的 Markdown 格式 lint 规则，适用于 .md 文件的编写、修复与审查。
事实来源：
.pre-commit-config.yaml（markdownlint 钩子配置）markdownlint-cli v0.46.0 规则集
1. 核心规则
1.1 MD040 — Fenced code blocks should have a language specified
所有围栏代码块（```）必须指定编程语言或内容类型。
正例：
```shell
npu-smi info -l
```python
def foo():
pass
**反例（触发 MD040）：**
```markdown
examples/dummy_run/
├── model/
├── wan_infer.py
└── README.md
代码块语言选用指南：
| 内容类型 | 语言标记 |
|---|
| Python 代码 | python |
| Shell 命令 | shell 或 bash |
| 目录 / 文件树 | text |
| 终端输出 / 日志 | text |
| 纯文本 / 伪代码 | text |
| YAML 配置 | yaml |
| Markdown 示例 | markdown |
| JSON 数据 | json |
1.2 其他常见规则
| 规则 | 说明 |
|---|
| MD009 | 禁止行尾空格（由 trailing-whitespace 钩子覆盖） |
| MD012 | 禁止连续多个空白行 |
| MD031 | 围栏代码块前后需有空行 |
| MD047 | 文件末尾需有换行符（由 end-of-file-fixer 钩子覆盖） |
2. 验证命令
2.1 全量检查
# 检查单个文件
pre-commit run markdownlint --files path/to/file.md
# 检查所有文件（CI 模式）
pre-commit run markdownlint --all-files
markdownlint 钩子在 .pre-commit-config.yaml 中配置为 stages: [manual]，需显式触发。
2.2 提交范围专项检查
对 commit 新增或修改的 .md 文件做独立检查，避免全量噪音：
git diff --name-only HEAD~1..HEAD -- '*.md' | xargs markdownlint -c .markdownlint.json
2.3 配置优先
- 始终使用
-c .markdownlint.json 配置文件而非 --disable 命令行参数
- PowerShell 中
--disable MDxxx 的数组传参可能不生效，导致规则未真正禁用
3. 修复模板
3.1 目录树 / 终端输出
<!-- 修改前 -->
examples/
├── a.py
└── b.py
<!-- 修改后 -->
```text
examples/
├── a.py
└── b.py
### 3.2 无明确代码语言的内容
```markdown
<!-- 修改前 -->
Warmup inference (1 step) ...
[transformer] 7.1s
Inference time: 7.1 s
<!-- 修改后 -->
```text
Warmup inference (1 step) ...
[transformer] 7.1s
Inference time: 7.1 s
---
## 4. 与 dev-workflow 的关系
本 skill 作为 `dev-workflow` 的补充模块，在以下时机触发：
- 新建或修改 `.md` 文件后，提交前
- CI 门禁报出 `markdownlint` 违规时
- 模板文件（PR/Issue）变更时
`dev-workflow` 的 Test-First 流程中，编码阶段需确保 Python 代码通过 Ruff 检查，同时确保 Markdown 文件通过 `markdownlint` 检查。
---
## 5. 批量修复注意事项
### 5.1 编码安全
PowerShell 5.1 下用 `Get-Content` / `Set-Content` 读写含中文的 UTF-8 文件会导致编码破坏（BOM 注入 + 字节重解释）。
**安全方式：**
- Python：`open(f, 'r', encoding='utf-8')` / `open(f, 'w', encoding='utf-8')`
- Node.js：`fs.readFileSync(f, 'utf-8')` / `fs.writeFileSync(f, content, 'utf-8')`
**避免：** PowerShell `Get-Content` / `Set-Content` / `Out-File` 直接读写 UTF-8 含中文文件。
### 5.2 MD040 修复模式
替换 `` ``` `` → `` ```text `` 时需覆盖两种变体：
- **顶格** `` ``` ``（行首无空白）
- **缩进** `` ``` ``、`` ``` `` 等（保留前导空白，缩进代码块）
### 5.3 修复后验证
1. 重跑 `markdownlint -c .markdownlint.json <files>` 确认 0 违规
2. `git diff` 检查只有预期替换行变化，无编码污染（BOM、乱码）
3. 确认中文等非 ASCII 字符未损坏
## 6. 维护与更新
当 `markdownlint-cli` 版本升级、`.pre-commit-config.yaml` 中 markdownlint 配置变更、
或新 MD 规则启用时，按 `dev-workflow` 的复盘流程更新本 skill。
