364 lines
No EOL
6.6 KiB
Markdown
364 lines
No EOL
6.6 KiB
Markdown
---
|
||
name: woocommerce-markdown
|
||
description: 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 撰写指南
|
||
|
||
### 标题
|
||
|
||
```markdown
|
||
# 主标题 (H1) - 每个文件仅一个
|
||
|
||
## 部分 (H2)
|
||
|
||
### 子部分 (H3)
|
||
|
||
#### 次要部分 (H4)
|
||
```
|
||
|
||
- 使用 ATX 风格 (`#`) 而非下划线风格
|
||
- 每个文件一个 H1 标题（通常是标题）
|
||
- 保持标题层次结构（不要跳过级别）
|
||
|
||
### 列表
|
||
|
||
**无序列表：**
|
||
|
||
```markdown
|
||
- 项目一
|
||
- 项目二
|
||
- 嵌套项目（4个空格）
|
||
- 另一个嵌套项目
|
||
- 项目三
|
||
```
|
||
|
||
**有序列表：**
|
||
|
||
```markdown
|
||
1. 第一项
|
||
2. 第二项
|
||
3. 第三项
|
||
```
|
||
|
||
**重要：**
|
||
|
||
- 嵌套列表项目使用 4 个空格
|
||
- 在列表前后添加空白行
|
||
- 无序列表使用 `-`（而非 `*` 或 `+`）
|
||
|
||
### 代码块
|
||
|
||
**始终指定语言：**
|
||
|
||
````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 示例
|
||
|
||
**代码块规则：**
|
||
|
||
- 在起始围栏前添加空行
|
||
- 在结束围栏后添加空行
|
||
- 始终指定语言（切勿使用普通的 ` ``` `）
|
||
|
||
### 内联代码
|
||
|
||
对内联代码使用反引号：
|
||
|
||
```markdown
|
||
使用 `process_order()` 方法来处理订单。
|
||
`$order_id` 参数必须是整数。
|
||
```
|
||
|
||
### 链接
|
||
|
||
```markdown
|
||
[链接文本](https://example.com)
|
||
|
||
[内部链接](.ai/skills/woocommerce-markdown/path/to/file)
|
||
|
||
[带标题的链接](https://example.com "可选标题")
|
||
```
|
||
|
||
### 表格
|
||
|
||
```markdown
|
||
| 列 1 | 列 2 | 列 3 |
|
||
|----------|----------|----------|
|
||
| 值 1 | 值 2 | 值 3 |
|
||
| 值 4 | 值 5 | 值 6 |
|
||
```
|
||
|
||
- 使用管道符 (`|`) 作为列分隔符
|
||
- 必须包含标题分隔行
|
||
- 对齐方式可选 (`:---`, `:---:`, `---:`)
|
||
|
||
### 目录树
|
||
|
||
**始终使用 UTF-8 制表符字符：**
|
||
|
||
```markdown
|
||
src/
|
||
├── Internal/
|
||
│ ├── Admin/
|
||
│ │ └── Controller.php
|
||
│ └── Utils/
|
||
│ └── Helper.php
|
||
└── External/
|
||
└── API.php
|
||
```
|
||
|
||
**切勿使用：**
|
||
|
||
- ASCII 艺术字符 (`+--`, `|--`)
|
||
- 空格或制表符来表示树结构
|
||
- 控制字符
|
||
|
||
### 强调
|
||
|
||
```markdown
|
||
**粗体文本** 用于强烈强调
|
||
*斜体文本* 用于常规强调
|
||
***粗斜体*** 用于非常强烈的强调
|
||
```
|
||
|
||
## Markdown 编辑工作流
|
||
|
||
1. **进行更改** 到 markdown 文件
|
||
2. **自动修复 linting 问题：**
|
||
|
||
```bash
|
||
markdownlint --fix path/to/file.md
|
||
```
|
||
|
||
3. **检查剩余问题：**
|
||
|
||
```bash
|
||
markdownlint path/to/file.md
|
||
```
|
||
|
||
4. **手动修复** 剩余问题（通常是代码块的语言规范）
|
||
5. **验证清理** - 无输出表示成功
|
||
6. **提交更改**
|
||
|
||
## 常见 Linting 错误及修复
|
||
|
||
### MD007: 列表缩进
|
||
|
||
**问题：**
|
||
|
||
```markdown
|
||
- 项目
|
||
- 嵌套（仅 2 个空格）
|
||
```
|
||
|
||
**修复：**
|
||
|
||
```markdown
|
||
- 项目
|
||
- 嵌套（4 个空格）
|
||
```
|
||
|
||
### MD031: 代码块需要空行
|
||
|
||
**问题：**
|
||
|
||
````markdown
|
||
一些文本
|
||
```bash
|
||
命令
|
||
```
|
||
更多文本
|
||
````
|
||
|
||
**修复：**
|
||
|
||
````markdown
|
||
一些文本
|
||
|
||
```bash
|
||
命令
|
||
```
|
||
|
||
更多文本
|
||
````
|
||
|
||
### MD032: 列表需要空行
|
||
|
||
**问题：**
|
||
|
||
````markdown
|
||
一些文本
|
||
- 列表项目
|
||
````
|
||
|
||
**修复：**
|
||
|
||
````markdown
|
||
一些文本
|
||
|
||
- 列表项目
|
||
````
|
||
|
||
### MD036: 强调作为标题
|
||
|
||
**问题：**
|
||
|
||
```markdown
|
||
**示例：使用粗体作为标题**
|
||
|
||
此处是一些内容
|
||
```
|
||
|
||
**修复：**
|
||
|
||
```markdown
|
||
|
||
#### 示例：使用正确的标题
|
||
|
||
此处有一些内容
|
||
```
|
||
|
||
### MD040：代码需要指定语言
|
||
|
||
**问题：**
|
||
|
||
````markdown
|
||
```
|
||
此处是代码
|
||
```
|
||
````
|
||
|
||
**修复：**
|
||
|
||
````markdown
|
||
```bash
|
||
此处是代码
|
||
```
|
||
````
|
||
|
||
## 特殊情况
|
||
|
||
### CLAUDE.md 文件
|
||
|
||
CLAUDE.md 文件是 AI 助手文档：
|
||
|
||
- 必须格式良好，以便 AI 进行最佳解析
|
||
- 严格遵守所有 markdownlint 规则
|
||
- 使用清晰、层次化的结构
|
||
- 对于长文件，包含目录
|
||
|
||
### README 文件
|
||
|
||
- 以 H1 标题开始
|
||
- 包含简要描述
|
||
- 添加安装/使用部分
|
||
- 保持简洁且易于浏览
|
||
|
||
### 更新日志文件
|
||
|
||
- 遵循 Keep a Changelog 格式
|
||
- 使用一致的日期格式
|
||
- 按类型（新增、更改、修复等）对更改进行分组
|
||
|
||
## 故障排除
|
||
|
||
### 文件显示为 "data" 而非文本
|
||
|
||
**问题：** 文件因控制字符而损坏
|
||
|
||
**修复：**
|
||
|
||
```bash
|
||
tr -d '\000-\037' < file.md > file.clean.md && mv file.clean.md file.md
|
||
file file.md # 验证显示为 "UTF-8 text"
|
||
```
|
||
|
||
### 代码检查显示意外错误
|
||
|
||
**问题：** 未从仓库根目录运行
|
||
|
||
**修复：**
|
||
|
||
```bash
|
||
|
||
# 总是从根目录运行
|
||
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 命令 |
