41 lines
2.0 KiB
Markdown
41 lines
2.0 KiB
Markdown
# Integration Plan for Markdown Conformance (PR-830)
|
|
|
|
## Goals
|
|
- Ensure BMAD-generated and authored Markdown renders correctly across CommonMark-compatible parsers.
|
|
- Enforce six PR-830 rules (lists/tables/fences spacing, bullet dash style, fence language) with low friction.
|
|
|
|
## Components
|
|
1) Custom conformance checker (already added): `tools/markdown/check-md-conformance.js`
|
|
- Zero-dep, fast, CI-friendly, includes table blank-line rule.
|
|
2) markdownlint (config in `.patch/830/.markdownlint.json` + custom table rule):
|
|
- Authoring ergonomics via editor integration and CLI.
|
|
|
|
## CI wiring (proposed)
|
|
- Add npm scripts in `package.json`:
|
|
- "check:md:docs": "node tools/markdown/check-md-conformance.js docs"
|
|
- "check:md:all": "node tools/markdown/check-md-conformance.js docs bmad src"
|
|
- "lint:md": "markdownlint \"docs/**/*.md\" \"bmad/**/*.md\" \"src/**/*.md\" --config .patch/830/.markdownlint.json --rules .patch/830/markdownlint-rules/table-blank-lines.js"
|
|
- In CI (GitHub Actions):
|
|
- Run `npm run check:md:all` as the source of truth for PR-830 guarantees.
|
|
- Optionally run `npm run lint:md` to provide authoring feedback.
|
|
|
|
## Editor setup
|
|
- Recommend VS Code extension: `DavidAnson.vscode-markdownlint`.
|
|
- `.markdownlint.json` will apply automatically for built-in rules.
|
|
- Use CLI for the custom table rule until we package it or port to a custom ruleset extension.
|
|
|
|
## Roadmap
|
|
- Short term:
|
|
- Keep both tools; rely on custom checker for CI gating.
|
|
- Fix high-traffic docs incrementally (e.g., docs/ide-info/*) or via targeted scripts.
|
|
- Medium term:
|
|
- Consider a safe auto-fix utility for inserting blank lines and fence languages.
|
|
- Evaluate porting the table rule into a markdownlint custom rules package.
|
|
- Long term:
|
|
- Integrate checks into generation pipelines so outputs are clean by default.
|
|
|
|
## Acceptance
|
|
- `npm run check:md:all` passes on a representative set of generated outputs and curated docs.
|
|
- markdownlint reports minimal violations aligned with team conventions.
|
|
- No regressions in rendered structure across parsers.
|