Stephan Lo
f797af114b
test: configure comprehensive markdown linting with Docsy best practices
Configure markdownlint with rules aligned to technical documentation
standards and Docsy theme conventions.
Design Decisions:
- Enable core quality rules (heading hierarchy, consistent list styles)
- Allow inline HTML for Docsy shortcodes and components
- Permit bare URLs (common in technical documentation)
- Make code block language hints optional (pragmatic for existing content)
- Set maximum 2 consecutive blank lines (balanced readability)
- Enforce single trailing newline (POSIX standard)
- Use asterisk for unordered lists (consistency)
- Allow 2-space list indentation (Markdown standard)
Auto-fixed Issues:
- Converted dash lists to asterisk lists (568 fixes)
- Removed trailing spaces (211 fixes)
- Added missing trailing newlines (74 fixes)
- Added blank lines around lists and headings (100+ fixes)
Remaining Style Warnings (intentionally accepted):
- MD029: List numbering variations in meeting notes (75 instances)
- MD036: Bold text for section headers in ADRs (13 instances)
- MD025: Multiple H1 in notes/brainstorming docs (10 instances)
- MD032/MD022: Minor spacing variations (15 instances)
Test Results:
✅ Hugo build: 227 pages generated successfully
✅ HTML validation: No errors
✅ Link checking: All links valid (except dev-only livereload)
✅ Markdown linting: Only non-critical style warnings remain
The configuration balances strict quality checks with pragmatic
flexibility for diverse content types (documentation, ADRs, meeting
notes, tutorials).