poocommerce-markdown

name	poocommerce-markdown
description	Guidelines for creating and modifying markdown files in PooCommerce. Use when writing documentation, README files, or any markdown content.

PooCommerce Markdown Guidelines

This skill provides guidance for creating and editing markdown files in the PooCommerce 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 PooCommerce markdown standards - See configuration rules below

PooCommerce 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 a h1, h2, h3, br, summary, details and video elements
• 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:

   markdownlint --fix path/to/file.md
   

3. Check for remaining issues:

   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/poocommerce
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 poocommerce-dev-cycle skill for markdown linting commands