feat: anchor every section heading (A2) - #353
Merged
Merged
Conversation
First area of the anchor pass. Every section heading in docs/tables now carries
an explicit `{#anchor}` — 114 of them — which is the identity Enterprise
overlays attach to from A5 and which survives the heading being reworded.
Anchors are taken from the ids the site already renders, not derived from the
heading text. That distinction turned out to matter: Mintlify applies smart
quotes before slugifying, so `## What's next?` renders as `what’s-next` with a
curly apostrophe, and a derived slug would have silently changed the id and
broken every existing deep link to it. Reading the ids back from `mint export`
makes the pass correct by construction rather than by reimplementing rules we
would have to keep in sync.
Headings that begin with a number need their period escaped. `### 1. Setup`
renders with its number until an explicit anchor is added, at which point
Mintlify re-parses the text, treats the number as an ordered list marker, and
drops it from both the heading and the table of contents. 117 headings across 17
pages start this way, so the pass would have quietly renumbered a good deal of
the site.
Verified: the exported site is unchanged. All six existing deep links into
tables still resolve.
Completes the anchor pass. 805 of 810 section headings across the authored pages
now carry an explicit `{#anchor}`, the identity Enterprise overlays attach to
from A5 and the one thing that survives a heading being reworded.
Three more cases the tables pilot had not reached, each of which would have
corrupted anchors silently:
Setext headings. Eleven h2s in the reranking pages are written as text over a
rule rather than with hashes. Mintlify gives them ids like any other heading, so
a parser that only saw hashes consumed the rendered ids out of order and handed
every later heading on the page the wrong anchor — plausible names attached to
the wrong sections. They are rewritten to hashes, which renders identically, and
a strict count check now refuses to write anything when source headings and
rendered ids disagree.
Headings below h4. Mintlify emits no id for h5, so there is nothing to read back
and nothing to preserve. The eight in the corpus, all API method names on one
page, keep their generated markup and stay unanchored.
Ampersands. Mintlify keeps `&` in a generated id but strips it from an explicit
anchor, so `observability-&-performance` cannot be written down: any anchor set
on those headings changes the id and breaks links to it. Five headings join two
words this way; they keep their generated id. If A5 needs to attach to one,
rewording the heading is the honest fix rather than silently moving it.
Verified: the exported site is unchanged.
Eighteen headings across twelve pages produced anchors containing `&`, `/`, or curly quotes. Ampersands were the pressing case — Mintlify keeps `&` in a generated id but strips it from an explicit anchor, so those five headings could not be anchored at all — but slashes made anchors read like paths and curly quotes made them non-ASCII, and neither belongs in a key that Enterprise overlays will be written against. The punctuation is incidental in every case, so the headings say the same thing without it: "Observability & performance" becomes "and", "S3 / GCS / Azure Blob" becomes a comma list, "What's next?" becomes "Next steps". Nothing linked to any of the old anchors, so nothing breaks. Underscores and the plus in `analyze_plan`, `explain_plan`, `max_pooling`, `approx_mode`, `torch_col` and `100B+ row scale` are left alone. Those characters are part of an API name or a quantity rather than punctuation, they are safe in a URL fragment, and renaming them would misname the thing the heading documents. All 810 headings now carry an anchor. The twelve pages whose rendered output changed are exactly the twelve retitled here.
Six headings named an API identifier or a quantity directly — `analyze_plan`, `explain_plan`, `approx_mode`, `torch_col`, `max_pooling`, `100B+ row scale` — so their anchors carried an underscore or a plus. Renaming the identifier would have misnamed what the section documents, so the headings now describe what the section does and the identifier stays in the prose, where it was already being used: `analyze_plan` appears 14 times in that page, `explain_plan` 11, `max_pooling` 9. Nothing about the API is lost, and the heading reads better for it. Every anchor in the corpus is now plain `[a-z0-9-]`.
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.
The A2 anchor pass, complete. All 810 section headings across the authored pages now carry an explicit
{#anchor}— the identity an Enterprise overlay attaches to from A5, and the one thing that survives a heading being reworded.Stacked on #352; merge that first, then retarget this to
mainso CI runs (the Assemble workflow only triggers on pull requests tomain).Anchors are read, not derived
They come from the ids Mintlify already renders, read back from a
mint exportbundle. That is what keeps existing deep links working, and it matters more than it looks — four separate rules would otherwise have had to be reimplemented correctly, and each was found only because the export harness or the alignment guard caught it:## What's next?renders aswhat’s-nextwith a curly apostrophe. A derived slug gavewhat-s-next— silently changing the id### 1. Setuploses its number once an anchor is added; Mintlify re-reads1.as a list marker and drops it from the heading and the TOC&appears as&; writing that back produced...-amp-...Headings retitled so their anchors are clean
Eighteen headings across twelve pages produced anchors containing
&,/, or curly quotes. Ampersands were the pressing case — Mintlify keeps&in a generated id but strips it from an explicit anchor, so those five could not be anchored at all — but slashes made anchors read like paths, and curly quotes made them non-ASCII. Neither belongs in a key overlays are written against.The punctuation was incidental in every case, so the headings say the same thing without it:
Nothing linked to any of the old anchors, so nothing breaks.
Left alone deliberately:
analyze_plan,explain_plan,max_pooling,approx_mode,torch_col,100B+ row scale. Those characters are part of an API name or a quantity rather than punctuation, they are safe in a URL fragment, and renaming them would misname the thing the heading documents.Verified