woocommerce/.ai/skills/woocommerce-markdown/zh-cn/SKILL.md

name	description
woocommerce-markdown	Guidelines for creating and modifying markdown files in WooCommerce. Use when writing documentation, README files, or any markdown content.

WooCommerce Markdown 指南

本技能为在 WooCommerce 项目中创建和编辑 markdown 文件提供指导。

关键规则

1. 更改后始终进行代码检查 - 运行 markdownlint --fix 然后运行 markdownlint 以验证
2. 从仓库根目录运行 - 确保加载 .markdownlint.json 配置
3. 使用 UTF-8 编码 - 特别是对于目录树和特殊字符
4. 遵循 WooCommerce markdown 标准 - 请参阅下面的配置规则

WooCommerce Markdown 配置

该项目使用 markdownlint 并遵循以下特定规则（来自 .markdownlint.json）：

启用的规则

• MD003: 标题样式必须为 ATX（使用 # 标题 而非 标题\n===）
• MD007: 无序列表缩进必须为 4 个空格
• MD013: 行长度限制已禁用（设置为 9999）
• MD024: 允许存在内容相同的多个标题（仅检查同级标题）
• MD031: 围栏代码块前后必须有空行
• MD032: 列表前后必须有空行
• MD033: 仅允许为 <video> 元素使用 HTML
• MD036: 不应使用强调（粗体/斜体）作为标题 - 应使用正确的标题标签
• MD040: 围栏代码块应指定语言
• MD047: 文件必须以单个换行符结尾

禁用规则

• no-hard-tabs: 允许使用制表符
• whitespace: 禁用尾随空格规则

Markdown 撰写指南

标题

# 主标题 (H1) - 每个文件仅一个

## 部分 (H2)

### 子部分 (H3)

#### 次要部分 (H4)

• 使用 ATX 风格 (#) 而非下划线风格
• 每个文件一个 H1 标题（通常是标题）
• 保持标题层次结构（不要跳过级别）

列表

无序列表：

- 项目一
- 项目二
    - 嵌套项目（4个空格）
    - 另一个嵌套项目
- 项目三

有序列表：

1. 第一项
2. 第二项
3. 第三项

重要：

• 嵌套列表项目使用 4 个空格
• 在列表前后添加空白行
• 无序列表使用 -（而非 * 或 +）

代码块

始终指定语言：

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

```php
public function process_order( int $order_id ) {
    // 此处代码
}
```

```javascript
const result = calculateTotal(items);
```

常用语言标识符：

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

代码块规则：

• 在起始围栏前添加空行
• 在结束围栏后添加空行
• 始终指定语言（切勿使用普通的 ```）

内联代码

对内联代码使用反引号：

使用 `process_order()` 方法来处理订单。
`$order_id` 参数必须是整数。

链接

[链接文本](https://example.com)

[内部链接](.ai/skills/woocommerce-markdown/path/to/file)

[带标题的链接](https://example.com "可选标题")

表格

| 列 1 | 列 2 | 列 3 |
|----------|----------|----------|
| 值 1  | 值 2  | 值 3  |
| 值 4  | 值 5  | 值 6  |

• 使用管道符 (|) 作为列分隔符
• 必须包含标题分隔行
• 对齐方式可选 (:---, :---:, ---:)

目录树

始终使用 UTF-8 制表符字符：

src/
├── Internal/
│   ├── Admin/
│   │   └── Controller.php
│   └── Utils/
│       └── Helper.php
└── External/
    └── API.php

切勿使用：

• ASCII 艺术字符 (+--, |--)
• 空格或制表符来表示树结构
• 控制字符

强调

**粗体文本** 用于强烈强调
*斜体文本* 用于常规强调
***粗斜体*** 用于非常强烈的强调

Markdown 编辑工作流

1. 进行更改 到 markdown 文件

2. 自动修复 linting 问题：

   markdownlint --fix path/to/file.md
   

3. 检查剩余问题：

   markdownlint path/to/file.md
   

4. 手动修复 剩余问题（通常是代码块的语言规范）

5. 验证清理 - 无输出表示成功

6. 提交更改

常见 Linting 错误及修复

MD007: 列表缩进

问题：

- 项目
  - 嵌套（仅 2 个空格）

修复：

- 项目
    - 嵌套（4 个空格）

MD031: 代码块需要空行

问题：

一些文本
```bash
命令
```
更多文本

修复：

一些文本

```bash
命令
```

更多文本

MD032: 列表需要空行

问题：

一些文本
- 列表项目

修复：

一些文本

- 列表项目

MD036: 强调作为标题

问题：

**示例：使用粗体作为标题**

此处是一些内容

修复：

#### 示例：使用正确的标题

此处有一些内容

MD040：代码需要指定语言

问题：

```
此处是代码
```

修复：

```bash
此处是代码
```

特殊情况

CLAUDE.md 文件

CLAUDE.md 文件是 AI 助手文档：

• 必须格式良好，以便 AI 进行最佳解析
• 严格遵守所有 markdownlint 规则
• 使用清晰、层次化的结构
• 对于长文件，包含目录

README 文件

• 以 H1 标题开始
• 包含简要描述
• 添加安装/使用部分
• 保持简洁且易于浏览

更新日志文件

• 遵循 Keep a Changelog 格式
• 使用一致的日期格式
• 按类型（新增、更改、修复等）对更改进行分组

故障排除

文件显示为 "data" 而非文本

问题： 文件因控制字符而损坏

修复：

tr -d '\000-\037' < file.md > file.clean.md && mv file.clean.md file.md
file file.md  # 验证显示为 "UTF-8 text"

代码检查显示意外错误

问题： 未从仓库根目录运行

修复：

# 总是从根目录运行
cd /path/to/woocommerce
markdownlint path/to/file.md

# 不要像这样
markdownlint /absolute/path/to/file.md

自动修复功能失效

问题： 某些问题需要手动干预

修复方法：

• 代码区块的语言规范必须手动添加
• 长行可能需要手动重新换行
• 某些结构性问题需要内容重组

注意

• 大多数 Markdown 问题可以通过 markdownlint --fix 自动修复
• 总是从仓库根目录运行 markdownlint
• UTF-8 编码对于特殊字符至关重要
• CLAUDE.md 文件必须通过 linting 检查以实现最佳 AI 解析
• 查看 woocommerce-dev-cycle 技能以获取 Markdown linting 命令