Skip to content

fix(lint): make the markdownlint pre-commit hook pass on a pristine tree - #132

Merged
sbaerlocher merged 1 commit into
mainfrom
fix/markdownlint-changelog
Aug 9, 2026
Merged

fix(lint): make the markdownlint pre-commit hook pass on a pristine tree#132
sbaerlocher merged 1 commit into
mainfrom
fix/markdownlint-changelog

Conversation

@sbaerlocher

Copy link
Copy Markdown
Member

Summary

  • The markdownlint step of the lefthook pre-commit failed on the unmodified default branch: CHANGELOG.md produced 64 errors. Every commit staging a changelog entry was blocked and could only land with --no-verify, which also disables gitleaks, yamllint, ansible-lint and actionlint.
  • Three separate causes, none of which required relaxing a rule. MD007: .editorconfig had no indent_size under [*.md], so Markdown inherited the global 4. Prettier reads .editorconfig and reindented nested bullets to 4, which MD007.indent=2 then rejected — the two hooks could not both be satisfied. Setting indent_size = 2 makes them agree, matching how arillso/action.playbook already solves this; .markdownlint.json keeps the org-wide indent: 2 unchanged.
  • MD024: two genuinely duplicated headings, not the format-inherent repetition of Keep a Changelog. A second ### Added inside [Unreleased] and a second ### Removed inside [1.0.0] were merged into the existing sections, so siblings_only stays on and real duplicates keep being reported.
  • MD041: CLAUDE.md is a bare @AGENTS.md import and the pull request template is a form fragment starting at H2. Both are headingless by construction and now carry a file-local markdownlint-disable-file.
  • Reformatting is indentation-only outside CHANGELOG.md; no wording changed.

Test plan

  • npx --yes -- markdownlint-cli2 $(git ls-files '*.md') — 0 issues across all 11 files
  • npx --yes -- prettier --check over the hook globs (*.json, *.yml, *.yaml, *.md) — clean
  • Commit lands without --no-verify, with gitleaks, markdownlint and prettier all passing
  • git diff --ignore-all-space on AGENTS.md and the READMEs is empty, confirming indentation-only changes
  • CI green

The `markdownlint` step in the lefthook `pre-commit` failed on the
unmodified default branch: `CHANGELOG.md` produced 64 errors, so every
commit staging a changelog entry was blocked and could only be landed
with `--no-verify`, which disables the remaining gates (gitleaks,
yamllint, ansible-lint, actionlint) as well.

Three separate causes, none of which required relaxing a rule:

- MD007: `.editorconfig` had no `indent_size` under `[*.md]`, so
  Markdown inherited the global `4`. Prettier reads `.editorconfig` and
  therefore reindented nested bullets to 4, which `MD007.indent=2` then
  rejected — the two hooks could not both be satisfied. Setting
  `indent_size = 2` for Markdown makes them agree, matching how
  `arillso/action.playbook` already solves this. `.markdownlint.json`
  keeps the org-wide `indent: 2` unchanged.

- MD024: two genuinely duplicated headings, not the format-inherent
  repetition of Keep a Changelog. A second `### Added` inside
  `[Unreleased]` and a second `### Removed` inside `[1.0.0]` were
  merged into the existing sections; `siblings_only` stays on, so real
  duplicates keep being reported.

- MD041: `CLAUDE.md` is a bare `@AGENTS.md` import and the pull request
  template is a form fragment starting at H2. Both are headingless by
  construction and now carry a file-local `markdownlint-disable-file`.

Reformatting is indentation-only outside `CHANGELOG.md`; no wording
changed.

Signed-off-by: Simon Bärlocher <claude@sbaerlo.ch>

@claude claude Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No issues found.

Verified the fix end-to-end:

  • .editorconfig indent_size = 2 for [*.md] is the correct root cause — no prettier config exists, so editorconfig drives prettier's markdown indent, and it now agrees with .markdownlint.json MD007.indent = 2.
  • Whitespace-ignored diff on AGENTS.md and all four READMEs is empty → indentation-only, no wording changed.
  • CHANGELOG MD024 fixes are pure section merges: no content lost, and both moved blocks stay within the same version's Added/Removed semantics.
  • MD041 disables are correctly scoped to the two headingless-by-construction files.
  • The three untouched md files still pass: the only 4-space lines (plugins/README.md) are inside a fenced code block, which prettier/MD007 ignore.

@sbaerlocher
sbaerlocher merged commit f6bc86c into main Aug 9, 2026
29 checks passed
@sbaerlocher
sbaerlocher deleted the fix/markdownlint-changelog branch August 9, 2026 16:21
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant