Chrome build modes
A docs site repeats the same auto-generated chrome (the navbar, footer, and left-nav) on every page, even though those regions are usually identical site-wide.
Use the td.chrome parameter to select one of two build modes:
full(default) renders each page’s chrome on the page itself, ready for any client. Anytd.chromevalue other thansharedis treated asfull, so a typo fails safe.sharedrenders each region on its donor page only 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.
shared mode is in the spirit of the app-shell pattern but
applied to page chrome, where a single region instance is fetched from its
donor page and restored on the client, over an otherwise static multi-page
site.
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.
Donor pages
A region’s donor page is the page on which shared mode renders it; the
other pages carry a placeholder that the browser fills from the donor page.
Clients without JavaScript (some search crawlers included) see only the donor
pages’ chrome. The donors:
- Navbar and footer: each language’s root page (the home page, or
the
docssection page on a doc-rooted site). - Left-nav: the page’s first section, that is, the docs section page; on a
site whose home page has
type: docs(the pre-0.15 shape), the home page, unless the page setstoc_root: true.
What shared mode keeps reachable
The donor pages are chosen to keep chrome links reachable without JavaScript:
- Navbar and footer: their links are config-defined and identical across the
language. The exceptions are the navbar’s optional selectors:
- A version menu with
version_menu_pagelinksrenders per-page links, which the browser restores but a link checker reaches only on the root page. - The language selector links each page’s own translation, which the
destination language’s left-nav already covers; only a full build reaches a
translation hidden from the left-nav (
toc_hide). For the restored selector, see the known differences.
- A version menu with
- Left-nav (computed per page): the docs section page carries the full docs
tree.
sharedmode currently targets the docs section; other sections (such as blog) aren’t a validated target yet, so keepfullfor them.
Known differences from a full build
shared mode is experimental: it rests on assumptions about how chrome
repeats that may not hold for every site. Keep full for production, and run
full-site link checks as well, even if less often.
The restore aims to match a full build, with these exceptions:
- The navbar’s language selector is restored by swapping the language prefix of
the current page’s path (#2689), so:
- A page with no translation in a language gets a live link where a full build disables the item.
- On a doc-rooted site, title-based slugs usually differ across languages, so the restored link misses.
- The restored navbar marks one entry active, the longest match for the current
path, where a full build marks every entry whose page contains it (#2689):
- With nested menu entries, a parent entry loses its active state on pages under a child entry; on a doc-rooted site, the docs entry under any docs subsection with its own entry.
- On a doc-rooted site, the docs entry is active on non-docs pages that no other entry covers, such as taxonomy and 404 pages (its URL, the language root, prefixes every path), where a full build marks none.
- A scoped sidebar (
sidebar_root_for) restores the right links and active state, but its re-rooted subtree differs structurally from a full build (an extra wrapper element, renumberedullevels), which can show as one indentation level less under a non-foldable, non-compact nav. - With
uglyURLs, section URLs end inindex.html, which the restore doesn’t treat as a directory: the version and language selector links keep the donor page’sindex.html, no section menu entry is marked active on pages under it, the out-of-tree active path is empty, and a scoped sidebar’s “up” link points at the directory (#2689). - With
sidebar_menu_compact: trueandsidebar_menu_foldable: false, the restored left-nav opens the current page’s siblings and children only, where a full build also shows the siblings of every ancestor on the active path (#2689).
Setting the build mode
Set the td.chrome parameter to shared (the default is full):
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.
To keep one page’s chrome in a shared build, set the parameter in its front
matter:
td: { chrome: full }
Two limits of the per-page setting:
- It doesn’t make the page complete without JavaScript on a large site: above
sidebar_cache_limit, the left-nav is the cached site-wide one, shipped hidden and revealed by script, onfullpages too. - Below
sidebar_cache_limit, setting it on a left-nav donor page (adocssection page) leaves that page’s own active state in the nav that other pages restore from it: the restored nav then marks both the donor and the current page active.
Feedback
Was this page helpful?
Glad to hear it! Please tell us how we can improve.
Sorry to hear that. Please tell us how we can improve.