Companion link

2026.08.18 Navigation

A companion link is a small directional callout that appears near the beginning of a page. Use it when the current page is a focused note, checklist, or runbook and another page explains the broader context.

When to use#

The current page is a focused note, checklist, or runbook, and one other page carries the broader explanation
One primary relationship only — the component answers: “this page is useful on its own, but read that page if you need the larger explanation”
Not for generic recommendations, end-of-page reading lists, or clusters of related articles — declare those in related: front matter instead

Implementation#


  ↩︎
  
    Companion note —
    Cross-references
    explains the three cross-reference mechanisms.

<aside class="companion-link not-prose" aria-label="Companion note">
  <span class="companion-link-icon" aria-hidden="true">↩︎</span>
  <p class="companion-link-copy">
    <span class="meta">Companion note —</span>
    <a href="/en/docs/site-governance/content/cross-references/">Cross-references</a>
    explains the three cross-reference mechanisms.
  </p>
</aside>

The Hugo shortcode is layouts/shortcodes/companion.html. It resolves the target page, displays its title, and adds the localized companion label. A bad path fails the build instead of shipping a dead link. There is no JavaScript; the component’s CSS classes in assets/css/site.css compose the token-backed spacing, colour, and border treatment.

Options#

Option	Purpose
first / `to`	Content path of the target page (required)
`prefix`	Text placed before the link
`label`	Overrides the target page’s title as the link text
inner content	The sentence after the link explaining why the reader should go

Accent#

One accent variant exists: the inline accent — a left vertical line (border-l-2 border-line) with the accent-coloured ↩︎ glyph. There is no bottom-accent option.

Interface manifest

Kind: Component
Category: Navigation
Status: Implemented
Implementation: Shortcode:layouts/shortcodes/companion.htmlCSS:assets/css/site.cssi18n:companionNote

Accessibility#

The component is an <aside> with a localized aria-label (“Companion note”), so screen readers announce it as a named complementary landmark
The ↩︎ glyph is decorative and carries aria-hidden="true"; the visible “Companion note” label, not the glyph, identifies the component
The only interactive element is the single link: Tab reaches it, Enter follows it — there is no JavaScript and no custom key handling
Avoid placing interactive content other than the single link inside the aside; the contract is one destination, and extra controls dilute what the landmark announces