chore(lint): disable markdownlint MD025 — documents use one H1 per section - #22
Merged
Conversation
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.
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
Adds
MD025: falseto.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.ymlis not in devkit's sync manifest —scripts/sync.tscarries the ast-grep rules and workflows only. Each repo holds a hand-seeded copy, and the copies have already drifted (MD013.line_lengthvaries 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 markdownlintrun against a probe inside the repo: a document with several H1 sections passes# Afollowed by### C:MD001/heading-incrementstill firesNote for anyone re-testing:
markdownlintsilently skips files outside the repo root, so a probe written to/tmpreports zero errors regardless of config. Probe from inside the repo.