61 lines
2.9 KiB
Markdown
61 lines
2.9 KiB
Markdown
# PR #830 — fix: add CommonMark-compliant markdown formatting rules
|
||
|
||
URL: https://github.com/bmad-code-org/BMAD-METHOD/pull/830
|
||
Author: @jheyworth
|
||
State: open | Mergeable: true | Commits: 1 | Files changed: 2 | +367 / -0
|
||
Head: jheyworth:fix/markdown-formatting-commonmark-compliance → Base: bmad-code-org:v6-alpha
|
||
|
||
## Summary
|
||
|
||
This PR proposes adding an explicit, critical mandate to `bmad/core/tasks/workflow.xml` that enforces six CommonMark-aligned markdown formatting rules around lists, tables, and code fences. A companion `TEST.md` file documents the problem, solution, and three-phase validation including a public test repository demonstrating cross-parser behavior.
|
||
|
||
## Problem Statement
|
||
|
||
- BMAD-generated markdown sometimes omits required blank lines around lists/tables/code fences.
|
||
- GitHub’s renderer (GFM) is lenient; strict parsers (e.g., Mac Markdown.app) break — lists collapse to plain text, structure is lost.
|
||
|
||
## Proposed Change
|
||
|
||
Insert a critical mandate under `<if tag="template-output">` in `workflow.xml` with the following rules:
|
||
1) Blank line before/after bullet lists
|
||
2) Blank line before/after numbered lists
|
||
3) Blank line before/after tables
|
||
4) Blank line before/after code blocks
|
||
5) Use `-` consistently for bullets
|
||
6) Use language identifiers for code fences
|
||
|
||
Also adds `TEST.md` documenting tests and links to evidence.
|
||
|
||
## Files Changed
|
||
|
||
- bmad/core/tasks/workflow.xml — add mandate (≈8 lines)
|
||
- TEST.md — comprehensive test evidence (new, 359 lines)
|
||
|
||
## External Resources (Evidence)
|
||
|
||
- Test repository (before/after, screenshots):
|
||
- https://github.com/jheyworth/bmad-markdown-formatting-test
|
||
- Before vs After diff: https://github.com/jheyworth/bmad-markdown-formatting-test/compare/dcf405f...0b30d47
|
||
- Example files and screenshot paths in TEST.md
|
||
- CommonMark Spec v0.31.2: https://spec.commonmark.org/
|
||
|
||
### Review plan for external resources
|
||
|
||
- Read README.md and FINDINGS.md in the test repo to validate metrics and methodology
|
||
- Manually open the specific before/after files linked to confirm rendering changes
|
||
- Verify the Mac Markdown.app screenshot path and reproduce with a strict renderer (e.g., CommonMark CLI)
|
||
- Cross-check mandate text against relevant CommonMark sections (lists, code fences, tables)
|
||
|
||
## Initial Review Notes
|
||
|
||
- Impacted scope is small (single mandate) with no engine logic changes.
|
||
- Benefits: standards compliance, cross-tool compatibility, zero semantic content change.
|
||
- Risk: mandate phrasing must remain guidance (not a parser); ensure it doesn’t conflict with existing writer behavior or other mandates.
|
||
|
||
## Next Steps
|
||
|
||
- Validate that this mandate text aligns with BMAD’s writer/generator semantics (no conflicts).
|
||
- Run a quick end-to-end generation on a sample workflow to confirm no unintended format regressions.
|
||
- Consider adding automated markdown conformance checks to CI as a follow-up.
|
||
- Option: integrate a CommonMark linter or markdownlint rule set; document exceptions if any
|