# 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