fix(docs): scope heading anchors to API documentation only#1228
Merged
Conversation
PR #1227 added rehype-slug + rehype-autolink-headings globally and put the anchor CSS (including a `scroll-margin-top` on every heading with an id) plus clipboard/scroll JS in the shared docs layout. As a result the `#` icon and the scroll override leaked onto every docs page — developers, providers, getting-started, learn, node-operators, AEPs — when the intent was to only ship this on the API documentation section. - Add `apiDocsOnly`, a small unified-plugin wrapper that only delegates to the inner plugin when the markdown vfile is under `src/content/Docs/api-documentation/`. - Wrap both rehype plugins with it in `astro.config.mjs`. - Gate the anchor `<style is:global>` and `<script>` in `docs-layout.astro` behind `Astro.url.pathname.startsWith("/docs/api-documentation/")`. Manual anchor markup on the custom `.astro` pages (`api-documentation/console-api/api-reference.astro`, `api-documentation/getting-started.astro`) is unchanged — those pages already live under the gated path so the layout's CSS + JS still apply.
8 tasks
baktun14
added a commit
that referenced
this pull request
May 26, 2026
…nchors (#1229) * fix(docs): restore hover-only # icons, drop h1 anchors 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. * fix(docs): drop literal <script>/<style> from frontmatter comment 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
Fixes the over-scoped rollout from #1227. The shareable
#heading anchors were meant to ship only on the API documentation section, but the implementation applied globally:rehype-slug+rehype-autolink-headingsran on every MD/MDX file undersrc/content/, so headings underdevelopers/,providers/,node-operators/,getting-started/,learn/, and AEPs (src/content/aeps/) all got the#icon injected.docs-layout.astrounconditionally emitted the anchor CSS (including ascroll-margin-top: 7remrule on every heading with an id) and the clipboard/scroll JS, affecting scroll behaviour across the whole site even on pages with no anchor UI.Changes
src/lib/markdown/apiDocsOnly.ts— a smallunifiedplugin wrapper that no-ops unless the vfile's source path is insidesrc/content/Docs/api-documentation/.astro.config.mjs— wrap both rehype plugins withapiDocsOnly(...).src/layouts/docs-layout.astro— deriveisApiDocs = Astro.url.pathname.startsWith("/docs/api-documentation/")and gate the<style is:global>+<script>behind it.api-documentation/console-api/api-reference.astroandapi-documentation/getting-started.astrois unchanged — both pages already live under the gated path, so the layout's CSS + JS still apply.Test plan
Verified against the production build (
npm run build, 588 pages):heading-anchorcountdocs/developers/contributingdocs/providers/getting-starteddocs/getting-started/...docs/learn/...docs/node-operators/...roadmap/aep-64(and other AEPs)docs/api-documentation/rest-api/gpu-availability-guide(markdown)docs/api-documentation/getting-started(custom.astro)docs/api-documentation/console-api/api-reference(custom.astro)#icon, no scroll-jump on refresh-with-hash#appears on hover, click copies the deep-link URL and shows the green checkgenerateTocuses)npm run buildsucceeds