Skip to content

chore(lint): disable markdownlint MD025 — documents use one H1 per section - #22

Merged
RickCogley merged 2 commits into
mainfrom
chore/markdownlint-md025
Jul 31, 2026
Merged

chore(lint): disable markdownlint MD025 — documents use one H1 per section#22
RickCogley merged 2 commits into
mainfrom
chore/markdownlint-md025

Conversation

@RickCogley

Copy link
Copy Markdown
Member

Summary

Adds MD025: false to .markdownlint.yml.

eSolia documents use one H1 per major section, nesting H2/H3 underneath and returning to H1 for the next section. The document title comes from the filename and CMS metadata, not from an in-body heading. MD025 (single-title/single-h1) requires exactly one top-level heading and therefore fails every document written that way.

This is not a style preference — documents built around a single top-level H1 have caused ingestion problems with Typst, and the Codex CMS documents under content/documents/ already follow the per-section pattern.

MD001 (heading-increment) stays enabled and is the rule that actually matters for heading hygiene: an H1 followed by H3 still errors.

Why this is a separate PR per repo

.markdownlint.yml is not in devkit's sync manifest — scripts/sync.ts carries the ast-grep rules and workflows only. Each repo holds a hand-seeded copy, and the copies have already drifted (MD013.line_length varies from 200 to 600 across repos, deliberately). Syncing the file would clobber those local settings, so the config is being corrected repo by repo instead.

Change request and rationale: eSolia/devkit#257 (devkit's own copy: eSolia/devkit#258).

Test plan

  • npx markdownlint run against a probe inside the repo: a document with several H1 sections passes
  • Same probe with # A followed by ### C: MD001/heading-increment still fires
  • No new findings introduced on existing files (adding a disabled rule cannot create errors)

Note for anyone re-testing: markdownlint silently skips files outside the repo root, so a probe written to /tmp reports zero errors regardless of config. Probe from inside the repo.

RickCogley and others added 2 commits July 31, 2026 19:42
eSolia documents use one H1 per major section, nesting H2/H3 underneath and
returning to H1 for the next section. The document title comes from the
filename and CMS metadata rather than an in-body heading.

MD025 requires exactly one top-level heading, so it fails every document
written to that convention. Documents built around a single top-level H1
have caused ingestion problems with Typst.

MD001 (heading-increment) stays enabled and still errors on a skipped level.

Change request: eSolia/devkit#257

InfoSec: no security impact — lint configuration only.
@RickCogley
RickCogley merged commit baabb49 into main Jul 31, 2026
@RickCogley
RickCogley deleted the chore/markdownlint-md025 branch July 31, 2026 10:48
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