eff7e339af
- Remove legacy rule files (documentation.mdc, general_development.mdc, etc.) - Implement new meta-rule system with core, app, and feature categories - Add meta-rule files for different workflows (bug diagnosis, feature planning, etc.) - Create organized directory structure: core/, app/, features/, database/, etc. - Add comprehensive README.md for rules documentation - Establish new rule architecture with always-on and workflow-specific rules This restructuring improves rule organization, enables better workflow management, and provides clearer separation of concerns for different development tasks.
169 lines
4.7 KiB
Plaintext
169 lines
4.7 KiB
Plaintext
# 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
|