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

3.4 KiB
Raw Blame History

check-md-conformance.js vs. markdownlint

Overview

  • check-md-conformance.js

    • Purpose-built, zero-dependency Node script enforcing 6 CommonMark-oriented rules proposed in PR-830.
    • Focuses on spacing and consistency that affect cross-parser rendering (lists, tables, fences, bullet markers, fence language).
    • Simple to run in CI, no config required, clear actionable output.

  • markdownlint (CLI + VS Code extension)

    • General Markdown linter with robust parsing (markdown-it), rich ruleset, config files, and editor integration.
    • Great for authoring hygiene, inline disables, and team-wide conventions; partial auto-fix support.

Rule coverage mapping

  • Blank line around lists
    • check-md: YES (list-blank-before, list-blank-after)
    • markdownlint: YES (MD032)
  • Blank line around fenced code blocks
    • check-md: YES (fence-blank-before, fence-blank-after)
    • markdownlint: YES (MD031)
  • Fenced code block has language
    • check-md: YES (fence-language-missing)
    • markdownlint: YES (MD040)
  • Bullet marker normalization ("-")
    • check-md: YES (bullet-marker → enforces "-")
    • markdownlint: YES (MD004 configurable to dash)
  • Blank line around tables
    • check-md: YES (table-blank-before, table-blank-after; heuristic)
    • markdownlint: NO direct core rule (requires a custom rule or a different linter for tables)

Parsing rigor and edge cases

  • check-md-conformance.js

    • Heuristic/regex based; ignores fenced code blocks by design; detects tables via lines containing "|".
    • Supports backtick fences (```), simple numbered lists ("1."); may miss rare edge cases.
    • Very fast, zero dependencies, ideal for CI gating specific guarantees.

  • markdownlint

    • Parser-backed (markdown-it) with accurate tokenization of nested structures.
    • Large ruleset far beyond PR-830 scope (headings, indentation, inline HTML, etc.).
    • Highly configurable; good developer experience with editor feedback.

Configurability and DX

  • check-md-conformance.js

    • No configuration; rules hard-coded to PR-830 goals.
    • Clear text output; no auto-fix; no editor integration.

  • markdownlint

    • Configurable via .markdownlint.json; inline disables and path ignores.
    • Editor integration (VS Code) for live feedback; CLI supports --fix for some rules.

Performance and footprint

  • check-md: Single file, no deps, instant startup → perfect for CI.
  • markdownlint: Adds dev deps and config, still fast; richer ecosystem.

Recommended usage (together)

  • Keep both tools, each where it shines:
    • Use check-md-conformance.js in CI to enforce PR-830’s exact guarantees across generated outputs and repo docs (especially table spacing).
    • Use markdownlint for general authoring hygiene and contributor feedback (enable MD031, MD032, MD040, MD004: dash; disable noisy rules as needed).

Optional enhancements

  • Write a small custom markdownlint rule to require blank lines before/after tables, or continue relying on the custom checker for that.
  • Later, port the table rule into a markdownlint custom ruleset to consolidate linting surfaces if desired.
  • Consider an opt-in "--fix" mode in check-md for low-risk insertions (blank lines + fence language), applied to a subset first.

Next steps (proposed)

  • Add minimal markdownlint config and npm scripts (authoring quality).
  • Keep running tools/markdown/check-md-conformance.js in CI for generator outputs and docs (PR-830 guarantees).
  • Optionally prototype a markdownlint custom rule for table blank lines.