---
alwaysApply: true
---

# Markdown Automation System

**Author**: Matthew Raymer
**Date**: 2025-08-20
**Status**: 🎯 **ACTIVE** - Markdown formatting automation

## Overview

The Markdown Automation System ensures your markdown formatting standards are
followed **during content generation** by AI agents, not just applied after the
fact.

## AI-First Approach

### **Primary Method**: AI Agent Compliance

- **AI agents follow markdown rules** while generating content
- **No post-generation fixes needed** - content is compliant from creation
- **Consistent formatting** across all generated documentation

### **Secondary Method**: Automated Validation

- **Pre-commit hooks** catch any remaining issues
- **GitHub Actions** validate formatting before merge
- **Manual tools** for bulk fixes when needed

## How It Works

### 1. **AI Agent Compliance** (Primary)

- **When**: Every time AI generates markdown content
- **What**: AI follows markdown rules during generation
- **Result**: Content is properly formatted from creation

### 2. **Pre-commit Hooks** (Backup)

- **When**: Every time you commit
- **What**: Catches any remaining formatting issues
- **Result**: Clean, properly formatted markdown files

### 3. **GitHub Actions** (Pre-merge)

- **When**: Every pull request
- **What**: Validates markdown formatting across all files
- **Result**: Blocks merge if formatting issues exist

## AI Agent Rules Integration

The AI agent follows markdown rules defined in `.cursor/rules/docs/markdown.mdc`:

- **alwaysApply: true** - Rules are enforced during generation
- **Line Length**: AI never generates lines > 80 characters
- **Blank Lines**: AI adds proper spacing around all elements
- **Structure**: AI uses established templates and patterns

## Available Commands

### NPM Scripts

- **`npm run markdown:setup`** - Install the automation system
- **`npm run markdown:fix`** - Fix formatting in all markdown files
- **`npm run markdown:check`** - Validate formatting without fixing

## 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

---

**Status**: Active automation system
**Priority**: High
**Maintainer**: Development team
**Next Review**: 2025-09-20