Conversation
The DoltHub v2 generator was one 448-line script. Hosted's v1 API needs the same rendering — its spec deliberately shares DoltHub v2's error model, success envelope, and pagination conventions — so the rendering moves to scripts/lib/openapi-docs.mjs and generate-api-v2.mjs becomes config. The only DoltHub-specific behaviour left is the Database tag's sub-resource grouping, now an opt-in `groups` config rather than `if (tag === "Database")`. Two defects fixed along the way, which is why the v2 pages change: Schema links resolved one level too deep. Pages build to <page>/index.html and are served from <page>/, so a sibling-relative `models#model-user` from the user page resolved to .../user/models — dead on every generated v2 page, and in the hand-written authentication.md and migration.md too. Links are now site-root-relative; the rehype base-path plugin prefixes the site base. curl examples dropped required query parameters, so the command as printed was a 400. The SQL endpoints need ?ref=&q=; they now carry the spec's own example values. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Documents the new public REST API for the Hosted control plane, under Products > Hosted Dolt > API > v1, mirroring the DoltHub API layout. specs/hosted-v1.yaml is vendored from ld's hosted-web/packages/hosted/openapi/v1.yaml, the same way the DoltHub v2 spec is. user.md, deployment.md, and models.md are generated from it by scripts/generate-hosted-api-v1.mjs (npm run generate-hosted-api-v1) — never hand-edit them. The two READMEs and authentication.md are hand-written. The authentication page documents the hsat.v1. token prefix, the settings/tokens flow, the show-once secret, and the fixed expiry options, all of which live in ld rather than in the spec. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Re-vendors specs/hosted-v1.yaml from ld main (1c62599829e), replacing the copy taken from the taylor/hosted-api-v1-list-instances branch, and regenerates deployment.md and models.md from it. The changes are all prose — no endpoints, schemas, or fields moved (still 6 operations and 17 schemas). Two are rewordings of the create-deployment 5xx guidance and the pagination description. The third is a real contract detail: next_page_token is now documented as absent on the last page rather than "absent or empty", and `meta` is omitted entirely there. That last one also invalidated a hand-written sentence in v1/README.md, which told clients to treat an empty token as the end of results. Updated to match: presence of the token is the only check needed. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
The sections sit directly under API rather than behind a "v1" node — with one version shipped, that layer was a click with nothing to choose. Every path still carries /v1/, so adding a v2 later reintroduces the version layer without moving any of these URLs. The v1 overview page is kept in the tree as "Overview". It holds the endpoint table, response envelope, error model, and stability policy, so dropping the v1 node without it would have left that page reachable only by inbound link. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Hosted Dolt API v1 docs
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>
Restore lost heading hierarchy across the docs
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.
No description provided.