Back to Details

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

核心规则

  1. Always lint after changes - Run 
    markdownlint --fix
    then 
    markdownlint
    to verify
  2. Run from repository root - Ensures 
    .markdownlint.json
    config is loaded
  3. Use UTF-8 encoding - Especially for directory trees and special characters
  4. Follow WooCommerce markdown standards - See configuration rules below
  1. 修改后务必运行检查 - 先执行
    markdownlint --fix
    ，再运行
    markdownlint
    进行验证
  2. 从仓库根目录运行 - 确保加载
    .markdownlint.json
    配置文件
  3. 使用UTF-8编码 - 尤其适用于目录树和特殊字符场景
  4. 遵循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`参数必须为整数类型。

Links

链接

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文件编辑流程

  1. Make your changes to the markdown file
  2. Auto-fix linting issues:
    bash
    markdownlint --fix path/to/file.md
  3. Check for remaining issues:
    bash
    markdownlint path/to/file.md
  4. Manually fix what remains (usually language specs for code blocks)
  5. Verify clean - No output means success
  6. Commit changes
  1. 修改Markdown文件内容
  2. 自动修复检查问题：
    bash
    markdownlint --fix path/to/file.md
  3. 检查剩余问题：
    bash
    markdownlint path/to/file.md
  4. 手动修复剩余问题（通常为代码块的语言标记）
  5. 验证通过 - 无输出结果即为检查通过
  6. 提交修改

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
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检查命令