# Cursor Markdown Ruleset for TimeSafari Documentation

## Overview

This ruleset enforces consistent markdown formatting standards across all project
documentation, ensuring readability, maintainability, and compliance with
markdownlint best practices. **LLMs must follow these rules strictly to generate
lint-free documentation.**

## General 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
- **LLM Guidance**: Always count characters and break lines at 80 characters
  unless in code blocks

### 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
- **LLM Guidance**: Always add blank lines around structural elements

### 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
- **LLM Guidance**: Use space characters only, never tabs

## 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`
- **LLM Guidance**: Always use ATX style, never use Setext style (`===` or `---`)

### Hierarchy

- **H1 (#)**: Document title only - **ONE PER DOCUMENT**
- **H2 (##)**: Major sections
- **H3 (###)**: Subsections
- **H4 (####)**: Sub-subsections
- **H5+**: Avoid deeper nesting
- **LLM Guidance**: Start every document with exactly one H1, maintain logical
  hierarchy

### Heading Content Rules

- **No trailing punctuation**: Avoid periods, colons, etc. at end
- **No duplicate headings**: Each heading must be unique within the document
- **Descriptive but concise**: Headings should clearly describe the section
- **LLM Guidance**: Use action-oriented headings, avoid generic terms like
  "Overview"

## List Standards

### Unordered Lists

- **Marker**: Use `-` (hyphen) consistently
- **Indentation**: 2 spaces for nested items
- **Blank lines**: Surround lists with blank lines
- **LLM Guidance**: Always use hyphens, never use asterisks or plus signs

### Ordered Lists

- **Format**: `1.`, `2.`, `3.` (sequential numbering)
- **Indentation**: 2 spaces for nested items
- **Blank lines**: Surround lists with blank lines
- **LLM Guidance**: Use sequential numbers, never skip numbers or use random
  numbers

### Task Lists

- **Format**: `- [ ]` for incomplete, `- [x]` for complete
- **Use case**: Project planning, checklists, implementation tracking
- **LLM Guidance**: Use consistent spacing in brackets `[ ]` not `[ ]`

## Code Block Standards

### Fenced Code Blocks

- **Syntax**: Triple backticks with language specification
- **Languages**: `json`, `bash`, `typescript`, `javascript`, `yaml`, `markdown`
- **Blank lines**: Must be surrounded by blank lines above and below
- **Line length**: No enforcement within code blocks
- **LLM Guidance**: Always specify language, never use generic code blocks

### Inline Code

- **Format**: Single backticks for inline code references
- **Use case**: File names, commands, variables, properties
- **LLM Guidance**: Use backticks for any technical term, file path, or command

## Special Content Standards

### JSON Examples

```json
{
  "property": "value",
  "nested": {
    "property": "value"
  }
}
```

### Shell Commands

```bash
# Command with comment
npm run build:web

# Multi-line command
VITE_GIT_HASH=`git log -1 --pretty=format:%h` \
  vite build --config vite.config.web.mts
```

### TypeScript Examples

```typescript
// Function with JSDoc
/**
 * Get environment configuration
 * @param env - Environment name
 * @returns Environment config object
 */
const getEnvironmentConfig = (env: string) => {
  switch (env) {
    case 'prod':
      return { /* production settings */ };
    default:
      return { /* development settings */ };
  }
};
```

## File Structure Standards

### Document Header

```markdown
# Document Title

**Author**: Matthew Raymer
**Date**: YYYY-MM-DD
**Status**: 🎯 **STATUS** - Brief description

## Overview

Brief description of the document's purpose and scope.
```

### Section Organization

1. **Overview/Introduction**
2. **Current State Analysis**
3. **Implementation Plan**
4. **Technical Details**
5. **Testing & Validation**
6. **Next Steps**

## Enhanced Markdownlint Configuration

### Required Rules (Comprehensive)

```json
{
  "MD013": { "code_blocks": false, "line_length": 80 },
  "MD012": true,
  "MD022": true,
  "MD031": true,
  "MD032": true,
  "MD047": true,
  "MD009": true,
  "MD024": true,
  "MD025": true,
  "MD026": { "punctuation": ".,;:!" },
  "MD029": { "style": "ordered" },
  "MD030": { "ul_single": 1, "ol_single": 1, "ul_multi": 1, "ol_multi": 1 },
  "MD033": false,
  "MD041": true,
  "MD046": { "style": "fenced" },
  "MD018": true,
  "MD019": true,
  "MD020": true,
  "MD021": true,
  "MD023": true,
  "MD027": true,
  "MD028": true,
  "MD036": true,
  "MD037": true,
  "MD038": true,
  "MD039": true,
  "MD040": true,
  "MD042": true,
  "MD043": true,
  "MD044": true,
  "MD045": true
}
```

### Rule Explanations (LLM Must Follow)

- **MD013**: Line length (80 chars max, disabled for code blocks)
- **MD012**: No multiple consecutive blank lines
- **MD022**: Headings must be surrounded by blank lines
- **MD031**: Fenced code blocks must be surrounded by blank lines
- **MD032**: Lists must be surrounded by blank lines
- **MD047**: Files must end with single newline
- **MD009**: No trailing spaces
- **MD024**: No duplicate headings
- **MD025**: Only one H1 per document
- **MD026**: No trailing punctuation in headings
- **MD029**: Ordered list item prefix style
- **MD030**: List item marker styles
- **MD033**: Allow inline HTML (disabled for flexibility)
- **MD041**: First line must be top-level heading
- **MD046**: Code block style (fenced only)
- **MD018**: Heading should have space after hash
- **MD019**: Heading should have space after hash
- **MD020**: Heading should have space after hash
- **MD021**: Heading should have space after hash
- **MD023**: Heading should start at beginning of line
- **MD027**: No multiple spaces after blockquote marker
- **MD028**: No blank line inside blockquote
- **MD036**: No emphasis used for headings
- **MD037**: No spaces inside emphasis markers
- **MD038**: No spaces inside code span markers
- **MD039**: No spaces inside link text
- **MD040**: Fenced code blocks should have language specified
- **MD042**: No empty links
- **MD043**: Required heading structure
- **MD044**: Line length in code blocks
- **MD045**: No images without alt text

## LLM-Specific Language Guidelines

### **CRITICAL: LLM Must Follow These Rules**

#### 1. **Heading Generation**

- **Always start with H1**: Every document must have exactly one
  `# Document Title`
- **Use descriptive headings**: Avoid generic terms like "Overview",
  "Details", "Information"
- **Maintain hierarchy**: H2 for major sections, H3 for subsections
- **No duplicate headings**: Each heading must be unique within the document

#### 2. **List Formatting**

- **Unordered lists**: Always use `-` (hyphen), never `*` or `+`
- **Ordered lists**: Use sequential numbers `1.`, `2.`, `3.`
- **Consistent spacing**: Always use 2 spaces for indentation
- **Blank lines**: Surround all lists with blank lines

#### 3. **Code and Technical Content**

- **Inline code**: Use backticks for any technical term, file path, or command
- **Code blocks**: Always specify language, never use generic blocks
- **File references**: Always use backticks for file names and paths

#### 4. **Line Length Management**

- **Count characters**: Ensure no line exceeds 80 characters
- **Break naturally**: Break at word boundaries when possible
- **Code blocks**: No line length enforcement within code blocks

#### 5. **Whitespace Rules**

- **No trailing spaces**: Never leave spaces at end of lines
- **No tabs**: Use spaces only for indentation
- **Blank lines**: Use exactly one blank line between sections

## Enhanced Validation Commands

### Check Single File

```bash
npx markdownlint docs/filename.md
```

### Check All Documentation

```bash
npx markdownlint docs/
```

### Check with Custom Config

```bash
npx markdownlint --config .markdownlint.json docs/
```

### Generate Detailed Report

```bash
npx markdownlint --config .markdownlint.json --output markdownlint-report.txt docs/
```

### Check Specific Rules

```bash
npx markdownlint --rules MD013,MD012,MD022,MD024,MD025 docs/
```

### Project-Wide Validation

```bash
# Check all markdown files in project
find . -name "*.md" -exec npx markdownlint {} \;

# Check specific directories
npx markdownlint .cursor/rules/ docs/ README.md

# Check with verbose output
npx markdownlint --verbose docs/
```

### Auto-fix Common Issues

```bash
# Remove trailing spaces
sed -i 's/[[:space:]]*$//' docs/filename.md

# Remove multiple blank lines
sed -i '/^$/N;/^\n$/D' docs/filename.md

# Add newline at end if missing
echo "" >> docs/filename.md

# Fix heading spacing
sed -i 's/^# /# /g' docs/filename.md
```

## Common Patterns

### Implementation Plans

```markdown
## Implementation Plan

### Phase 1: Foundation

#### 1.1 Component Setup

- [ ] Create new component file
- [ ] Add basic structure
- [ ] Implement core functionality

#### 1.2 Configuration

- [ ] Update configuration files
- [ ] Add environment variables
- [ ] Test configuration loading
```

### Status Tracking

```markdown
**Status**: ✅ **COMPLETE** - All phases finished
**Progress**: 75% (15/20 components)
**Next**: Ready for testing phase
```

### Performance Metrics

```markdown
#### 📊 Performance Metrics
- **Build Time**: 2.3 seconds (50% faster than baseline)
- **Bundle Size**: 1.2MB (30% reduction)
- **Success Rate**: 100% (no failures in 50 builds)
```

## Enforcement

### Pre-commit Hooks

```bash
#!/bin/bash
# .git/hooks/pre-commit
# Check markdown files before commit

echo "Running markdownlint..."

# Get list of staged markdown files
staged_md_files=$(git diff --cached --name-only --diff-filter=ACM | grep '\.md$')

if [ -n "$staged_md_files" ]; then
  echo "Checking markdown files: $staged_md_files"
  
  # Run markdownlint on staged files
  npx markdownlint $staged_md_files
  
  if [ $? -ne 0 ]; then
    echo "❌ Markdown linting failed. Please fix issues before committing."
    exit 1
  fi
  
  echo "✅ Markdown linting passed."
fi
```

### CI/CD Integration

```yaml
# .github/workflows/markdown-lint.yml
name: Markdown Lint

on:
  push:
    paths: ['**/*.md']
  pull_request:
    paths: ['**/*.md']

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'
          
      - name: Install markdownlint
        run: npm install -g markdownlint-cli
        
      - name: Run markdownlint
        run: markdownlint --config .markdownlint.json .
        
      - name: Generate report
        run: markdownlint --config .markdownlint.json --output lint-report.txt .
        
      - name: Upload report
        uses: actions/upload-artifact@v3
        with:
          name: markdown-lint-report
          path: lint-report.txt
```

### Team Guidelines

- All documentation PRs must pass markdownlint
- Use provided templates for new documents
- Follow established patterns for consistency
- **LLM-generated content must pass all linting rules**

## Templates

### New Document Template

```markdown
# Document Title

**Author**: Matthew Raymer
**Date**: YYYY-MM-DD
**Status**: 🎯 **PLANNING** - Ready for Implementation

## Overview

Brief description of the document's purpose and scope.

## Current State

Description of current situation or problem.

## Implementation Plan

### Phase 1: Foundation

- [ ] Task 1
- [ ] Task 2

## Next Steps

1. **Review and approve plan**
2. **Begin implementation**
3. **Test and validate**

---

**Status**: Ready for implementation
**Priority**: Medium
**Estimated Effort**: X days
**Dependencies**: None
**Stakeholders**: Development team
```

### Rule File Template

```markdown
# Rule Name

**Purpose**: Brief description of what this rule accomplishes

## Overview

Detailed explanation of the rule's scope and importance.

## Implementation

### Requirements

- [ ] Requirement 1
- [ ] Requirement 2

### Examples

#### ✅ Good Example

```markdown
# Good example content
```

#### ❌ Bad Example

```markdown
# Bad example content
```

## Validation

How to test that this rule is working correctly.

---

**Status**: Active
**Version**: 1.0
**Maintainer**: Matthew Raymer

## LLM Quality Assurance Checklist

### **Before Generating Documentation, LLM Must:**

- [ ] **Understand line length**: No line over 80 characters
- [ ] **Plan heading structure**: One H1, logical hierarchy, no duplicates
- [ ] **Choose list markers**: Hyphens for unordered, sequential numbers for ordered
- [ ] **Plan code blocks**: Specify languages, add blank lines around
- [ ] **Check whitespace**: No trailing spaces, consistent indentation
- [ ] **Validate structure**: Proper blank line placement

### **After Generating Documentation, LLM Must:**

- [ ] **Verify line lengths**: Count characters, break long lines
- [ ] **Check heading hierarchy**: Ensure logical structure
- [ ] **Validate lists**: Consistent markers and spacing
- [ ] **Review code blocks**: Proper language specification
- [ ] **Clean whitespace**: Remove trailing spaces, add proper blank lines
- [ ] **Test with markdownlint**: Ensure all rules pass

---

**Last Updated**: 2025-08-17
**Version**: 2.0
**Maintainer**: Matthew Raymer
**LLM Compliance**: Required for all documentation generation