Chrome build modes

A docs site re-emits the same auto-generated chrome — the navbar, footer, and left-nav — on every page, even though those regions are usually identical site-wide. That repetition slows the build, bloats the output, and slows anything that processes every page, such as a link checker; it also makes for noisy output diffs.

Use the td.chrome parameter to select one of two build modes:

• full (default) emits each page’s chrome on the page itself, ready for any client. Any td.chrome value other than shared is treated as full, so a typo fails safe.
• shared emits each region on just one donor page per locale and restores it on the other pages in the browser with a small script. The output stays lean, while readers still get the full navigation once the page loads.

The shared mode helps wherever a JavaScript-capable client or a link checker consumes the output:

• Faster link checking. A checker reaches each unique chrome link once instead of once per page, and sees the lean output because it doesn’t run the restore script.
• Cleaner output diffs. A change to a shared region shows up once instead of on every page, so a diff surfaces the content that actually changed.
• Smaller output for local development and deploy previews.

What shared mode keeps reachable

In shared mode, each region stays on exactly one page per locale — its donor, which the browser restores the others from — so every chrome link stays reachable without JavaScript:

• Navbar and footer: kept on each locale’s home page. Their links are config-defined and identical across the locale, except for the navbar’s optional language selector and version menu — see the caution.
• Left-nav (computed per page): kept on each locale’s docs landing page; it carries the full docs tree. On a doc-rooted site, that landing page is the home page. shared mode currently targets the docs section; other sections (such as blog) aren’t a validated target yet, so keep full for them.

The navbar’s language selector points to each page’s own translation rather than a fixed target, but those translations are docs pages that the destination locale’s left-nav already covers, so the single kept navbar loses no reachable link.

Setting the build mode

Set the td.chrome parameter to shared (the default is full):

• hugo.yaml
• hugo.toml

params:
  td:
    chrome: shared

[params.td]
chrome = "shared"

For a link-checking or preview CI job, it’s usually cleaner to set it through the environment instead, leaving your committed config untouched:

HUGO_PARAMS_TD_CHROME=shared hugo

See Hugo’s configuration with environment variables. Then run your link checker against the generated public/ output as usual: a shared build needs no checker-specific configuration, since the donor pages keep every chrome link reachable.