crowd-funder-from-jason/.cursor/rules/docs/markdown_core.mdc

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

**Primary Focus**: Create educational content that increases human
competence, not just technical descriptions.

## 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
5. **Educational Value**: Focus on increasing reader competence and
   understanding

### **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
- ❌ Focus only on technical details without educational context
- ❌ Assume reader has extensive prior knowledge

### **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
- ✅ Explain concepts before implementation details
- ✅ Provide context and motivation for technical choices
- ✅ Include examples that illustrate key concepts

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

## Educational Content Standards

### **Content Structure for Learning**

- **Concept First**: Explain what something is before how to use it
- **Context Matters**: Explain why and when to use a feature
- **Progressive Disclosure**: Start simple, add complexity gradually
- **Real Examples**: Use concrete, relatable scenarios
- **Common Questions**: Anticipate and answer reader questions

### **Writing for Understanding**

- **Conversational Tone**: Write as if explaining to a colleague
- **Active Voice**: "You can do this" not "This can be done"
- **Question Format**: "What happens when..." to engage thinking
- **Analogies**: Use familiar concepts to explain complex ideas
- **Limitations**: Clearly state what solutions don't do

## 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
- [ ] **Educational Focus**: Plan content structure for learning progression
- [ ] **Audience Consideration**: Identify target reader knowledge level

### 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
- [ ] **Educational Review**: Verify content increases reader competence
- [ ] **Example Validation**: Ensure examples illustrate key concepts clearly

### 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
- [ ] **Educational Value**: Content increases reader understanding and competence
- [ ] **Context Clarity**: Reader understands when and why to use the information

---

**See also**:

- `.cursor/rules/meta_documentation.mdc` for comprehensive documentation workflow
- `.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