woocommerce/.ai/skills/woocommerce-dev-cycle/zh-cn/markdown-linting.md

Markdown 代码检查

目录

• 关键规则
• 安装
• 基本命令
• 重要：始终从仓库根目录运行
• 推荐工作流程
• 常见 Markdown 代码检查问题
• Markdown 文件中的字符编码
• 示例
• 备注

关键规则

更改后务必对 Markdown 文件进行代码检查。 它们必须通过 markdownlint 验证。

安装

如果 markdownlint 无法使用：

npm install -g markdownlint-cli

基础命令

# 检查 markdown 文件（从仓库根目录运行）
markdownlint plugins/woocommerce/CLAUDE.md

# 推荐：首先自动修复问题（处理大多数错误）
markdownlint --fix plugins/woocommerce/CLAUDE.md

# 检查多文件
markdownlint packages/js/CLAUDE.md plugins/woocommerce/CLAUDE.md

# 检查所有 CLAUDE.md 文件
markdownlint packages/js/CLAUDE.md plugins/woocommerce/CLAUDE.md \
  plugins/woocommerce/client/admin/CLAUDE.md

重要：总是从仓库根目录运行

关键提示： 总是从仓库根目录运行 markdownlint，以便加载 .markdownlint.json 配置文件。

使用绝对路径会绕过配置，并可能显示不正确的错误。

# ✅ 正确 - 从仓库根目录运行
cd /path/to/woocommerce
markdownlint plugins/woocommerce/CLAUDE.md

# ❌ 错误 - 绕过配置
markdownlint /absolute/path/to/plugins/woocommerce/CLAUDE.md

推荐工作流程

1. 进行 Markdown 更改
2. 运行 markdownlint --fix path/to/file.md（自动修复大部分问题）
3. 检查剩余问题：markdownlint path/to/file.md
4. 手动修复剩余问题（语言规范、长行等）
5. 验证无误后提交

常见的 Markdown 语法检查问题

代码	问题	描述	修复方法
MD007	列表缩进	缩进级别错误	为嵌套项目使用 4 个空格
MD013	行长度限制	行超过 80 个字符	拆分成多行
MD031	代码块需要空白行	缺少空白行	在代码块上方/下方添加空白行
MD032	列表需要空白行	缺少空白行	在列表前/后添加空白行
MD036	强调作为标题	使用粗体代替标题	使用 ### 而非粗体
MD040	代码需要语言	缺少语言说明	添加：```bash, ```php 等
MD047	需要尾随换行符	文件未以换行符结尾	文件必须以换行符结尾

Markdown 文件中的字符编码

关键：使用正确的 UTF-8 字符

绝不允许控制字符或空字节进入 markdown 文件。

目录树

使用 UTF-8 盒子绘制字符，而非空格、标签或 ASCII 艺术：

✅ 正确 - UTF-8 盒子绘制：
.ai/skills/
├── woocommerce-backend/
│   ├── SKILL.md
│   └── file-entities.md
└── woocommerce-dev-cycle/
    └── SKILL.md

❌ 错误 - ASCII 艺术或空格：
.ai/skills/
+-- woocommerce-backend/
|   +-- SKILL.md
    +-- file-entities.md

避免文件损坏

切勿在 markdownlint --fix 后使用编辑工具，如果文件包含目录树。

务必首先检查文件编码：

file path/to/file.md
# 应显示："UTF-8 text" 或 "ASCII text"
# 切勿显示："data"

修复损坏的文件

如果文件损坏（显示为"data"而非文本）：

# 移除控制字符和空字节
tr -d '\000-\037' < file.md > file.clean.md && mv file.clean.md file.md

# 修复后验证编码
file file.md

例子

为代码区块添加语言规范

前:

```
pnpm test:php:env
```

后:

```bash
pnpm test:php:env
```

常见的语言规范：

• bash - Shell 命令
• php - PHP 代码
• javascript 或 js - JavaScript
• typescript 或 ts - TypeScript
• json - JSON 数据
• markdown 或 md - Markdown 例子

断行长行

前：

This is a very long line that exceeds the 80 character limit and needs to be broken into multiple lines for better readability.

后：

This is a very long line that exceeds the 80 character limit and needs to be
broken into multiple lines for better readability.

代码块周围的空白行

前：

Some text here
```bash
command here
```
More text

后：

Some text here

```bash
command here
```

More text

注意事项

• markdownlint --fix 命令会自动处理大多数问题
• CLAUDE.md 文件是 AI 助手文档，必须格式良好以实现最佳解析
• 只有少数问题需要手动修复（语言规范、长行）
• 编辑后务必验证编码以防止损坏