ldy26098
/
BMAD-METHOD
mirror of https://github.com/bmad-code-org/BMAD-METHOD.git
1
0
Fork 0
Code Packages Projects Releases Wiki Activity

fix: add CommonMark-compliant markdown formatting rules (#830) 

* fix: add CommonMark-compliant markdown formatting rules to workflow

Problem:
--------
BMAD generates markdown that violates CommonMark specification by omitting
required blank lines around lists, tables, and code blocks. While GitHub's
renderer (GFM) handles this gracefully, strict parsers like Mac Markdown.app
break completely, rendering lists as plain text and losing document structure.

Solution:
---------
Add 6 mandatory markdown formatting rules to workflow.xml (line 73) that
enforce proper spacing and consistency:

1. ALWAYS add blank line before and after bullet lists
2. ALWAYS add blank line before and after numbered lists
3. ALWAYS add blank line before and after tables
4. ALWAYS add blank line before and after code blocks
5. Use - for bullets consistently (not * or +)
6. Use language identifier for code fences

Impact:
-------
- Makes BMAD output CommonMark compliant
- Ensures compatibility with ALL markdown parsers, not just GitHub
- Follows industry best practices for professional documentation
- Future-proofs against stricter parser implementations
- Zero content changes - only formatting improved

Testing:
--------
Comprehensive three-phase testing completed:
- Phase 1: Synthetic test validating fix mechanism
- Phase 2: Fresh install end-to-end test (API Gateway project)
- Phase 3: GitHub validation with visual proof

Results: 1,112 lines of formatting improvements, 0 content changes,
100% CommonMark compliance achieved.

Test Evidence:
--------------
Complete test repository with before/after comparison, Mac Markdown.app
screenshot proving the issue, and comprehensive documentation:
https://github.com/jheyworth/bmad-markdown-formatting-test

See TEST.md for full documentation, test methodology, and evidence.

🤖 Generated with Claude Code (https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* Remove TEST.md per maintainer feedback

As requested by @bmadcode - the test documentation was useful during review but is not needed in the repository. Testing evidence remains documented in the PR description and external test repository.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

---------

Co-authored-by: Claude <noreply@anthropic.com>
This commit is contained in:
jheyworth 2025-10-29 03:27:48 +00:00 committed by GitHub
parent 44bc96fadc
commit 8376ca0ba2
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 8 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
bmad/core/tasks/workflow.xml
View File

@ -70,6 +70,14 @@
<substep n="2c" title="Handle Special Output Tags"> <substep n="2c" title="Handle Special Output Tags">
<if tag="template-output"> <if tag="template-output">
<mandate>Generate content for this section</mandate> <mandate>Generate content for this section</mandate>
<mandate critical="true">MARKDOWN FORMATTING RULES - Critical for proper rendering across all markdown parsers:
1. ALWAYS add blank line before and after bullet lists (-, *, +)
2. ALWAYS add blank line before and after numbered lists (1., 2., etc.)
3. ALWAYS add blank line before and after tables (| header |)
4. ALWAYS add blank line before and after code blocks (```)
5. Use - for bullets consistently (not * or +)
6. Use language identifier for code fences (```bash, ```javascript, etc.)
</mandate>
<mandate>Save to file (Write first time, Edit subsequent)</mandate> <mandate>Save to file (Write first time, Edit subsequent)</mandate>
<action>Show checkpoint separator: ━━━━━━━━━━━━━━━━━━━━━━━</action> <action>Show checkpoint separator: ━━━━━━━━━━━━━━━━━━━━━━━</action>
<action>Display generated content</action> <action>Display generated content</action>