Markdown documentation standards for LLM and Pandoc PDF. TRIGGERS - markdown standards, section numbering, documentation style.
Standards for writing markdown documentation optimized for both LLM consumption and conversion to professional PDFs using Pandoc. Ensures consistency across all documentation.
Use when:
Machine-Readable Priority: OpenAPI 3.1.0 specs, JSON Schema, YAML specifications take precedence over human documentation.
Why: Structured formats provide unambiguous contracts that both humans and LLMs can consume reliably. Human docs supplement, don't replace, machine-readable specs.
Application:
Pattern: Central hubs (like CLAUDE.md, INDEX.md) link to detailed spokes (skills, docs directories).
Structure:
CLAUDE.md (Hub - Essentials Only)
↓ links to
Skills (Spokes - Progressive Disclosure)
├── SKILL.md (Overview + Quick Start)
└── references/ (Detailed Documentation)
Rules:
Critical Rule: Never manually number markdown headings.
❌ Wrong:
## 1. Introduction
### 1.1 Background
### 1.2 Objectives
## 2. Implementation
✅ Correct:
## Introduction
### Background
### Objectives
## Implementation
Rationale:
--number-sections flag auto-numbers all sections when generating PDFsRule: If markdown might ever convert to PDF, never manually number headings. Use semantic heading levels (##, ###) and let tools handle numbering.
Use this checklist when creating or reviewing documentation:
[text](url), not bare URLsHub (CLAUDE.md):
## PDF Generation from Markdown
**Quick Start**: Use pandoc-pdf-generation skill
**Critical Rules**:
1. Never write ad-hoc pandoc commands
2. Always verify PDFs before presenting
3. See skill for detailed principles
Spoke (skill/SKILL.md):
Workflow Specification (specifications/hook-prompt-capture.yaml):