Skip to content

chore: enforce 7 more markdownlint rules, fix pre-existing violations - #174

Merged
Arthurvdv merged 1 commit into
mainfrom
ci/markdownlint-debt
Sep 6, 2026
Merged

chore: enforce 7 more markdownlint rules, fix pre-existing violations#174
Arthurvdv merged 1 commit into
mainfrom
ci/markdownlint-debt

Conversation

@Arthurvdv

Copy link
Copy Markdown
Member

Follow-up to #171. Resolves the markdownlint debt that shipped disabled to get the gate green, and re-evaluates the "deliberate convention" disables. Stacked on ci/pr-build (base will move to main once #171 merges).

Result: 20 disabled → 13 disabled, 7 now enforced

Enforced now (were disabled):

  • MD009, MD012, MD031, MD032, MD047 — whitespace hygiene, cleared via markdownlint --fix across ~20 files (trailing spaces, blank-line normalization, final newline). All changes verified prose-safe.
  • MD055, MD056 — table pipe style / column count. The only offenders repo-wide were two malformed borderless tables in LinterCop/LC0090; reformatted to bordered pipes with correct column counts (data preserved, renders as 3 correct tables).

The key finding

115 content files author code with Hugo shortcodes ({{< highlight >}}, {{< tab >}}, {{< tabpane >}}), which markdownlint parses as prose. That makes a whole class of rules structural false positives, not fixable debt — there's no config to make markdownlint read shortcode bodies. Verified with the exact CI tool (markdownlint-cli2@0.23.2).

A concrete example caught during implementation: --fix with MD038 enabled corrupted a PowerShell backtick line-continuation in github.md (stripped indentation, reading the backticks as a code span). MD038 was reverted and moved to the disabled set.

Stays disabled — now categorized with reasons in .markdownlint.jsonc

  • Structural false positive (code in shortcodes): MD033, MD018, MD025, MD026, MD034, MD038.
  • Deliberate convention: MD013 (prose authored as long unwrapped lines), MD001 (rule pages open at ### Example under the front-matter title; cli2 counts the title as H1 → h1→h3).
  • Deferred manual debt (future pass): MD022, MD040, MD046, MD036, MD060.

Docs sync

.claude/rules/rule-pages.md now documents bordered pipe tables with consistent column counts (supports MD055/MD056). The /new-rule skill already emits compliant tables and clean Markdown — no change needed.

Verification (local, current tree)

  • markdownlint-cli2@0.23.2 "content/**/*.md"0 issues, 148 files.
  • hugo --gc --minify --panicOnWarning --printPathWarnings → clean.
  • htmltest → 157 docs pass (LC0090 tables render; #compensating-usages anchor intact).

Out of scope (noted for later)

  • Migrating shortcode code blocks → fenced blocks with {hl_lines} would unlock MD018/MD025/MD026/MD033/MD034 but touches 115 files, rule-pages.md, and /new-rule — a separate initiative.
  • Clearing the deferred-debt rules and the pre-existing broken links (still allowlisted in .htmltest.yml) remain their own follow-ups.

🤖 Generated with Claude Code

Re-enables the markdownlint rules that can be enforced without false
positives or churn, and clears their existing violations.

Enforced now (were disabled): MD009, MD012, MD031, MD032, MD047 (whitespace
hygiene, auto-fixed) and MD055, MD056 (table pipe style / column count).

- Fix the two malformed borderless tables in LinterCop/LC0090 — the only
  MD055/MD056 offenders in the repo — to bordered pipes with correct column
  counts (data preserved).
- Apply markdownlint --fix for the 5 whitespace rules across ~20 content
  files (trailing spaces, blank-line normalization, final newline).
- rule-pages.md: document bordered pipe tables with consistent column counts.

Stays disabled, now categorized with reasons in .markdownlint.jsonc:
- Structural false positives — code lives in Hugo shortcodes ({{< highlight >}},
  {{< tab >}}) that markdownlint parses as prose: MD033, MD018, MD025, MD026,
  MD034, MD038 (the last would corrupt PowerShell backtick line-continuations).
- Deliberate conventions: MD013 (long unwrapped prose), MD001 (### under the
  front-matter title).
- Deferred manual debt: MD022, MD040, MD046, MD036, MD060.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@Arthurvdv
Arthurvdv merged commit 4014941 into main Sep 6, 2026
1 check passed
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