fix(docs): restore hover-only # icons on API docs headings; drop h1 anchors#1229
Merged
Conversation
PR #1228 wrapped the heading-anchor `<style is:global>` and `<script>` in `{isApiDocs && (<tag>{`...`}</tag>)}` JSX conditionals with the CSS/JS body inside a template literal. Astro's build mangles that pattern: the production stylesheet truncated to `.heading-anchor { .heading-anchor:hover,` (so the default `opacity: 0` rule was missing and # icons rendered fully visible), and the clipboard/scrollToHash script was dropped from the page entirely (so refresh-with-hash stopped working). Move the style and script into a dedicated child component with raw tag bodies (no template literals); the layout just renders `{isApiDocs && <HeadingAnchorAssets />}`. Astro processes the tags correctly through the component boundary. While here, drop the `<a class="heading-anchor">` wrapper from the page-title `<h1>`s on `api-reference.astro` and `getting-started.astro` — anchoring to the page URL itself is meaningless — and configure `rehype-autolink-headings` with `test: ["h2", ..., "h6"]` so MD/MDX h1s skip the anchor too.
Astro's component parser was matching the literal `<script>` text inside the frontmatter JS comment as a real script-tag opening, sliding the script body's start into the comment text and feeding "tags directly — wrapping them inside a JSX…" to esbuild, which then failed: `Expected ";" but found "directly"`. Production `astro build` happened to ignore it; `astro dev` (Vite dep scan) surfaced the error. Rewrite the comment without literal tag names.
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.
Summary
<style is:global>and<script>blocks indocs-layout.astroinside{isApiDocs && (<tag>{…}</tag>)}JSX conditionals with the CSS/JS body inside a template literal. Astro's build pipeline mangles that pattern — the production stylesheet for/docs/api-documentation/console-api/api-reference/truncated to.heading-anchor { .heading-anchor:hover,(missing theopacity: 0default, so the#icons rendered fully visible all the time), and the clipboard/scrollToHashscript was dropped from the page entirely (so refresh-with-hash no longer scrolled to the target).src/components/docs/heading-anchor-assets.astrowith raw<style>/<script>bodies (no template literals). The layout becomes{isApiDocs && <HeadingAnchorAssets />}. Astro processes the tags correctly through the component boundary.<a class="heading-anchor">wrapper from the page-title<h1>s on the two custom.astroapi-docs pages — anchoring to the URL of the page you're already on is meaningless — and configurerehype-autolink-headingswithtest: ["h2","h3","h4","h5","h6"]so MD/MDX# H1would also be skipped if anyone adds one.Test plan
Verified in headless Chromium against
astro previewover the freshly builtdist/:dist/_astro/_slug_.KcU_Tvib.csscontains the full ruleset, including.heading-anchor-icon{opacity:0…},:where(h1..h6):hover .heading-anchor-icon{opacity:.45},.heading-anchor:hover .heading-anchor-icon{opacity:.85}. Previously truncated in production.dist/_astro/hoisted.BkIvRzCB.jscontains thedata-anchor-linkclick handler +scrollToHash+hashchangelistener. Previously absent in production./docs/api-documentation/console-api/api-reference/— fresh load, mouse off: all 8 sampled.heading-anchor-iconcomputedopacity: 0(hidden). Hover oneh2→ only that icon becomes visible. Others stay at 0.#next to "Authentication" → URL updates to#authentication, full deep link copied to clipboard, section scrolls into view.…/api-reference/#authentication→ section lands 249px from viewport top, well below the sticky docs header (was stuck behind it on production)./docs/api-documentation/getting-started/— same checks pass; main h1 "API Documentation" has no#icon at all./docs/api-documentation/sdk/quick-start/(MD/MDX route) — h1 has no anchor (testoption works); h2–h6 do; default opacity 0; hover reveals./(marketing home),/roadmap/2026/,/roadmap/aep-1/,/privacy/: zero.heading-anchormarkup, zeroscroll-margin-topon[id]headings, anchor-click JS bundle not loaded. Non-api/docs/**pages share the docs layout — they get a 112pxscroll-margin-topon id-bearing headings (offsets refresh-scroll below the sticky header — an improvement) and load the JS bundle inertly.