fix(lint): make the markdownlint pre-commit hook pass on a pristine tree - #132
Merged
Conversation
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>
There was a problem hiding this comment.
No issues found.
Verified the fix end-to-end:
.editorconfigindent_size = 2for[*.md]is the correct root cause — no prettier config exists, so editorconfig drives prettier's markdown indent, and it now agrees with.markdownlint.jsonMD007.indent = 2.- Whitespace-ignored diff on
AGENTS.mdand 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.
4 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
markdownlintstep of the lefthookpre-commitfailed on the unmodified default branch:CHANGELOG.mdproduced 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..editorconfighad noindent_sizeunder[*.md], so Markdown inherited the global4. Prettier reads.editorconfigand reindented nested bullets to 4, whichMD007.indent=2then rejected — the two hooks could not both be satisfied. Settingindent_size = 2makes them agree, matching howarillso/action.playbookalready solves this;.markdownlint.jsonkeeps the org-wideindent: 2unchanged.### Addedinside[Unreleased]and a second### Removedinside[1.0.0]were merged into the existing sections, sosiblings_onlystays on and real duplicates keep being reported.CLAUDE.mdis a bare@AGENTS.mdimport and the pull request template is a form fragment starting at H2. Both are headingless by construction and now carry a file-localmarkdownlint-disable-file.CHANGELOG.md; no wording changed.Test plan
npx --yes -- markdownlint-cli2 $(git ls-files '*.md')— 0 issues across all 11 filesnpx --yes -- prettier --checkover the hook globs (*.json,*.yml,*.yaml,*.md) — clean--no-verify, with gitleaks, markdownlint and prettier all passinggit diff --ignore-all-spaceonAGENTS.mdand the READMEs is empty, confirming indentation-only changes