crowd-funder-for-time-pwa/.cursor/rules/markdown.mdc

---
globs: *.md
alwaysApply: false
---
# 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.

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

### 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
- **Use case**: Project planning, checklists, implementation tracking

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

### Inline Code

- **Format**: Single backticks for inline code references
- **Use case**: File names, commands, variables, properties

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

## Markdownlint Configuration

### Required Rules

```json
{
  "MD013": { "code_blocks": false },
  "MD012": true,
  "MD022": true,
  "MD031": true,
  "MD032": true,
  "MD047": true,
  "MD009": true
}
```

### Rule Explanations

- **MD013**: Line length (disabled for code blocks)
- **MD012**: No multiple consecutive blank lines
- **MD022**: Headings should be surrounded by blank lines
- **MD031**: Fenced code blocks should be surrounded by blank lines
- **MD032**: Lists should be surrounded by blank lines
- **MD047**: Files should end with a single newline
- **MD009**: No trailing spaces

## Validation Commands

### Check Single File

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

### Check All Documentation

```bash
npx markdownlint 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
```

## Common Patterns

### Implementation Plans

```markdown
## Implementation Plan

### Phase 1: Foundation (Day 1)

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

- Run markdownlint on all changed markdown files
- Block commits with linting violations
- Auto-fix common issues when possible

### CI/CD Integration

- Include markdownlint in build pipeline
- Generate reports for documentation quality
- Fail builds with critical violations

### Team Guidelines

- All documentation PRs must pass markdownlint
- Use provided templates for new documents
- Follow established patterns for consistency

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

---

**Last Updated**: 2025-07-09
**Version**: 1.0
**Maintainer**: Matthew Raymer


### Heading Uniqueness

- **Rule**: No duplicate heading content at the same level
- **Scope**: Within a single document
- **Rationale**: Maintains clear document structure and navigation
- **Example**:

  ```markdown
  ## Features        ✅
  ### Authentication
  ### Authorization

  ## Features        ❌ (Duplicate heading)
  ### Security
  ### Performance
  ```