@levino/shipyard-base 0.9.3-rc-20260926183647 → 0.9.3

package/astro/components/AnnouncementBar.astro

@@ -1,4 +1,5 @@
 ---
+import { useUiStrings } from '../../src/i18n'
 import type { AnnouncementBar } from '../../src/schemas/config'
 
 interface Props {
@@ -6,6 +7,7 @@ interface Props {
 }
 
 const { config } = Astro.props
+const t = useUiStrings(Astro.currentLocale)
 const {
   id = 'announcement-bar',
   content,
@@ -67,7 +69,7 @@ const customStyle = [
       <button
         type="button"
         class="announcement-close absolute right-2 top-1/2 -translate-y-1/2 p-1 hover:opacity-70 transition-opacity"
-        aria-label="Close announcement"
+        aria-label={t.closeAnnouncement}
         data-announcement-id={id}
       >
         <svg

package/astro/components/GlobalDesktopNavigation.astro

@@ -1,4 +1,5 @@
 ---
+import { useUiStrings } from '../../src/i18n'
 import type { Config } from '../../src/schemas/config'
 import { cn } from '../../src/tools/cn'
 import LanguageSwitcher from './LanguageSwitcher.astro'
@@ -7,15 +8,16 @@ import ThemeToggle from './ThemeToggle.astro'
 type Props = Pick<Config, 'brand' | 'navigation'> & { showBrand: boolean }
 
 const { brand, navigation, showBrand = false } = Astro.props as Props
+const t = useUiStrings(Astro.currentLocale)
 ---
 
 <div class="navbar z-10 bg-base-100">
   <span
     class="tooltip tooltip-bottom before:text-xs before:content-[attr(data-tip)]"
-    data-tip="Menu"
+    data-tip={t.menu}
   >
     <label
-      aria-label="Open menu"
+      aria-label={t.openMenu}
       for="drawer"
       class="btn btn-square btn-ghost drawer-button lg:hidden"
     >

package/astro/components/SidebarNavigation.astro

@@ -1,4 +1,5 @@
 ---
+import { useUiStrings } from '../../src/i18n'
 import { cn } from '../../src/tools/cn'
 import LanguageSwitcher from './LanguageSwitcher.astro'
 import SidebarElement from './SidebarElement.astro'
@@ -12,6 +13,7 @@ interface Props {
 }
 
 const { local, global, brand } = Astro.props
+const t = useUiStrings(Astro.currentLocale)
 
 const withLocale = (path: string) =>
   Astro.currentLocale ? `/${Astro.currentLocale}${path}` : path
@@ -31,7 +33,7 @@ const withLocale = (path: string) =>
       {
         local ? (
           <details>
-            <summary>Main menu</summary>
+            <summary>{t.mainMenu}</summary>
             <SidebarElement entry={global} />
           </details>
         ) : (
@@ -42,7 +44,7 @@ const withLocale = (path: string) =>
     <slot name="sidebarExtra" />
     <LanguageSwitcher variant="list" />
     <li class="flex flex-row items-center gap-2 px-4 py-2">
-      <span class="text-sm opacity-70">Theme</span>
+      <span class="text-sm opacity-70">{t.theme}</span>
       <ThemeToggle />
     </li>
     <div class={cn("divider my-1 block lg:hidden", { hidden: !local })}></div>

package/astro/components/TableOfContents.astro

@@ -1,4 +1,5 @@
 ---
+import { useUiStrings } from '../../src/i18n'
 import { cn } from '../../src/tools/cn'
 
 interface Link {
@@ -16,7 +17,7 @@ interface Props {
 
 const {
   links,
-  label = 'On this page',
+  label = useUiStrings(Astro.currentLocale).onThisPage,
   class: className,
   desktopOnly = false,
 } = Astro.props

package/astro/components/Tabs.astro

@@ -18,6 +18,7 @@
  * </Tabs>
  * ```
  */
+import { useUiStrings } from '../../src/i18n'
 
 interface Props {
   /**
@@ -39,6 +40,7 @@ interface Props {
 }
 
 const { items, groupId, queryString, defaultValue } = Astro.props
+const t = useUiStrings(Astro.currentLocale)
 
 const tabId = `tabs-${Math.random().toString(36).slice(2, 9)}`
 const defaultTab = defaultValue ?? items[0]
@@ -50,7 +52,7 @@ const defaultTab = defaultValue ?? items[0]
   data-group-id={groupId}
   data-query-string={queryString === true ? groupId : (queryString || undefined)}
 >
-  <div class="shipyard-tabs-list" role="tablist" aria-label="Content tabs">
+  <div class="shipyard-tabs-list" role="tablist" aria-label={t.contentTabs}>
     {items.map((item, index) => (
       <button
         type="button"

package/astro/layouts/Markdown.astro

@@ -1,5 +1,6 @@
 ---
 import type { ImageMetadata } from 'astro'
+import { useUiStrings } from '../../src/i18n'
 import type { NavigationTree } from '../../src/schemas/config'
 import Base from './Page.astro'
 
@@ -50,6 +51,7 @@ type Props = {
 }
 
 const props = Astro.props
+const t = useUiStrings(Astro.currentLocale)
 const frontmatter = props.frontmatter
 
 // Check if this is a draft page in production
@@ -89,7 +91,7 @@ const allMetaTags = [
 <Base {...pageProps} customMetaTags={allMetaTags}>
   {isDraft && (
     <div class="alert alert-warning mb-4">
-      <span>This page is a draft and will not be visible in production.</span>
+      <span>{t.draftNotice}</span>
     </div>
   )}
   <div class={wrapperClass}><slot /></div>

package/astro/layouts/Page.astro

@@ -5,6 +5,7 @@ import { i18n } from 'astro:config/server'
 import config from 'virtual:shipyard/config'
 import type { ImageMetadata } from 'astro'
 import { mapObjIndexed } from 'ramda'
+import { getPageLocale, getUiStrings } from '../../src/i18n'
 import type {
   NavigationEntry,
   NavigationTree,
@@ -114,9 +115,11 @@ const navigation = applyLocaleAndSetActive(config.navigation)
 const title = getTitle(config.title, props.title)
 const hasSidebar = !!props.sidebarNavigation
 
-// Language for the <html> element: current locale on i18n sites, otherwise the
-// configured default locale (omitted entirely when i18n is disabled).
-const htmlLang = Astro.currentLocale ?? (i18n ? i18n.defaultLocale : undefined)
+// Language for the <html> element and shipyard's UI labels: current locale on
+// i18n sites, otherwise the i18n default locale, otherwise `locale` from the
+// shipyard config (omitted entirely when none is set).
+const htmlLang = getPageLocale(Astro.currentLocale)
+const t = getUiStrings(htmlLang)
 
 // Absolute URL of the current page (no query string), used for og:url and as
 // the self-referential canonical when no explicit canonicalUrl is provided.
@@ -202,12 +205,12 @@ const renderScriptAttributes = (script: Script) => {
       href="#main-content"
       class="sr-only focus:not-sr-only focus:absolute focus:left-4 focus:top-4 focus:z-50 btn btn-primary btn-sm"
     >
-      {config.skipToContentLabel ?? 'Skip to content'}
+      {config.skipToContentLabel ?? t.skipToContent}
     </a>
     {config.announcementBar && <AnnouncementBar config={config.announcementBar} />}
     <div class={cn("drawer grow", { "lg:drawer-open": hasSidebar })}>
       <input id="drawer" type="checkbox" class="drawer-toggle" />
-      <div class="drawer-content flex flex-col overflow-x-hidden">
+      <div class="drawer-content flex flex-col overflow-x-clip">
         <GlobalDesktopNavigation
           showBrand={!hasSidebar}
           brand={config.brand}
@@ -223,7 +226,7 @@ const renderScriptAttributes = (script: Script) => {
       </div>
 
       <div class="drawer-side z-40">
-        <label for="drawer" aria-label="close sidebar" class="drawer-overlay"
+        <label for="drawer" aria-label={t.closeSidebar} class="drawer-overlay"
         ></label>
         <SidebarNavigation
           brand={config.brand}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@levino/shipyard-base",
-  "version": "0.9.3-rc-20260926183647",
+  "version": "0.9.3",
   "description": "Core layouts, components, and configuration for shipyard - a composable page builder for Astro",
   "keywords": [
     "astro",
@@ -32,6 +32,7 @@
     "./layouts/*": "./astro/layouts/*",
     "./components": "./astro/components/index.ts",
     "./components/*": "./astro/components/*",
+    "./i18n": "./src/i18n/index.ts",
     "./remark": "./src/remark/index.ts",
     "./shiki": "./src/shiki/index.ts",
     "./globals.css": "./src/globals.css",
@@ -56,10 +57,13 @@
     "@tailwindcss/typography": "^0.5.20",
     "@types/ramda": "^0.32",
     "daisyui": "^5",
+    "hast-util-from-html": "^2.0.3",
+    "hast-util-to-html": "^9.0.5",
     "remark": "^15.0.1",
     "remark-html": "^16.0.1",
     "tailwindcss": "^4",
     "typescript": "^7.0.2",
+    "vfile": "^6.0.3",
     "vite": "^8.3.1",
     "vitest": "^5.0.2"
   },

package/src/i18n/index.ts

@@ -0,0 +1,23 @@
+import { i18n } from 'astro:config/server'
+import config from 'virtual:shipyard/config'
+import { getUiStrings, resolveLocale } from './ui'
+
+export type { UiStringKey, UiStrings } from './ui'
+export { formatUiString, getUiStrings, resolveLocale, uiStrings } from './ui'
+
+/**
+ * Locale of the page being rendered. Pass `Astro.currentLocale`.
+ */
+export const getPageLocale = (currentLocale: string | undefined) =>
+  resolveLocale({
+    currentLocale,
+    i18nDefaultLocale: i18n?.defaultLocale,
+    configLocale: config.locale,
+  })
+
+/**
+ * shipyard's UI labels in the language of the page being rendered.
+ * Pass `Astro.currentLocale`.
+ */
+export const useUiStrings = (currentLocale: string | undefined) =>
+  getUiStrings(getPageLocale(currentLocale))

package/src/i18n/ui.test.ts

@@ -0,0 +1,57 @@
+import { describe, expect, it } from 'vitest'
+import { formatUiString, getUiStrings, resolveLocale, uiStrings } from './ui'
+
+describe('getUiStrings', () => {
+  it('returns English labels without a locale', () => {
+    expect(getUiStrings(undefined).onThisPage).toBe('On this page')
+  })
+
+  it('returns German labels for de', () => {
+    expect(getUiStrings('de').onThisPage).toBe('Auf dieser Seite')
+  })
+
+  it('falls back from a region subtag to the language', () => {
+    expect(getUiStrings('de-AT').onThisPage).toBe('Auf dieser Seite')
+    expect(getUiStrings('DE').next).toBe('Weiter')
+  })
+
+  it('falls back to English for unknown languages', () => {
+    expect(getUiStrings('xx').onThisPage).toBe('On this page')
+  })
+
+  it('has the same keys in every language', () => {
+    const keys = Object.keys(uiStrings.en).sort()
+    for (const strings of Object.values(uiStrings)) {
+      expect(Object.keys(strings).sort()).toEqual(keys)
+    }
+  })
+})
+
+describe('resolveLocale', () => {
+  it('prefers the current route locale', () => {
+    expect(
+      resolveLocale({
+        currentLocale: 'en',
+        i18nDefaultLocale: 'de',
+        configLocale: 'fr',
+      }),
+    ).toBe('en')
+  })
+
+  it('falls back to the i18n default locale, then the config locale', () => {
+    expect(resolveLocale({ i18nDefaultLocale: 'de', configLocale: 'fr' })).toBe(
+      'de',
+    )
+    expect(resolveLocale({ configLocale: 'de' })).toBe('de')
+    expect(resolveLocale({})).toBeUndefined()
+  })
+})
+
+describe('formatUiString', () => {
+  it('fills placeholders and keeps unknown ones', () => {
+    expect(formatUiString('von {author}', { author: 'Levin' })).toBe(
+      'von Levin',
+    )
+    expect(formatUiString('{missing}', {})).toBe('{missing}')
+  })
+})

package/src/i18n/ui.ts

@@ -0,0 +1,85 @@
+/**
+ * Built-in labels of shipyard's UI (table of contents, navigation, docs
+ * footer, …). Pure data and helpers so they can be unit-tested; the Astro
+ * glue that picks the page's locale lives in `./index.ts`.
+ */
+export const uiStrings = {
+  en: {
+    onThisPage: 'On this page',
+    skipToContent: 'Skip to content',
+    menu: 'Menu',
+    openMenu: 'Open menu',
+    closeSidebar: 'Close sidebar',
+    mainMenu: 'Main menu',
+    theme: 'Theme',
+    previous: 'Previous',
+    next: 'Next',
+    docsNavigation: 'Docs navigation',
+    lastUpdated: 'Last updated:',
+    lastUpdatedBy: 'by {author}',
+    editThisPage: 'Edit this page',
+    draftNotice: 'This page is a draft and will not be visible in production.',
+    closeAnnouncement: 'Close announcement',
+    contentTabs: 'Content tabs',
+  },
+  de: {
+    onThisPage: 'Auf dieser Seite',
+    skipToContent: 'Zum Inhalt springen',
+    menu: 'Menü',
+    openMenu: 'Menü öffnen',
+    closeSidebar: 'Seitenleiste schließen',
+    mainMenu: 'Hauptmenü',
+    theme: 'Design',
+    previous: 'Zurück',
+    next: 'Weiter',
+    docsNavigation: 'Navigation in der Dokumentation',
+    lastUpdated: 'Zuletzt aktualisiert:',
+    lastUpdatedBy: 'von {author}',
+    editThisPage: 'Diese Seite bearbeiten',
+    draftNotice:
+      'Diese Seite ist ein Entwurf und erscheint nicht in der Produktion.',
+    closeAnnouncement: 'Ankündigung schließen',
+    contentTabs: 'Inhalts-Tabs',
+  },
+} as const satisfies Record<string, Record<string, string>>
+
+export type UiStringKey = keyof (typeof uiStrings)['en']
+export type UiStrings = Record<UiStringKey, string>
+
+export const defaultUiLocale = 'en'
+
+/**
+ * Returns the UI labels for a locale. Region subtags fall back to the
+ * language (`de-AT` → `de`); unknown languages fall back to English.
+ */
+export const getUiStrings = (locale: string | undefined): UiStrings => {
+  if (!locale) return uiStrings.en
+  const normalized = locale.toLowerCase()
+  const language = normalized.split('-')[0] ?? normalized
+  const strings =
+    (uiStrings as Record<string, UiStrings>)[normalized] ??
+    (uiStrings as Record<string, UiStrings>)[language]
+  return strings ?? uiStrings.en
+}
+
+/**
+ * The locale a page is rendered in: the current i18n route locale, else
+ * Astro's i18n default locale, else the `locale` set in the shipyard config.
+ * `undefined` when none of them is set.
+ */
+export const resolveLocale = ({
+  currentLocale,
+  i18nDefaultLocale,
+  configLocale,
+}: {
+  currentLocale?: string | undefined
+  i18nDefaultLocale?: string | undefined
+  configLocale?: string | undefined
+}): string | undefined => currentLocale ?? i18nDefaultLocale ?? configLocale
+
+/** Replaces `{name}` placeholders in a label. */
+export const formatUiString = (
+  template: string,
+  values: Record<string, string>,
+): string =>
+  template.replace(/\{(\w+)\}/g, (match, key: string) => values[key] ?? match)

package/src/markdownProcessor.test.ts

@@ -11,6 +11,7 @@ import shipyard from './index'
 import type { Config } from './schemas/config'
 
 const SHIPYARD_PLUGIN_COUNT = 3
+const SHIPYARD_REHYPE_PLUGIN_COUNT = 1
 
 interface ConfigUpdate {
   markdown?: {
@@ -58,6 +59,9 @@ describe('markdown processor', () => {
     expect(update?.markdown?.processor?.options.remarkPlugins).toHaveLength(
       SHIPYARD_PLUGIN_COUNT,
     )
+    expect(update?.markdown?.processor?.options.rehypePlugins).toHaveLength(
+      SHIPYARD_REHYPE_PLUGIN_COUNT,
+    )
     expect(logger.warn).not.toHaveBeenCalled()
   })
 
@@ -69,13 +73,20 @@ describe('markdown processor', () => {
 
   test("keeps the user's own plugins on an existing unified processor", () => {
     const userPlugin = () => undefined
+    const userRehypePlugin = () => undefined
     const { update, logger } = runConfigSetup(
-      unified({ remarkPlugins: [userPlugin] }),
+      unified({
+        remarkPlugins: [userPlugin],
+        rehypePlugins: [userRehypePlugin],
+      }),
     )
 
     const plugins = update?.markdown?.processor?.options.remarkPlugins
     expect(plugins).toHaveLength(SHIPYARD_PLUGIN_COUNT + 1)
     expect(plugins?.[0]).toBe(userPlugin)
+    const rehypePlugins = update?.markdown?.processor?.options.rehypePlugins
+    expect(rehypePlugins).toHaveLength(SHIPYARD_REHYPE_PLUGIN_COUNT + 1)
+    expect(rehypePlugins?.[0]).toBe(userRehypePlugin)
     expect(logger.warn).not.toHaveBeenCalled()
   })
 

package/src/markdownProcessor.ts

@@ -2,6 +2,7 @@ import { isDeepStrictEqual } from 'node:util'
 import { isUnifiedProcessor, unified } from '@astrojs/markdown-remark'
 import { satteri } from '@astrojs/markdown-satteri'
 import type { AstroConfig, AstroIntegrationLogger } from 'astro'
+import { rehypeHeadingLinks } from './rehype/rehypeHeadingLinks'
 import { remarkAdmonitions } from './remark/remarkAdmonitions'
 import { remarkBlockDirective } from './remark/remarkBlockDirective'
 import { remarkNpm2Yarn } from './remark/remarkNpm2Yarn'
@@ -14,6 +15,8 @@ const shipyardRemarkPlugins = [
   remarkNpm2Yarn,
 ]
 
+const shipyardRehypePlugins = [rehypeHeadingLinks]
+
 // Astro fills in a fresh `satteri()` when `markdown.processor` is unset, so
 // the resolved config cannot tell that default apart from an explicit bare
 // `satteri()`. Both render identically, so both count as "not chosen".
@@ -27,7 +30,8 @@ const isAstroDefault = (processor: MarkdownProcessor) => {
 
 /**
  * shipyard's admonitions, npm2yarn tabs and block directives are remark
- * plugins, and only the `unified()` processor runs those.
+ * plugins, and the linked headings a rehype plugin; only the `unified()`
+ * processor runs those.
  *
  * - Astro's default processor is replaced with `unified()` carrying the
  *   shipyard plugins.
@@ -49,11 +53,18 @@ export const shipyardMarkdownProcessor = (
         ...current.options.remarkPlugins,
         ...shipyardRemarkPlugins,
       ],
+      rehypePlugins: [
+        ...current.options.rehypePlugins,
+        ...shipyardRehypePlugins,
+      ],
     })
   }
 
   if (isAstroDefault(current)) {
-    return unified({ remarkPlugins: shipyardRemarkPlugins })
+    return unified({
+      remarkPlugins: shipyardRemarkPlugins,
+      rehypePlugins: shipyardRehypePlugins,
+    })
   }
 
   logger.warn(

package/src/rehype/rehypeHeadingLinks.test.ts

@@ -0,0 +1,56 @@
+import { fromHtml } from 'hast-util-from-html'
+import { toHtml } from 'hast-util-to-html'
+import { unified } from 'unified'
+import { VFile } from 'vfile'
+import { describe, expect, it } from 'vitest'
+import { rehypeHeadingLinks } from './rehypeHeadingLinks'
+
+const run = async (html: string) => {
+  const processor = unified().use(rehypeHeadingLinks)
+  const tree = await processor.run(
+    fromHtml(html, { fragment: true }),
+    new VFile(),
+  )
+  return toHtml(tree)
+}
+
+describe('rehypeHeadingLinks', () => {
+  it('links h2 to h4 to their own anchor', async () => {
+    expect(await run('<h2>Getting started</h2><h4>Fine print</h4>')).toBe(
+      '<h2 id="getting-started"><a href="#getting-started" class="heading-link">Getting started</a></h2>' +
+        '<h4 id="fine-print"><a href="#fine-print" class="heading-link">Fine print</a></h4>',
+    )
+  })
+
+  it('keeps existing ids and uses them as the link target', async () => {
+    expect(await run('<h3 id="custom">Title</h3>')).toBe(
+      '<h3 id="custom"><a href="#custom" class="heading-link">Title</a></h3>',
+    )
+  })
+
+  it('creates the same slugs as Astro, including umlauts and duplicates', async () => {
+    const html = await run(
+      '<h2>Vorgaben fürs Angebot</h2><h2>Vorgaben fürs Angebot</h2>',
+    )
+    expect(html).toContain('href="#vorgaben-fürs-angebot"')
+    expect(html).toContain('href="#vorgaben-fürs-angebot-1"')
+  })
+
+  it('keeps inline markup inside the link', async () => {
+    expect(await run('<h2>Use <code>npm</code></h2>')).toBe(
+      '<h2 id="use-npm"><a href="#use-npm" class="heading-link">Use <code>npm</code></a></h2>',
+    )
+  })
+
+  it('leaves h1, h5 and h6 alone', async () => {
+    expect(await run('<h1>Title</h1><h5>Small</h5>')).toBe(
+      '<h1 id="title">Title</h1><h5 id="small">Small</h5>',
+    )
+  })
+
+  it('does not nest links', async () => {
+    expect(await run('<h2><a href="/x">Linked</a></h2>')).toBe(
+      '<h2 id="linked"><a href="/x">Linked</a></h2>',
+    )
+  })
+})

package/src/rehype/rehypeHeadingLinks.ts

@@ -0,0 +1,50 @@
+import { rehypeHeadingIds } from '@astrojs/markdown-remark'
+import type { Element, ElementContent, Root } from 'hast'
+import type { Plugin } from 'unified'
+import { visit } from 'unist-util-visit'
+
+/** Headings that get a link to their own anchor. */
+const LINKED_HEADINGS = new Set(['h2', 'h3', 'h4'])
+
+/** CSS class of the link that wraps a heading's content. */
+export const HEADING_LINK_CLASS = 'heading-link'
+
+const containsLink = (nodes: ElementContent[]): boolean =>
+  nodes.some(
+    (node) =>
+      node.type === 'element' &&
+      (node.tagName === 'a' || containsLink(node.children)),
+  )
+
+/**
+ * Turns the content of every `h2`–`h4` into a link to the heading's own
+ * anchor (`<h2 id="setup"><a href="#setup" class="heading-link">Setup</a></h2>`),
+ * so readers can click a heading and copy its URL from the address bar.
+ *
+ * Heading IDs are normally added by Astro after all user rehype plugins have
+ * run. This plugin adds them first with Astro's own `rehypeHeadingIds`, so the
+ * IDs, the slugs in the table of contents and the link targets stay
+ * identical. Headings that already contain a link are left alone, because
+ * links cannot be nested.
+ */
+export const rehypeHeadingLinks: Plugin<[], Root> = () => {
+  const addIds = rehypeHeadingIds()
+  return (tree, file) => {
+    // Astro's transformer is synchronous; the callback is never needed.
+    addIds?.(tree, file, () => {})
+    visit(tree, 'element', (node: Element) => {
+      if (!LINKED_HEADINGS.has(node.tagName)) return
+      const id = node.properties?.id
+      if (typeof id !== 'string' || id === '') return
+      if (node.children.length === 0 || containsLink(node.children)) return
+      node.children = [
+        {
+          type: 'element',
+          tagName: 'a',
+          properties: { href: `#${id}`, className: [HEADING_LINK_CLASS] },
+          children: node.children,
+        },
+      ]
+    })
+  }
+}

package/src/schemas/config.ts

@@ -226,9 +226,20 @@ export interface Config {
    * @example 'https://example.com/og.jpg'
    */
   defaultImage?: string
+  /**
+   * Language of the site when Astro's `i18n` routing is not configured, as a
+   * BCP 47 tag (e.g. `'de'`). Sets `<html lang>` and the language of
+   * shipyard's built-in labels such as "On this page", "Next" or
+   * "Edit this page" (English and German ship with shipyard; other languages
+   * fall back to English). With `i18n` configured, the route's locale wins.
+   *
+   * @example 'de'
+   */
+  locale?: string
   /**
    * Label for the accessibility "skip to content" link, rendered as the first
-   * focusable element on every page. Set this to localize it.
+   * focusable element on every page. Overrides the built-in label for the
+   * page's locale.
    * @default 'Skip to content'
    */
   skipToContentLabel?: string

package/src/styles/components.css

@@ -18,6 +18,35 @@
     @apply block overflow-x-auto;
   }
 
+  /*
+   * Linked headings (rehypeHeadingLinks): the whole heading links to its own
+   * anchor. It keeps the heading's look; a "#" fades in on hover and keyboard
+   * focus. The "#" always takes its space, so nothing shifts, and its empty
+   * alt text keeps it out of the link's accessible name.
+   */
+  .prose :where(h1, h2, h3, h4, h5, h6)[id] {
+    scroll-margin-top: 5rem;
+  }
+
+  .prose a.heading-link {
+    color: inherit;
+    font-weight: inherit;
+    text-decoration: none;
+  }
+
+  .prose a.heading-link::after {
+    content: "#" / "";
+    margin-inline-start: 0.35em;
+    color: var(--color-primary);
+    opacity: 0;
+    transition: opacity 0.15s;
+  }
+
+  .prose a.heading-link:hover::after,
+  .prose a.heading-link:focus-visible::after {
+    opacity: 1;
+  }
+
   /* Admonitions / Callouts */
   .admonition {
     @apply my-4 rounded-lg border-l-4 p-4;