Skip to content

Add a markdownlint rule policy and make the Markdown files pass it - #366

Merged
NormB merged 2 commits into
mainfrom
fix/markdownlint
Oct 15, 2026
Merged

Add a markdownlint rule policy and make the Markdown files pass it#366
NormB merged 2 commits into
mainfrom
fix/markdownlint

Conversation

@NormB

@NormB NormB commented Oct 15, 2026 •
edited
Loading

Copy link
Copy Markdown
Owner

Makes pre-commit run markdownlint --all-files pass, with a rule policy in .markdownlint.yaml, and fixes the local link checker that this work needed.

Commits

  1. Make the local Markdown link checker run past the first link. scripts/check-markdown-links.sh exited 1 after the first link (((TOTAL_LINKS++)) under set -e). With that fixed it reported 8 false positives: [^\s] in ERE cut https:// reference definitions to http, and bracket text inside code blocks was read as links. New tests/test-check-markdown-links.sh (4 tests on fixture files) fails 4/4 on the old checker; reverting either pattern fix alone fails only its test. CI runs the tests and the checker in the Test Documentation job.
  2. Add a markdownlint rule policy and make the Markdown files pass it.

Rule decisions (markdownlint-cli 0.38.0, 10,271 findings on 40d8b32)

Rule Findings Decision
MD013 line length 2,081 disabled: prose is one paragraph per line; tables and URLs exceed any width
MD029 ordered-list prefix 237 disabled: steps split by unindented code blocks restart at their written number; renumbering changes the numbers readers see
MD036 emphasis as heading 311 disabled: bold labels introduce blocks; headings would change outlines and anchors
MD040 fence language 380 disabled: choosing a language per block is a separate content pass; text everywhere adds no information
MD041 first-line heading 1 disabled: the PR template is a body under a GitHub-supplied title
MD010 hard tabs 14 code_blocks: false: all 14 are inside code blocks (Makefile tabs in reference-apps/API_PATTERNS.md)
MD024 duplicate headings 215 siblings_only: true: 0 remain
MD033 inline HTML 3 allowed_elements: [br]: line breaks in table cells
MD032, MD031, MD022, MD012, MD007, MD005, MD004, MD034 6,926 fixed by the hook's --fix
MD026 trailing punctuation 19 fixed by --fix; GitHub drops : from anchors, so no anchor changes
MD037 spaces in emphasis 9 ___ fill-in blanks escaped as \_\_\_ (same rendering); --fix would have made them emphasis
MD038 spaces in code span 1 the span is a single space on purpose; same-line disable comment
MD051 link fragments 74 all 74 were broken on GitHub; fixed to GitHub's anchors (checked against GitHub's rendered HTML), stale TOC entries repointed or removed; CHANGELOG and wiki/Migration-Guide TOCs rebuilt from their headings

Checks

  • Every Markdown file parsed with markdown-it-py before and after: code block content identical in all 162 files, heading anchors identical in all files, link targets identical except the fragment fixes (32 files). Rendered text differs only in 19 heading colons and the edited TOCs.
  • reference-apps/API_PATTERNS.md keeps its 7 tab lines.
  • uvx pre-commit run --all-files: every hook passes. scripts/wiki-mirror.sh --check: current (16 files). scripts/check-markdown-links.sh: 1,279 links, 0 broken. tests/test-documentation-accuracy.sh: 12/12.
  • detect-secrets baseline rescanned with 1.4.0: same 108 findings, all still audited, 35 at new line numbers.

Not done

The advisory Markdown Lint job (markdownlint-cli2 0.23.2) reads the same config and still reports newer table rules: MD060 2,963, MD058 20, MD056 14. The job comment in lint.yml now says this; making it a gate needs a decision on those rules.

NormB added 2 commits October 15, 2026 11:16
@NormB
Make the local Markdown link checker run past the first link
9830a76 
scripts/check-markdown-links.sh stopped after the first link of the
first file and exited 1: under `set -e`, `((TOTAL_LINKS++))` returns
status 1 when the old value is 0. The four counters now use
`VAR=$((VAR + 1))`.

