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

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

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

Shell Commands

# 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

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

# 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

{
  "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

npx markdownlint docs/filename.md

Check All Documentation

npx markdownlint docs/

Auto-fix Common Issues

# 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

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

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

Performance Metrics

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

# 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