Markdown Style Guide - Project Conventions

This project uses markdownlint to enforce consistent markdown formatting. This guide summarizes the configured rules and provides examples to help you write compliant markdown from the start.

When to Reference This Guide

ALWAYS read this instruction before:

• Creating new .md files (READMEs, documentation, agents, etc.)
• Making significant edits to existing .md files
• Writing YAML frontmatter blocks in markdown files

Critical Rules (Most Common Violations)

1. MD036: No Emphasis as Heading

Rule: Don't use bold/italic text as a heading substitute.

❌ Incorrect:

**Step 1: Configure the database**

This is the first step...

✅ Correct:

#### Step 1: Configure the database

This is the first step...

Why: Screen readers and markdown parsers can't identify emphasized text as headings.

---

2. MD040: Fenced Code Language

Rule: All fenced code blocks MUST specify a language.

❌ Incorrect:

Install dependencies:

\```
npm install
\```

✅ Correct:

Install dependencies:

\```bash
npm install
\```

Common language tags:

• bash / sh - Shell commands
• javascript / js - JavaScript
• typescript / ts - TypeScript
• python / py - Python
• yaml / yml - YAML configuration
• json - JSON data
• text - Plain text, pseudo-code, or output
• markdown / md - Markdown examples
• mermaid - Mermaid diagrams

Special cases:

• Use text when showing command output or non-executable content
• Use text for pseudo-code that isn't a real language
• Use bash for multi-line shell commands even if some aren't bash-specific

---

3. MD060: Table Column Style

Rule: Table pipes must have spaces on both sides.

❌ Incorrect:

| Column1 | Column2 | Column3 |
| ------- | ------- | ------- |
| Value1  | Value2  | Value3  |

✅ Correct:

| Column1 | Column2 | Column3 |
| ------- | ------- | ------- |
| Value1  | Value2  | Value3  |

Tip: Let markdownlint handle table formatting - it will check proper spacing automatically.

---

4. MD029: Ordered List Prefix

Rule: Ordered lists should use sequential numbering (1, 2, 3) not all 1s.

❌ Incorrect:

1. First item
1. Second item
1. Third item

✅ Correct:

1. First item
2. Second item
3. Third item

Exception: Some markdown engines render 1. style correctly, but our linter requires sequential.

---

5. MD046: Code Block Style (Fenced)

Rule: Use fenced code blocks (```) not indented code blocks.

❌ Incorrect:

Example code:

    function hello() {
      console.log("Hello");
    }

✅ Correct:

Example code:

