woocommerce-markdown

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

WooCommerce Markdown Guidelines

WooCommerce Markdown 编写指南

This skill provides guidance for creating and editing markdown files in the WooCommerce project.

本指南为WooCommerce项目中创建和编辑Markdown文件提供规范指导。

Critical Rules

核心规则

Always lint after changes - Run
```
markdownlint --fix
```
then
```
markdownlint
```
to verify
Run from repository root - Ensures
```
.markdownlint.json
```
config is loaded
Use UTF-8 encoding - Especially for directory trees and special characters
Follow WooCommerce markdown standards - See configuration rules below

修改后务必运行检查 - 先执行
```
markdownlint --fix
```
，再运行
```
markdownlint
```
进行验证
从仓库根目录运行 - 确保加载
```
.markdownlint.json
```
配置文件
使用UTF-8编码 - 尤其适用于目录树和特殊字符场景
遵循WooCommerce Markdown标准 - 详见下方配置规则

WooCommerce Markdown Configuration

WooCommerce Markdown 配置规则

The project uses markdownlint with these specific rules (from

.markdownlint.json

项目使用markdownlint工具，并采用以下特定规则（来自

.markdownlint.json

）：

Enabled Rules

启用的规则

MD003: Heading style must be ATX (
```
# Heading
```
not
```
Heading\n===
```
)
MD007: Unordered list indentation must be 4 spaces
MD013: Line length limit disabled (set to 9999)
MD024: Multiple headings with same content allowed (only check siblings)
MD031: Fenced code blocks must be surrounded by blank lines
MD032: Lists must be surrounded by blank lines
MD033: HTML allowed for
```
<video>
```
elements only
MD036: Emphasis (bold/italic) should not be used as headings - use proper heading tags
MD040: Fenced code blocks should specify language
MD047: Files must end with a single newline

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

Disabled Rules

禁用的规则

no-hard-tabs: Tabs are allowed
whitespace: Trailing whitespace rules disabled

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

Markdown Writing Guidelines

Markdown 编写规范

Headings

标题

markdown

undefined

markdown

undefined

Main Title (H1) - Only one per file

主标题（H1）- 每个文件仅允许一个

Section (H2)

章节（H2）

Subsection (H3)

子章节（H3）

Minor Section (H4)

小章节（H4）


- Use ATX style (`#`) not underline style
- One H1 per file (usually the title)
- Maintain heading hierarchy (don't skip levels)


- 使用ATX格式（`#`），而非下划线格式
- 每个文件仅保留一个H1标题（通常为文件标题）
- 保持标题层级连贯（请勿跳过层级）

Lists

列表

Unordered lists:

markdown

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

Ordered lists:

markdown

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

Important:

Use 4 spaces for nested list items
Add blank line before and after lists
Use
```
-
```
for unordered lists (not
```
*
```
or
```
+
```
)

无序列表：

markdown

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

有序列表：

markdown

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

注意事项：

嵌套列表项使用4个空格缩进
列表前后需添加空行
无序列表使用
```
-
```
作为标记（而非
```
*
```
或
```
+
```
）

Code Blocks

代码块

Always specify the language:

markdown

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

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

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

Common language identifiers:

```
bash
```
- Shell commands
```
php
```
- PHP code
```
javascript
```
or
```
js
```
- JavaScript
```
typescript
```
or
```
ts
```
- TypeScript
```
json
```
- JSON data
```
sql
```
- SQL queries
```
markdown
```
or
```
md
```
- Markdown examples

Code block rules:

Add blank line before the opening fence
Add blank line after the closing fence
Always specify language (never use plain
```
```
```
)

必须指定编程语言：

markdown

```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示例

代码块规则：

代码块起始标记前需添加空行
代码块结束标记后需添加空行
必须指定编程语言（请勿使用无语言标记的
```
```
```
）

Inline Code

行内代码

Use backticks for inline code:

markdown

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

使用反引号包裹行内代码：

markdown

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

链接

markdown

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

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

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

markdown

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

[内部链接](../path/to/file.md)

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

Tables

表格

markdown

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

Use pipes (
```
|
```
) for column separators
Header separator row required
Alignment optional (
```
:---
```
,
```
:---:
```
,
```
---:
```
)

markdown

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

使用竖线（
```
|
```
）作为列分隔符
必须包含表头分隔行
可选设置对齐方式（
```
:---
```
左对齐,
```
:---:
```
居中,
```
---:
```
右对齐）

Directory Trees

目录树

Always use UTF-8 box-drawing characters:

markdown

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

Never use:

ASCII art (
```
+--
```
,
```
|--
```
)
Spaces or tabs for tree structure
Control characters

务必使用UTF-8方框绘制字符：

markdown

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

禁止使用：

ASCII字符绘制（
```
+--
```
,
```
|--
```
）
空格或制表符构建树结构
控制字符

Emphasis

强调格式

markdown

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

markdown

**粗体文本**用于强强调
*斜体文本*用于常规强调
***粗斜体文本***用于极强强调

Workflow for Editing Markdown

Markdown文件编辑流程

Make your changes to the markdown file
Auto-fix linting issues:
bash
```
markdownlint --fix path/to/file.md
```
Check for remaining issues:
bash
```
markdownlint path/to/file.md
```
Manually fix what remains (usually language specs for code blocks)
Verify clean - No output means success
Commit changes

修改Markdown文件内容
自动修复检查问题：
bash
```
markdownlint --fix path/to/file.md
```
检查剩余问题：
bash
```
markdownlint path/to/file.md
```
手动修复剩余问题（通常为代码块的语言标记）
验证通过 - 无输出结果即为检查通过
提交修改

Common Linting Errors and Fixes

常见检查错误及修复方案

MD007: List indentation

MD007: 列表缩进错误

Problem:

markdown

- Item
  - Nested (only 2 spaces)

Fix:

markdown

- Item
    - Nested (4 spaces)

问题：

markdown

- 列表项
  - 嵌套项（仅2个空格）

修复：

markdown

- 列表项
    - 嵌套项（4个空格）

MD031: Code blocks need blank lines

MD031: 代码块前后缺少空行

Problem:

markdown

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

Fix:

markdown

Some text

```bash
command
```

More text

问题：

markdown

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

修复：

markdown

一些文本

```bash
命令
```

更多文本

MD032: Lists need blank lines

MD032: 列表前后缺少空行

Problem:

markdown

Some text
- List item

Fix:

markdown

Some text

- List item

问题：

markdown

一些文本
- 列表项

修复：

markdown

一些文本

- 列表项

MD036: Emphasis as heading

MD036: 使用强调格式代替标题

Problem:

markdown

**Example: Using bold as a heading**

Some content here

Fix:

markdown

undefined

问题：

markdown

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

此处为内容

修复：

markdown

undefined

Example: Using a proper heading

示例：使用标准标题

Some content here

undefined

此处为内容

undefined

MD040: Code needs language

MD040: 代码块未指定语言

Problem:

markdown

```
code here
```

Fix:

markdown

```bash
code here
```

问题：

markdown

```
代码内容
```

修复：

markdown

```bash
代码内容
```

Special Cases

特殊情况

CLAUDE.md Files

CLAUDE.md文件

CLAUDE.md files are AI assistant documentation:

Must be well-formatted for optimal parsing by AI
Follow all markdownlint rules strictly
Use clear, hierarchical structure
Include table of contents for long files

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

必须格式规范，以确保AI能最优解析
严格遵循所有markdownlint规则
使用清晰的层级结构
长文件需包含目录

README Files

README文件

Start with H1 title
Include brief description
Add installation/usage sections
Keep concise and scannable

以H1标题开头
包含简要描述
添加安装/使用章节
保持内容简洁、易读

Changelog Files

更新日志文件

Follow Keep a Changelog format
Use consistent date formatting
Group changes by type (Added, Changed, Fixed, etc.)

遵循Keep a Changelog格式
使用统一的日期格式
按类型分组变更内容（新增、修改、修复等）

Troubleshooting

问题排查

File Shows as "data" Instead of Text

文件显示为“数据”而非文本

Problem: File is corrupted with control characters

Fix:

bash

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

问题： 文件被控制字符损坏

修复：

bash

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

Linting Shows Unexpected Errors

检查工具显示意外错误

Problem: Not running from repository root

Fix:

bash

undefined

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

修复：

bash

undefined

Always run from root

务必从根目录运行

cd /path/to/woocommerce markdownlint path/to/file.md

NOT like this

请勿这样运行

markdownlint /absolute/path/to/file.md

undefined

markdownlint /absolute/path/to/file.md

undefined

Auto-fix Doesn't Work

自动修复功能无效

Problem: Some issues require manual intervention

Fix:

Language specs for code blocks must be added manually
Long lines may need manual rewrapping
Some structural issues require content reorganization

问题： 部分问题需要手动处理

修复：

代码块的语言标记必须手动添加
过长的行可能需要手动换行
部分结构问题需要重新组织内容

Notes

注意事项

Most markdown issues are auto-fixable with
```
markdownlint --fix
```
Always run markdownlint from repository root
UTF-8 encoding is critical for special characters
CLAUDE.md files must pass linting for optimal AI parsing
See
```
woocommerce-dev-cycle
```
skill for markdown linting commands

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

woocommerce-markdown

Original

Translation

WooCommerce Markdown Guidelines

WooCommerce Markdown 编写指南

Critical Rules

核心规则

WooCommerce Markdown Configuration

WooCommerce Markdown 配置规则

Enabled Rules

启用的规则

Disabled Rules

禁用的规则

Markdown Writing Guidelines

Markdown 编写规范

Headings

标题

Main Title (H1) - Only one per file

主标题（H1）- 每个文件仅允许一个

Section (H2)

章节（H2）

Subsection (H3)

子章节（H3）

Minor Section (H4)

小章节（H4）

Lists

列表

Code Blocks

代码块

Inline Code

行内代码

Links

链接

Tables

表格

Directory Trees

目录树

Emphasis

强调格式

Workflow for Editing Markdown

Markdown文件编辑流程

Common Linting Errors and Fixes

常见检查错误及修复方案

MD007: List indentation

MD007: 列表缩进错误

MD031: Code blocks need blank lines

MD031: 代码块前后缺少空行

MD032: Lists need blank lines

MD032: 列表前后缺少空行

MD036: Emphasis as heading

MD036: 使用强调格式代替标题

Example: Using a proper heading

示例：使用标准标题

MD040: Code needs language

MD040: 代码块未指定语言

Special Cases

特殊情况

CLAUDE.md Files

CLAUDE.md文件

README Files

README文件

Changelog Files

更新日志文件

Troubleshooting

问题排查

File Shows as "data" Instead of Text

文件显示为“数据”而非文本

Linting Shows Unexpected Errors

检查工具显示意外错误

Always run from root

务必从根目录运行

NOT like this

请勿这样运行

Auto-fix Doesn't Work

自动修复功能无效

Notes

注意事项