Sidebar link highlighting and heading ID utilities enhance documentation consistency

The documentation build now correctly highlights sidebar items for section roots, provides a shared heading‑ID filter for deep links, and removes obsolete width utilities, improving consistency across the site.

背景

Accurate sidebar navigation is essential for readers to recognize their current location, especially when a page belongs to a broader section. Previously, the current‑link transformer only matched exact URLs, causing section‑root items to lose their active state when viewing child pages. Additionally, deep‑linking to headings required ad‑hoc string manipulation in templates, leading to potential mismatches between generated anchors and link targets. These inconsistencies motivated a unified approach.

技術的な変更

Sidebar current‑link logic was expanded to treat URLs ending with / as section roots. By normalising both the link and page URL and checking whether the page URL starts with the section root plus a slash, the transformer now activates the parent item for any descendant page while preserving exact‑match behavior for regular links.

@@
-  if (normalize(href) === normalize(pageUrl)) {
-    el.classList.add(className);
-  }
+  const normalizedHref = normalize(href);
+  const normalizedPageUrl = normalize(pageUrl);
+  const isSectionLink = href.endsWith('/') && href !== '/';
+  const isExactMatch = normalizedHref === normalizedPageUrl;
+  const isChildOfSection = isSectionLink && normalizedPageUrl.startsWith(normalizedHref + '/');
+  if (isExactMatch || isChildOfSection) {
+    el.classList.add(className);
+  }

A shared heading‑ID helper was extracted from the anchor‑headings transformer and exported as createId. The Eleventy configuration now imports this function and registers a Nunjucks filter named headingId, allowing templates to generate the same slug as the transformer.

@@
-import { anchorHeadingsTransformer } from './_transformers/anchor-headings.js';
+import { anchorHeadingsTransformer, createId } from './_transformers/anchor-headings.js';
@@
+  // Generates the same heading anchor id used by anchorHeadingsTransformer, so links can target headings reliably
+  eleventyConfig.addFilter('headingId', content => createId(String(content ?? '')));

Template updates now utilize the new filter. In component-badges.njk, the changelog “Since” badge constructs its anchor with {{ sinceVersion | headingId }} instead of manually prefixing wa_. The sidebar markup was simplified by removing the experimental badge wrapper and applying a unified wa-cluster wa-gap-xs class pattern.

@@
-    <span class="wa-split">
-      <a href="/docs/ssr">Server Rendering</a>
-      <wa-badge
-        variant="warning"
-        appearance="filled"
-        pill
-      ><wa-icon label="Experimental" name="flask"></wa-icon></wa-badge>
-    </span>
+    <a class="wa-cluster wa-gap-xs" href="/docs/ssr">
+      Server Rendering
+      <wa-icon name="flask" aria-hidden="true" class="icon-shrink de-emphasize"></wa-icon>
+    </a>

Several CSS and layout clean‑ups were performed: the .page-wide rule and its associated max‑inline‑size adjustments were removed; the now‑unused wide: true front‑matter flag was dropped from the visual‑tests page; utility classes were harmonised (wa-text-center replaces inline style="text-align: center;"). These changes eliminate dead code and align naming conventions across the stylesheet.

@@
-.page-wide {
-  wa-page > main {
-    max-inline-size: var(--content-width-l);
-
-    .max-line-length {
-      max-inline-size: var(--line-length-l);
-    }
-  }
-}

設計判断

The team opted to extend existing utilities rather than introduce new ones. By exporting createId and adding a filter, the same slugging algorithm is reused across both content transformation and template rendering, guaranteeing consistency without duplication. The sidebar’s link‑matching logic was enhanced with minimal branching, preserving the original exact‑match path while adding a clear child‑of‑section check. CSS clean‑ups were performed conservatively, removing only rules that were no longer referenced, which reduces bundle size and maintenance overhead.

まとめ

This PR tightens the documentation experience: sidebar items now stay highlighted throughout a section, heading anchors are generated via a single source of truth, and obsolete width utilities are eliminated. The changes improve navigational clarity and reduce technical debt in the documentation build pipeline.