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

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

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

Ordered lists:

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:

```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:

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

Links

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

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

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

Tables

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

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

Never use:

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

Emphasis

**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:

- Item
  - Nested (only 2 spaces)

Fix:

- Item
    - Nested (4 spaces)

MD031: Code blocks need blank lines

Problem:

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

Fix:

Some text

```bash
command
```

More text

MD032: Lists need blank lines

Problem:

Some text
- List item

Fix:

Some text

- List item

MD036: Emphasis as heading

Problem:

**Example: Using bold as a heading**

Some content here

Fix:

#### Example: Using a proper heading

Some content here

MD040: Code needs language

Problem:

```
code here
```

Fix:

```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:

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:

# 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