Close up the heading-level gaps on 82 pages - #148
Closed
oblomov-dev wants to merge 1 commit into
Closed
Conversation
82 of 123 pages jumped a level - 31 went straight from `#` to `####`, 21 had `##` and `####` with no `###` between them. Every page sets `outline: [2, 4]`, so the box on the right collects h2 to h4: on a page whose sections are h4, it showed them at the indent of a sub-sub-section, and on the 15 pages whose only heading level was h3, one level in. One rule fixes all of them: map the levels a page actually uses onto consecutive levels starting at `##`, preserving relative depth. `#`+`####` becomes `#`+`##`; `#`+`##`+`####` becomes `#`+`##`+`###`. The author's hierarchy survives exactly; only the gaps go. Zero pages have one left. The anchors do not move - verified in the built HTML rather than assumed: vitepress emits `<h4 id="play-sounds">`, the id being the slugified TEXT. So all 111 fragment links in this repository still resolve. This was proposed once and turned down, for a good reason: `##` was 24px with a rule and 72px of air, so promoting a section heading made pages shout. The compact layout since then puts `h2` at 19px with a third of the padding, which is what made this worth doing at all. It also broke `check:version`, and the way it broke is the point. The release headings in changelog.md were `###` and became `##`; the gate's pattern pinned `###`, so a check about the release NUMBER went red over a `#`. It said so plainly - "the file changed shape, fix the pattern" - rather than silently matching nothing, which is the failure it was written against. The pattern now accepts any heading level, because the level was never what it was checking, and a gate that fires on a change it does not care about is one people learn to route around.
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.
82 of 123 pages jumped a level. 31 went straight from
#to####; 21 had##and####with no###between them. Every page setsoutline: [2, 4], so the box on the right collects h2 to h4 — on a page whose sections are h4 it showed them at the indent of a sub-sub-section, and on the 15 pages whose only heading level was h3, one level in.One rule fixes all of them: map the levels a page actually uses onto consecutive levels starting at
##, preserving relative depth.#+#####+###+##+#####+##+###The author's hierarchy survives exactly; only the gaps go. Zero pages have one left.
The anchors do not move — verified in the built HTML rather than assumed: VitePress emits
<h4 id="play-sounds">, the id being the slugified text, not the level. All 111 fragment links in this repository still resolve.Why now, when this was turned down before
For a good reason:
##used to be 24px with a rule and 72px of air, so promoting a section heading made pages shout. The compact layout since then putsh2at 19px with a third of the padding — which is what makes this worth doing at all.It broke
check:version, and that is the pointThe release headings in
changelog.mdwere###and became##; the gate's pattern pinned###, so a check about the release number went red over a#. It said so plainly — "the file changed shape, fix the pattern" — rather than silently matching nothing, which is the failure mode it was written against. The pattern now accepts any heading level, because the level was never what it was checking, and a gate that fires on a change it does not care about is one people learn to route around.Generated by Claude Code