# Markdown Core Standards & Automation

**Author**: Matthew Raymer
**Date**: 2025-08-21
**Status**: 🎯 **ACTIVE** - Core markdown standards and automation

## Overview

This file combines core markdown formatting standards with automation
guidelines. AI agents must follow these rules DURING content generation,
not apply them after the fact.

## AI Generation Guidelines

### **MANDATORY**: Follow These Rules While Writing

When generating markdown content, you MUST:

1. **Line Length**: Never exceed 80 characters per line
2. **Blank Lines**: Always add blank lines around headings, lists, and
   code blocks
3. **Structure**: Use proper heading hierarchy and document templates
4. **Formatting**: Apply consistent formatting patterns immediately

### **DO NOT**: Generate content that violates these rules

- ❌ Generate long lines that need breaking
- ❌ Create content without proper blank line spacing
- ❌ Use inconsistent formatting patterns
- ❌ Assume post-processing will fix violations

### **DO**: Generate compliant content from the start

- ✅ Write within 80-character limits
- ✅ Add blank lines around all structural elements
- ✅ Use established templates and patterns
- ✅ Apply formatting standards immediately

## Core Formatting Standards

### Line Length

- **Maximum line length**: 80 characters
- **Exception**: Code blocks (JSON, shell, TypeScript, etc.) - no line
  length enforcement
- **Rationale**: Ensures readability across different screen sizes and
  terminal widths

### Blank Lines

- **Headings**: Must be surrounded by blank lines above and below
- **Lists**: Must be surrounded by blank lines above and below
- **Code blocks**: Must be surrounded by blank lines above and below
- **Maximum consecutive blank lines**: 1 (no multiple blank lines)
- **File start**: No blank lines at the beginning of the file
- **File end**: Single newline character at the end

### Whitespace

- **No trailing spaces**: Remove all trailing whitespace from lines
- **No tabs**: Use spaces for indentation
- **Consistent indentation**: 2 spaces for list items and nested content

## Heading Standards

### Format

- **Style**: ATX-style headings (`#`, `##`, `###`, etc.)
- **Case**: Title case for general headings
- **Code references**: Use backticks for file names and technical terms
  - ✅ `### Current package.json Scripts`
  - ❌ `### Current Package.json Scripts`

### Hierarchy

- **H1 (#)**: Document title only
- **H2 (##)**: Major sections
- **H3 (###)**: Subsections
- **H4 (####)**: Sub-subsections
- **H5+**: Avoid deeper nesting

## List Standards

### Unordered Lists

- **Marker**: Use `-` (hyphen) consistently
- **Indentation**: 2 spaces for nested items
- **Blank lines**: Surround lists with blank lines

### Ordered Lists

- **Format**: `1.`, `2.`, `3.` (sequential numbering)
- **Indentation**: 2 spaces for nested items
- **Blank lines**: Surround lists with blank lines

### Task Lists

- **Format**: `- [ ]` for incomplete, `- [x]` for complete
- **Indentation**: 2 spaces for nested items
- **Blank lines**: Surround lists with blank lines

## Code Block Standards

### Inline Code

- **Format**: Single backticks for inline code
- **Use cases**: File names, commands, variables, technical terms
- **Examples**: `package.json`, `npm run build`, `VITE_PLATFORM`

### Code Blocks

- **Format**: Triple backticks with language specification
- **Language**: Always specify the language for syntax highlighting
- **Blank lines**: Surround with blank lines above and below

## Automation System

### Available Commands

- **`npm run markdown:fix`** - Fix formatting in all markdown files
  using markdownlint-cli2 --fix
- **`npm run markdown:check`** - Validate formatting without fixing
  using markdownlint-cli2

### How It Works

1. **AI Agent Compliance** (Primary): AI follows markdown rules during
   generation
2. **Pre-commit Hooks** (Backup): Catches any remaining formatting
   issues
3. **GitHub Actions** (Pre-merge): Validates formatting before merge

### Benefits

- **No more manual fixes** - AI generates compliant content from start
- **Consistent style** - All files follow same standards
- **Faster development** - No need to fix formatting manually

## Model Implementation Checklist

### Before Generating Markdown Content

- [ ] **Line Length**: Ensure no line exceeds 80 characters
- [ ] **Blank Lines**: Add blank lines around headings, lists, and code blocks
- [ ] **Whitespace**: Remove all trailing spaces, use 2-space indentation
- [ ] **Headings**: Use ATX-style with proper hierarchy (H1 for title only)
- [ ] **Lists**: Use consistent markers (- for unordered, 1. for ordered)
- [ ] **Code**: Specify language for fenced blocks, use backticks for inline

### After Generating Markdown Content

- [ ] **Validation**: Run `npm run markdown:check` to verify compliance
- [ ] **Auto-fix**: Use `npm run markdown:fix` if any issues found
- [ ] **Review**: Confirm content follows established templates and patterns
- [ ] **Cross-reference**: Link to related documentation and templates

### Quality Assurance

- [ ] **Readability**: Content is clear and follows project conventions
- [ ] **Consistency**: Formatting matches existing documentation style
- [ ] **Completeness**: All required sections and information included
- [ ] **Accuracy**: Technical details are correct and up-to-date

---

**See also**:

- `.cursor/rules/docs/markdown_templates.mdc` for document templates
- `.cursor/rules/docs/markdown_workflow.mdc` for validation workflows

**Status**: Active core standards and automation
**Priority**: High
**Estimated Effort**: Ongoing reference
**Dependencies**: None
**Stakeholders**: Documentation team, Development team