Guidelines for creating and modifying markdown files in WooCommerce. Use when writing documentation, README files, or any markdown content.
This skill provides guidance for creating and editing markdown files in the WooCommerce project.
markdownlint --fix then markdownlint to verify.markdownlint.json config is loadedThe project uses markdownlint with these specific rules (from .markdownlint.json):
# Heading not )Heading\n===# Main Title (H1) - Only one per file
## Section (H2)
### Subsection (H3)
#### Minor Section (H4)
#) not underline styleUnordered 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:
- for unordered lists (not * or +)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 commandsphp - PHP codejavascript or js - JavaScripttypescript or ts - TypeScriptjson - JSON datasql - SQL queriesmarkdown or md - Markdown examplesCode block rules:
```)Use backticks for inline code:
Use the `process_order()` method to handle orders.
The `$order_id` parameter must be an integer.
[Link text](https://example.com)
[Internal link](../path/to/file.md)
[Link with title](https://example.com "Optional title")
| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Value 1 | Value 2 | Value 3 |
| Value 4 | Value 5 | Value 6 |
|) for column separators:---, :---:, ---:)Always use UTF-8 box-drawing characters:
src/
├── Internal/
│ ├── Admin/
│ │ └── Controller.php
│ └── Utils/
│ └── Helper.php
└── External/
└── API.php
Never use:
+--, |--)**Bold text** for strong emphasis
*Italic text* for regular emphasis
***Bold and italic*** for very strong emphasis
Make your changes to the markdown file
Auto-fix linting issues:
markdownlint --fix path/to/file.md
Check for remaining issues:
markdownlint path/to/file.md
Manually fix what remains (usually language specs for code blocks)
Verify clean - No output means success
Commit changes
Problem:
- Item
- Nested (only 2 spaces)
Fix:
- Item
- Nested (4 spaces)
Problem:
Some text
```bash
command
```
More text
Fix:
Some text
```bash
command
```
More text
Problem:
Some text
- List item
Fix:
Some text
- List item
Problem:
**Example: Using bold as a heading**
Some content here
Fix:
#### Example: Using a proper heading
Some content here
Problem:
```
code here
```
Fix:
```bash
code here
```
CLAUDE.md files are AI assistant documentation:
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"
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
Problem: Some issues require manual intervention
Fix:
markdownlint --fixwoocommerce-dev-cycle skill for markdown linting commands