202 lines
No EOL
4.7 KiB
Markdown
202 lines
No EOL
4.7 KiB
Markdown
# Markdown 代码检查
|
||
|
||
## 目录
|
||
|
||
- [关键规则](#critical-rule)
|
||
- [安装](#installation)
|
||
- [基本命令](#basic-commands)
|
||
- [重要：始终从仓库根目录运行](#important-always-run-from-repository-root)
|
||
- [推荐工作流程](#recommended-workflow)
|
||
- [常见 Markdown 代码检查问题](#common-markdown-linting-issues)
|
||
- [Markdown 文件中的字符编码](#character-encoding-in-markdown-files)
|
||
- [示例](#examples)
|
||
- [备注](#notes)
|
||
|
||
## 关键规则
|
||
|
||
**更改后务必对 Markdown 文件进行代码检查。** 它们必须通过 markdownlint 验证。
|
||
|
||
## 安装
|
||
|
||
如果 markdownlint 无法使用：
|
||
|
||
```bash
|
||
npm install -g markdownlint-cli
|
||
```
|
||
|
||
## 基础命令
|
||
|
||
```bash
|
||
# 检查 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` 配置文件。
|
||
|
||
使用绝对路径会绕过配置，并可能显示不正确的错误。
|
||
|
||
```bash
|
||
# ✅ 正确 - 从仓库根目录运行
|
||
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 艺术：
|
||
|
||
```markdown
|
||
✅ 正确 - 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` 后使用编辑工具**，如果文件包含目录树。
|
||
|
||
**务必首先检查文件编码：**
|
||
|
||
```bash
|
||
file path/to/file.md
|
||
# 应显示："UTF-8 text" 或 "ASCII text"
|
||
# 切勿显示："data"
|
||
```
|
||
|
||
### 修复损坏的文件
|
||
|
||
如果文件损坏（显示为"data"而非文本）：
|
||
|
||
```bash
|
||
# 移除控制字符和空字节
|
||
tr -d '\000-\037' < file.md > file.clean.md && mv file.clean.md file.md
|
||
|
||
# 修复后验证编码
|
||
file file.md
|
||
```
|
||
|
||
## 例子
|
||
|
||
### 为代码区块添加语言规范
|
||
|
||
**前:**
|
||
|
||
````markdown
|
||
```
|
||
pnpm test:php:env
|
||
```
|
||
````
|
||
|
||
**后:**
|
||
|
||
````markdown
|
||
```bash
|
||
pnpm test:php:env
|
||
```
|
||
````
|
||
|
||
常见的语言规范：
|
||
|
||
- `bash` - Shell 命令
|
||
- `php` - PHP 代码
|
||
- `javascript` 或 `js` - JavaScript
|
||
- `typescript` 或 `ts` - TypeScript
|
||
- `json` - JSON 数据
|
||
- `markdown` 或 `md` - Markdown 例子
|
||
|
||
### 断行长行
|
||
|
||
**前：**
|
||
|
||
```markdown
|
||
This is a very long line that exceeds the 80 character limit and needs to be broken into multiple lines for better readability.
|
||
```
|
||
|
||
**后：**
|
||
|
||
```markdown
|
||
This is a very long line that exceeds the 80 character limit and needs to be
|
||
broken into multiple lines for better readability.
|
||
```
|
||
|
||
### 代码块周围的空白行
|
||
|
||
**前：**
|
||
|
||
````markdown
|
||
Some text here
|
||
```bash
|
||
command here
|
||
```
|
||
More text
|
||
````
|
||
|
||
**后：**
|
||
|
||
````markdown
|
||
Some text here
|
||
|
||
```bash
|
||
command here
|
||
```
|
||
|
||
More text
|
||
````
|
||
|
||
## 注意事项
|
||
|
||
- `markdownlint --fix` 命令会自动处理大多数问题
|
||
- CLAUDE.md 文件是 AI 助手文档，必须格式良好以实现最佳解析
|
||
- 只有少数问题需要手动修复（语言规范、长行）
|
||
- 编辑后务必验证编码以防止损坏 |
