---
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 Guidelines

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

## 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

## WooCommerce Markdown Configuration

The project uses markdownlint with these specific rules (from `.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

### Disabled Rules

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

## Markdown Writing Guidelines

### Headings

```markdown
# Main Title (H1) - Only one per file

## Section (H2)

### Subsection (H3)

#### Minor Section (H4)
```

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

### 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 `+`)

### 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 ` ``` `)

### Inline Code

Use backticks for inline code:

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

### Links

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

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

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

### 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 (`:---`, `:---:`, `---:`)

### 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

### Emphasis

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

## Workflow for Editing 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**

## Common Linting Errors and Fixes

### MD007: List indentation

**Problem:**

```markdown
- Item
  - Nested (only 2 spaces)
```

**Fix:**

```markdown
- Item
    - Nested (4 spaces)
```

### MD031: Code blocks need blank lines

**Problem:**

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

**Fix:**

````markdown
Some text

```bash
command
```

More text
````

### MD032: Lists need blank lines

**Problem:**

````markdown
Some text
- List item
````

**Fix:**

````markdown
Some text

- List item
````

### MD036: Emphasis as heading

**Problem:**

```markdown
**Example: Using bold as a heading**

Some content here
```

**Fix:**

```markdown
#### Example: Using a proper heading

Some content here
```

### MD040: Code needs language

**Problem:**

````markdown
```
code here
```
````

**Fix:**

````markdown
```bash
code here
```
````

## Special Cases

### CLAUDE.md Files

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

### README Files

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

### Changelog Files

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

## 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"
```

### Linting Shows Unexpected Errors

**Problem:** Not running from repository root

**Fix:**

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

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

### 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