Skip to content

chore: triage markdownlint warnings across repo #706

Description

@yvonnedevlinrh

Describe the bug

MegaLinter reports ~1,462 markdownlint warnings across .md files on main. These are configured as non-blocking (warnings, not errors) so they don't fail the CI job, but they add noise to linter reports.

To Reproduce

  1. Push any commit to main
  2. Check Standardized CI / Run linters log
  3. Markdownlint shows MARKDOWN | markdownlint | Found 1462 non blocking error(s)

Expected behavior

Markdown files should conform to the configured markdownlint rules, or rules that don't match the repo's conventions should be disabled in .markdownlint.json.

Additional context

Most warnings fall into a few categories:

  • MD060 (table column style) — widespread across AGENTS.md, docs/QUICK_START.md
  • MD013 (line length > 400) — long lines in agent .md files
  • MD041 (first line heading) — openspec files, man pages, PR template
  • MD024 (duplicate headings) — CHANGELOG.md (Changed, Fixed repeated per release)

Some of these (MD024 in changelogs, MD041 in man pages/templates) likely warrant rule exclusions in .markdownlint.json rather than file changes.

Metadata

Metadata

Labels

No labels
No labels

Type

No type

Fields

Priority

Medium

Effort

Low

Projects

Status
In progress 📋

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions