crowd-funder-for-time-pwa/.cursor/rules/docs/markdown_workflow.mdc

# Markdown Workflow & Validation

> **Agent role**: Reference this file for markdown validation rules,
> enforcement procedures, and workflow management.

## Markdownlint Configuration

### Core Rules

```json
{
  "MD013": { "line_length": 80, "code_blocks": false },
  "MD012": true,
  "MD022": true,
  "MD031": true,
  "MD032": true,
  "MD047": true,
  "MD009": true,
  "MD004": { "style": "dash" }
}
```

### Rule Explanations

- **MD013**: Line length (80 chars, 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
- **MD004**: Consistent list markers (dash style)

## Validation Commands

### Check All MDC Files

```bash
npm run markdown:check
```

### Auto-fix Formatting Issues

```bash
npm run markdown:fix
```

### Check Single File

```bash
npx markdownlint-cli2 .cursor/rules/filename.mdc
```

## Enforcement Workflow

### Pre-commit Hooks

- **Automatic**: `lint-staged` runs `markdownlint-cli2 --fix` on all
  staged `.mdc` files
- **Result**: Files are automatically formatted before commit
- **Blocking**: Commits with unfixable violations are blocked

### CI/CD Integration

- **Build Pipeline**: Include markdownlint in automated builds
- **Quality Reports**: Generate documentation quality metrics
- **Build Failure**: Fail builds with critical violations

### Team Guidelines

- **PR Requirements**: All documentation PRs must pass markdownlint
- **Templates**: Use provided templates for new documents
- **Patterns**: Follow established patterns for consistency
- **Auto-fixing**: Let automation handle formatting, focus on content

## Quality Assurance

### Validation Checklist

- [ ] All files pass `npm run markdown:check`
- [ ] Line length under 80 characters
- [ ] Proper blank line spacing around elements
- [ ] No trailing spaces
- [ ] Consistent list markers
- [ ] Proper heading hierarchy
- [ ] Code blocks have language specification

### Common Issues & Fixes

#### Trailing Spaces

```bash
# Remove trailing spaces
sed -i 's/[[:space:]]*$//' .cursor/rules/**/*.mdc
```

#### Multiple Blank Lines

```bash
# Remove multiple blank lines
sed -i '/^$/N;/^\n$/D' .cursor/rules/**/*.mdc
```

#### Missing Newlines

```bash
# Add newline at end if missing
find .cursor/rules -name "*.mdc" -exec sed -i -e '$a\' {} \;
```

## Integration Points

### Git Workflow

1. **Edit**: Make changes to MDC files
2. **Stage**: `git add .cursor/rules/filename.mdc`
3. **Auto-fix**: `lint-staged` runs `markdownlint-cli2 --fix`
4. **Commit**: Changes are committed with perfect formatting

### Development Workflow

1. **Create/Edit**: Use templates from `markdown_templates.mdc`
2. **Validate**: Run `npm run markdown:check` before committing
3. **Auto-fix**: Use `npm run markdown:fix` for bulk fixes
4. **Review**: Ensure content quality, not just formatting

## Model Implementation Checklist

### Before Starting Workflow

- [ ] **Configuration Review**: Understand markdownlint rules and settings
- [ ] **Tool Availability**: Ensure markdownlint-cli2 is installed and working
- [ ] **File Scope**: Identify which files need validation or fixing
- [ ] **Backup Strategy**: Consider backing up files before bulk operations

### During Workflow Execution

- [ ] **Validation First**: Run `npm run markdown:check` to identify issues
- [ ] **Issue Analysis**: Review and understand each validation error
- [ ] **Auto-fix Application**: Use `npm run markdown:fix` for automatic fixes
- [ ] **Manual Review**: Check files that couldn't be auto-fixed

### After Workflow Completion

- [ ] **Final Validation**: Confirm all files pass `npm run markdown:check`
- [ ] **Quality Review**: Verify formatting meets project standards
- [ ] **Documentation Update**: Update any related documentation or guides
- [ ] **Team Communication**: Share workflow results and any manual fixes needed

### Workflow-Specific Requirements

- [ ] **Pre-commit Hooks**: Ensure lint-staged configuration is working
- [ ] **CI/CD Integration**: Verify build pipeline includes markdown validation
- [ ] **Team Guidelines**: Confirm all team members understand the workflow
- [ ] **Error Resolution**: Document common issues and their solutions

---

**See also**:

- `.cursor/rules/docs/markdown_core.mdc` for core formatting standards
- `.cursor/rules/docs/markdown_templates.mdc` for document templates

**Status**: Active workflow and validation
**Priority**: Medium
**Estimated Effort**: Ongoing reference
**Dependencies**: markdown_core.mdc, markdown_templates.mdc
**Stakeholders**: Development team, Documentation team