Back to Details

markdown-writing

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

markdown-writing Guidelines

Markdown写作指南

This skill provides guidance for creating and editing markdown files.
本指南为创建和编辑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
command
```
更多文本
修复：
markdown
一些文本

```bash
command
```

更多文本

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
```
code here
```
修复：
markdown
```bash
code here
```

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最佳解析
  • 有关markdownlint命令，请参阅 
    woocommerce-dev-cycle
    相关指南