woocommerce-markdown

WooCommerce Markdown 指南

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

关键规则

1. 更改后务必运行 lint - 先运行 markdownlint --fix，再运行 markdownlint 进行验证
2. 从仓库根目录运行 - 确保加载 .markdownlint.json 配置
3. 使用 UTF-8 编码 - 尤其是目录树和特殊字符
4. 遵循 WooCommerce Markdown 标准 - 参见下方的配置规则

WooCommerce Markdown 配置

项目使用 markdownlint，并启用了以下特定规则（来自 .markdownlint.json）：

已启用的规则

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

已禁用的规则

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

Markdown 编写指南

标题

# Main Title (H1) - Only one per file

## Section (H2)

### Subsection (H3)

#### Minor Section (H4)

• 使用 ATX 样式（#），而非下划线样式
• 每个文件使用一个 H1（通常是标题）
• 保持标题层级（不要跳过级别）

列表

无序列表：

- Item one
- Item two
    - Nested item (4 spaces)
    - Another nested item
- Item three

有序列表：

1. First item
2. Second item
3. Third item

重要提示：

• 嵌套列表项使用 4 个空格缩进
• 列表前后添加空行
• 无序列表使用 -（不要使用 * 或 +）

代码块

务必指定语言：

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

```php
public function process_order( int $order_id ) {
    // code here
}
```

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

常用语言标识符：

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

代码块规则：

• 起始围栏前添加空行
• 结束围栏后添加空行
• 务必指定语言（不要只使用 ```）

行内代码

使用反引号标记行内代码：

Use the `process_order()` method to handle orders.
The `$order_id` parameter must be an integer.

链接

[Link text](https://example.com)

[Internal link](../path/to/file.md)

[Link with title](https://example.com "Optional title")

表格

| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Value 1  | Value 2  | Value 3  |
| Value 4  | Value 5  | Value 6  |

• 使用竖线（|）分隔列
• 必须有表头分隔行
• 对齐方式可选（:---、:---:、---:）

目录树

务必使用 UTF-8 制表绘图字符：

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

切勿使用：

• ASCII 艺术字符（+--、|--）
• 用空格或制表符表示树形结构
• 控制字符

强调

**Bold text** for strong emphasis
*Italic text* for regular emphasis
***Bold and italic*** for very strong emphasis

Markdown 编辑工作流

1. 进行更改，编辑 Markdown 文件

2. 自动修复 lint 问题：

   markdownlint --fix path/to/file.md
   

3. 检查剩余问题：

   markdownlint path/to/file.md
   

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

5. 确认无误 - 没有输出即表示成功

6. 提交更改

常见 lint 错误及修复方法

MD007：列表缩进

问题：

- Item
  - Nested (only 2 spaces)

修复方法：

- Item
    - Nested (4 spaces)

MD031：代码块需要空行

问题：

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

修复方法：

Some text

```bash
command
```

More text

MD032：列表需要空行

问题：

Some text
- List item

修复方法：

Some text

- List item

MD036：将强调样式用作标题

问题：

**Example: Using bold as a heading**

Some content here

修复方法：

#### Example: Using a proper heading

Some content here

MD040：代码需要指定语言

问题：

```
code here
```

修复方法：

```bash
code here
```

特殊情况

CLAUDE.md 文件

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

• 格式必须清晰，以便 AI 最佳解析
• 严格遵循所有 markdownlint 规则
• 使用清晰的层级结构
• 长文件应包含目录

README 文件

• 以 H1 标题开头
• 包含简短说明
• 添加安装/使用部分
• 保持简洁，便于快速浏览

Changelog 文件

• 遵循 Keep a Changelog 格式
• 使用一致的日期格式
• 按类型分组更改（Added、Changed、Fixed 等）

故障排除

文件显示为“data”而不是文本

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

修复：

tr -d '\000-\037' < file.md > file.clean.md && mv file.clean.md file.md
file file.md  # Verify shows "UTF-8 text"

Lint 检查出现意外错误

问题： 未从代码库根目录运行

修复：

# Always run from root
cd /path/to/woocommerce
markdownlint path/to/file.md

# NOT like this
markdownlint /absolute/path/to/file.md

自动修复不起作用

问题： 有些问题需要手动处理

修复：

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

备注

• 大多数 Markdown 问题都可以通过 markdownlint --fix 自动修复
• 始终从代码库根目录运行 markdownlint
• 对于特殊字符，UTF-8 编码至关重要
• CLAUDE.md 文件必须通过 lint 检查，才能实现最佳 AI 解析效果
• 有关 Markdown lint 命令，请参阅 woocommerce-dev-cycle 技能