With the counters fixed, it reported 8 broken links, none of them
real:

- Five in .github/CODE_OF_CONDUCT.md. In `[ref]: url` definitions the
  pattern `[^\s]+` means "not a backslash or s" in ERE, so
  https://... was cut to "http" and checked as a file. The pattern
  now uses `[^[:space:]]`.
- Three were bracket text inside fenced code blocks
  (`log_line_prefix = '... [%l-1] ...'`, `[serviceName: string]:
  ServiceHealth`, `{ [key: string]: string }`). Lines inside ``` and
  ~~~ fences are now skipped.

On this tree it checks 1,276 links in 55 files and reports none
broken. tests/test-check-markdown-links.sh runs the checker on
fixture files: with the old checker all four tests fail; with each
of the two pattern fixes reverted on its own, only its test fails.
CI runs the tests and then the checker in the Test Documentation job.
@NormB
Add a markdownlint rule policy and make the Markdown files pass it
69338cc 
The markdownlint pre-commit hook (markdownlint-cli 0.38.0, default
rules) reported 10,271 findings in the 162 Markdown files on 40d8b32.
.markdownlint.yaml now sets the policy; each change carries its
reason in the file:

- Disabled: MD013 line length (2,081), MD029 ordered-list prefixes
  (237), MD036 emphasis as heading (311), MD040 fence language (380),
  MD041 first-line heading (1, the pull request template).
- Narrowed: MD010 hard tabs skips code blocks, so the Makefile tabs
  in reference-apps/API_PATTERNS.md stay (14 findings, all inside
  code blocks). MD024 duplicate headings reports same-parent
  duplicates only (215 before, none after). MD033 inline HTML allows
  <br> (3, all in table cells).

The rest are fixed in the files:

- `markdownlint --fix` (the hook's own argument) for MD032, MD031,
  MD022, MD012 blank lines, MD007 and MD005 list indentation, MD004
  list marker, MD034 bare URLs (wrapped in <>), and MD026 trailing
  colons in 19 headings. GitHub drops the colon from the anchor, so
  no anchor changes.
- MD037: nine fill-in blanks (`___`) in
  wiki/Improvement-Task-List.md are escaped as `\_\_\_`, which
  renders the same; the fixer would have joined them into emphasis.
- MD038: the one code span holding a single space, in
  wiki/Link-Fixes-Summary.md, keeps it under a same-line disable
  comment.
- MD051: 74 link fragments did not match any anchor on GitHub. Each
  now uses the anchor GitHub generates, checked against the rendered
  HTML from the contents API: `&` leaves a double hyphen, and an
  emoji with U+FE0F leaves the U+FE0F. Links to sections that no
  longer exist were pointed at the section that replaced them or
  removed. The table of contents of .github/CHANGELOG.md is rebuilt
  from its headings (it listed headings that exist only inside a code
  example and an HTML comment, and omitted four releases), as is the
  stale one in wiki/Migration-Guide.md. reference-apps/CHANGELOG.md
  had two more release links of the same kind.

Checks, before and after, parsing every Markdown file with
markdown-it-py: the content of every code block is identical, every
heading anchor is identical, and the only changed link targets are
the fragment fixes above. Rendered text differs only in the 19
heading colons and the edited tables of contents. `pre-commit run
--all-files` passes every hook; scripts/wiki-mirror.sh --check,
scripts/check-markdown-links.sh (1,279 links, none broken) and
tests/test-documentation-accuracy.sh (12/12) pass. The detect-secrets
baseline was rescanned (1.4.0): the same 108 findings, 35 at new
line numbers.

The Markdown Lint job in lint.yml stays advisory: markdownlint-cli2
0.23.2 also reads .markdownlint.yaml and still reports its newer
table rules (MD060 2,963, MD058 20, MD056 14). The job comment says
so.
@NormB
NormB merged commit ec0c37d into main Oct 15, 2026
32 checks passed
@NormB
NormB deleted the fix/markdownlint branch October 15, 2026 15:21
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@NormB