\```javascript
function hello() {
console.log("Hello");
}
\```

---

Project-Specific Configuration

Our .markdownlint.json configuration:

{
  "default": true,
  "MD013": false,
  "MD033": {
    "allowed_elements": ["br", "details", "summary", "kbd"]
  },
  "MD041": false
}

What this means:

• MD013 disabled: No line length limit (can exceed 80 chars)
• MD033 allowed HTML: Can use <br>, <details>, <summary>, <kbd> tags
• MD041 disabled: First line doesn't need to be H1 (allows frontmatter)

---

Heading Structure

Rule: Proper Hierarchy

Headings should follow a logical hierarchy without skipping levels.

❌ Incorrect:

# Main Title

### Subsection (skipped H2)

##### Detail (skipped H3 and H4)

✅ Correct:

# Main Title

## Section

### Subsection

#### Detail

Rule: Unique Headings

Avoid duplicate heading text in the same document (causes anchor conflicts).

❌ Incorrect:

## Installation

Instructions for Linux...

## Installation

Instructions for macOS...

✅ Correct:

## Installation on Linux

Instructions...

## Installation on macOS

Instructions...

---

Lists and Formatting

Unordered Lists

Use consistent markers (prefer - for this project):

✅ Correct:

- Item 1
- Item 2
  - Nested item
  - Another nested
- Item 3

Task Lists

- [x] Completed task
- [ ] Pending task
- [ ] Another pending task

Nested Lists

Indent nested lists with 2 spaces:

- Parent item
  - Child item (2 spaces)
    - Grandchild (4 spaces)

---

Links and References

Inline Links

✅ Correct:

See the [documentation](https://example.com/docs) for details.

Reference-Style Links

✅ Correct:

Check out [Claude Code][claude] and [Serena][serena].

[claude]: https://claude.ai/code
[serena]: https://github.com/ceorkm/serena

Relative Links

✅ Correct:

See [Installation Guide](./docs/installation.md) for setup instructions.

---

YAML Frontmatter

Structure

Frontmatter MUST:

• Start with --- on line 1
• End with --- on its own line
• Use valid YAML syntax
• Include all required fields for asset type

✅ Correct:

---
version: '1.0.0'
kind: prompt
id: example-prompt
title: Example Prompt
description: A clear description
owner: username
lifecycle_status: active
last_reviewed: '2025-01-20'
tags:
  - example
  - demo
---

# Content starts here

Common Frontmatter Mistakes

❌ Incorrect:

---
version: 1.0.0 # Missing quotes for version
tags: example, demo # Should be YAML array
last_reviewed: 2025-01-20 # Should be quoted string
---

✅ Correct:

---
version: '1.0.0' # Quoted semver
tags: # YAML array
  - example
  - demo
last_reviewed: '2025-01-20' # Quoted ISO date
---

---

Emphasis and Formatting

Bold

Use **text** for bold:

This is **important** information.

Italic

Use *text* or _text_ for italic:

This is _emphasized_ or _emphasized_.

Code

Use backticks for inline code:

Run the `npm install` command to install dependencies.

Strikethrough

Use ~~text~~ for strikethrough:

This is ~~incorrect~~ **correct**.

---

Common Patterns in This Project

Agent Files

Agents have special structure requirements:

---
version: '1.0'
kind: agent
id: example-agent
title: Example Agent
# ... (complete frontmatter)
---

# Agent Title

Brief description.

## Primary Goal

Clear goal statement.

## Your Mission

Numbered list of objectives:

1. First objective
2. Second objective

---

## Core Workflow

### Phase 1: Discovery

#### Step 1: Initial Analysis

Details about step 1.

#### Step 2: Data Collection

Details about step 2.

### Phase 2: Processing

...

Key conventions:

• Use #### (H4) for steps within phases
• Separate major sections with --- (horizontal rule)
• Always specify language for code blocks
• Use text blocks for pseudo-code or non-executable examples

---

README Files

Standard README structure:

# Project Name

Brief one-line description.

## Overview

Detailed description.

## Installation

\```bash
npm install
\```

## Usage

\```javascript
const example = require('example');
\```

## Configuration

\```yaml
config:
key: value
\```

## Contributing

See [CONTRIBUTING.md](./CONTRIBUTING.md).

## License

MIT License.

---

Pre-commit Hook Behavior

Auto-Fix Enabled

The markdownlint pre-commit hook is configured with --fix flag:

- id: markdownlint-cli
  name: markdownlint-cli
  args: ['--fix']

What this means:

• Most formatting issues will be auto-corrected
• Files will be modified in-place
• You'll need to re-stage files after hook runs
• However: Not all issues can be auto-fixed (e.g., MD036, MD040)

Issues That Can't Be Auto-Fixed

These require manual correction:

1. MD036 (Emphasis as heading) - Must manually convert to real heading
2. MD040 (Missing language tag) - Must manually add language to code blocks
3. MD041 (First line should be heading) - Must restructure document
4. MD029 (List numbering) - May need manual reordering

Best practice: Reference this guide BEFORE writing to avoid manual fixes.

---

Failure Modes and Fallbacks

If markdownlint is Not Installed

If markdownlint-cli2 is not available:

Symptoms:

• Pre-commit hook fails with "command not found"
• Manual validation fails

Solution:

# Install globally
npm install -g markdownlint-cli2

# Or install project dependencies
npm install

If Pre-commit Hook Fails

If the hook fails even after auto-fix:

Diagnosis:

# Run markdownlint manually to see unfixable issues
npx markdownlint-cli2 path/to/file.md

# Check which rules failed
npx markdownlint-cli2 --config .markdownlint.json path/to/file.md

Common unfixable issues:

• Bold text used as headings (MD036) → Change **Text** to #### Text
• Missing code language tags (MD040) → Add language after opening backticks
• Wrong heading hierarchy (MD001) → Restructure heading levels

If You Must Bypass the Hook

Use with extreme caution:

# Skip pre-commit hooks (NOT RECOMMENDED)
git commit --no-verify -m "message"

When this is acceptable:

• Emergency hotfix
• Committing intentionally non-compliant markdown (e.g., test fixtures)
• Pre-commit infrastructure is broken

When this is NOT acceptable:

• "I don't want to fix my markdown" - Fix it properly instead

---

Quick Reference Checklist

Before committing markdown files, verify:

• All code blocks have language tags (e.g., ```bash)
• No bold/italic text used as headings (use #### instead)
• Tables have spaces around pipes
• Ordered lists use sequential numbers (1, 2, 3)
• Heading hierarchy is logical (no skipped levels)
• YAML frontmatter is valid and complete
• No trailing whitespace on lines
• File ends with a single newline

---

Tool Integration

VS Code

Install the markdownlint extension:

code --install-extension DavidAnson.vscode-markdownlint

Settings (.vscode/settings.json):

{
  "markdownlint.config": {
    "extends": "./.markdownlint.json"
  },
  "editor.formatOnSave": true,
  "[markdown]": {
    "editor.defaultFormatter": "DavidAnson.vscode-markdownlint"
  }
}

CLI Usage

# Check all markdown files
npx markdownlint-cli2 "**/*.md"

# Auto-fix issues
npx markdownlint-cli2 --fix "**/*.md"

# Check specific file
npx markdownlint-cli2 README.md

# Custom config
npx markdownlint-cli2 --config .markdownlint.json "**/*.md"

---

Examples by File Type

1. Prompt File

---
version: '1.0.0'
kind: prompt
id: k8s-debug
title: Kubernetes Pod Debugging
description: Debug Kubernetes pod issues
owner: platform-team
lifecycle_status: active
last_reviewed: '2025-01-20'
tags:
  - kubernetes
  - debugging
---

# Kubernetes Pod Debugging

You are a Kubernetes expert helping debug pod issues.

## Initial Commands

Run these diagnostic commands:

\```bash
kubectl get pods -n production
kubectl describe pod <pod-name> -n production
kubectl logs <pod-name> -n production --tail=100
\```

## Common Issues

### CrashLoopBackOff

Check logs for errors:

\```bash
kubectl logs <pod-name> -n production --previous
\```

2. Agent File

---
version: '1.0'
kind: claude-agent
id: terraform-validator
title: Terraform Validator
description: Validate Terraform configurations
owner: platform-automation
lifecycle_status: active
last_reviewed: '2025-01-20'
tags:
  - terraform
  - validation
goals:
  - Validate Terraform syntax
  - Check best practices
---

# Terraform Validator Agent

## Core Workflow

### Phase 1: Syntax Validation

#### Step 1: Run terraform validate

Execute validation:

\```bash
terraform init
terraform validate
\```

#### Step 2: Check Formatting

Verify formatting:

\```bash
terraform fmt -check -recursive
\```

3. Documentation File

# Installation Guide

This guide covers installation for all supported platforms.

## Prerequisites

- Node.js 18+
- npm 9+

## Installation Steps

### Linux

Install via package manager:

\```bash
sudo apt update
sudo apt install nodejs npm
\```

Verify installation:

\```bash
node --version
npm --version
\```

### macOS

Install via Homebrew:

\```bash
brew install node
\```

### Windows

Download from [Node.js website](https://nodejs.org/).

## Post-Installation

Configure npm:

\```bash
npm config set registry https://registry.npmjs.org/
\```

---

Related Resources

• markdownlint Rules
• CommonMark Spec
• GitHub Flavored Markdown
• Project .markdownlint.json
• Project Constraints Awareness

---

Summary

Golden Rules:

1. Always specify language tags on code blocks
2. Use real headings, not bold text
3. Let markdownlint handle table formatting
4. Read this guide before creating markdown
5. Trust the auto-fix, but fix what it can't

Following these conventions ensures consistent, accessible, and tool-friendly markdown across the entire project.