Restore lost heading hierarchy across the docs - #170
Merged
Conversation
Operations, Quick Start, SQL Workbench, and Dolt Ecosystem were rendering at the same level as their own subsections, so Logs and Monitoring looked like peers of Operations rather than parts of it, and the right-side table of contents was 24 flat entries. The levels come from 4276c04, which demoted each page's section headings from h1 to h2 but left their existing h2 subsections alone, collapsing the two onto one level. Restored by mapping every heading back to its level at the original import (90815da) plus one, since ccc4760 moved the page h1 into frontmatter — so the five sections stay h2 and their 19 subsections become h3. Heading lines only; no prose changed. Anchor ids are unaffected: rehype-slug derives them from heading text, not level, so existing deep links still resolve. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Same collapse as hosted notable-features: 4276c04 demoted each page's section headings from h1 to h2 without demoting their existing h2 subsections, so the alternatives under "Dolt replaces…" — Soft Deletes, Change Data Capture, Files in Git, Spreadsheets, and the rest — rendered as peers of the section that introduces them instead of items within it. Recovered the same way: each heading mapped back to its level immediately before 4276c04, plus one for the page h1 that ccc4760 moved into frontmatter. Every heading matched that baseline, so the mapping was mechanical rather than a judgement call. 13 headings across 8 files; heading lines only, no prose touched, and no file ends up skipping a level. Anchor ids are unchanged — rehype-slug derives them from heading text. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Same collapse as notable-features and the use-case pages: 4276c04 demoted each page's section headings from h1 to h2 without demoting their existing h2 subsections. The numbered walkthrough steps in cloning.md and dolthub-as-remote.md, and the workbench/MySQL-client steps in getting-started.md, all rendered as peers of the "Example" section that introduces them rather than steps within it. 22 headings across 3 files, mapped back to their level immediately before 4276c04 plus one for the page h1 that ccc4760 moved into frontmatter. Two headings in cloning.md postdate that baseline (added by a8ff9bf) and were placed by hand: "5. Open a pull request" continues the numbered Example steps, so it joins them at h3; "Branch permissions" is a separate topic that follows the Example, so it stays at h2. Heading lines only, no prose changed, no file skips a level, and no inbound anchor links reference these pages. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Same collapse as the hosted and use-case pages, in both the Dolt and Doltgres copies of reference/sql/server/troubleshooting.md: the diagnostic steps under Basics and the symptoms under Problems rendered as peers of the sections that group them. 17 headings across the two files (9 dolt, 8 doltgres), mapped back to their level immediately before 4276c04 plus one for the page h1 that ccc4760 moved into frontmatter. Every heading matched the baseline, so no manual placement was needed. Submitting Issues correctly stays at h2 between the two grouped sections. Heading lines only; no prose changed, no skipped levels, no inbound anchor links to these pages. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The page opened with an empty "## Expressions, Functions, Operators" heading
restating its own title. It was a near-duplicate h1 in the source ("Functions,
Operators" vs the title's "Functions, and Operators"); 4276c04 demoted it to h2
and ccc4760 then moved the real title into frontmatter, leaving the copy behind
with no content under it.
Removing it is the right fix here rather than re-leveling. The remaining
headings — Statements, Clauses, Table expressions, and the rest — were always
siblings, so they stay at h2 and the page needs no other change. The same
pattern covers the 44 DoltLab release notes, where nesting sections under the
duplicate would have been worse than leaving them flat.
The one inbound link to this page targets #window-functions, which is
unaffected and still resolves.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Same collapse as the other pages: "Dolt CI Commands" and "Saved Query" rendered as peers of the sections they belong to rather than parts of them. 2 headings, mapped back to their level immediately before 4276c04 plus one for the page h1 that ccc4760 moved into frontmatter. Dolt CI Commands nests under "CI starts with Dolt" and Saved Query under "Steps"; Workflows, Events, and Jobs were always siblings and stay at h2. Heading lines only, no skipped levels, and nothing links to this page's anchors. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
storage-engine.md: B-Trees, Prolly Trees, and Comparison are the search-tree types "The Database Backbone: Search Trees" introduces, not peers of it. garbage-collection.md (dolt): Offline and "Online, with Automatic GC disabled" are the two ways "How to run garbage collection manually" describes — that section's own text introduces both. 5 headings, mapped back to their pre-4276c04 level plus one. Heading lines only, no skipped levels. The two inbound anchor links to these pages (#commit-graph, #automatic-gc) point at headings that stay at h2. Doltgres's garbage-collection.md is deliberately left alone. The mechanical mapping would nest its "Online" section under "How garbage is created", which is where the original had it — but that section is about running GC via select dolt_gc(), not about how garbage accumulates. The original nesting was an authoring mistake, and its current flat structure is already correct. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
getting-started.md: "Make sure Docker works" belongs to the download step, and the Basic Configuration and Adding Additional Functionality sections each own the options listed beneath them. pre-installer-administrator-guide.md: the three backup/restore methods sit under "Backup and restore volumes", and the two setup steps under "Run DoltLab on Hosted Dolt". 16 headings across the two files, mapped back to their pre-4276c04 level plus one. Heading lines only, no skipped levels. The inbound anchor links from aws/gcp/azure and start-doltlab-pre-installer all target headings that stay at h2. The 44 release notes are left alone — their extra heading is a restatement of the page title rather than a lost section, so they need a deletion rather than this re-leveling. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
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
1 participant
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.
Restores heading levels on 20 pages across all three sites. The diff is 189 heading lines plus one blank line — no prose changed.
The bug
4276c04demoted each page's section headings from#to##but left their existing##subsections alone, collapsing two levels into one. So sections render as siblings of their own subsections — onnotable-features.md,Operationssat level withLogsandMonitoring, and the TOC was 24 flat entries.Each heading is mapped back to its level immediately before
4276c04, plus one for the page H1 thatccc4760moved into frontmatter. Mechanical everywhere except the three cases below.Worth reviewing
cloning.md— two headings postdate the baseline, placed by hand: "5. Open a pull request" joins the numbered Example steps at h3; "Branch permissions" is a separate topic and stays h2.expressions-functions-operators.md— a deletion, not a re-level. The source had a near-duplicate h1 pair (title…Functions, and Operators, then…Functions, Operators); the title moved to frontmatter, leaving an empty copy. Re-leveling would have nested every section under it. The 44 DoltLab release notes share this shape and are excluded — they need the same deletion separately.doltgres
garbage-collection.md— deliberately not fixed. The mapping would nest "Online" under "How garbage is created", where the original had it, but that section is about running GC viaselect dolt_gc(). The original nesting was wrong; the current flat structure is correct.Verification
Heading lines only, no skipped levels, anchor ids unchanged (rehype-slug derives them from text) with every inbound anchor link checked. All three sites build (202 / 78 / 79 pages). TOC nesting confirmed in-browser. Suites: 90/90 dolt, 27/27 doltlab, 32/32 doltgres.
Outstanding
Same root cause, not here: 6 more files led by
reference/cli/cli.md(all 73 headings), plus the 44 release notes anddolt reference/sql/server/README.mdon the deletion side.