This document explains how the site selects navigation, renders pages, and applies shared styles and browser behavior. Use it when changing templates, registering a product, or investigating a layout problem. For content authoring, see COMPONENTS.md. For the API generation pipeline, see hack/api-docs/README.md.
Hugo builds the site from content/, mounted upstream content, and generated API
presentation data. layouts/ renders that effective content tree. Product pages
remain under content/manuals/ in source; hugo.yaml strips the /manuals prefix
from published product URLs. Internal source references retain that prefix.
The section at content/manuals/_index.md remains part of the content tree but
doesn't render a directory page. Its former /manuals/ URL redirects to /c/,
which lists documentation categories. /get-docker/ provides installation paths;
installation aliases redirect there. Tutorials and learning paths are built by
docker/learn and served at /learn/.
The former Guides and Get started trees, their layouts, and their exclusive
assets have been removed. data/redirects.yml maps verified equivalents and
their historical aliases directly to Learn. Pages without equivalents have no
replacement redirect. Learn owns its content, navigation, and assets; this Hugo
site links to it without importing or building its pages.
Vendored CLI data, mounted content, and upstream API specifications keep their
existing update workflows. Template changes must work with Hugo's mounted and
generated pages as well as files present directly in content/.
Three files define navigation collections:
| File | Responsibility |
|---|---|
| products.json | Product IDs, source roots, labels, categories, and related-reference links |
| references.json | Reference-family roots and labels |
| categories.json | Category labels, landing URLs, homepage cards, and category-page grouping |
These files identify collection boundaries. Hugo's content tree supplies the pages within each collection. Adding a page below an existing root doesn't require adding it to a registry.
To register a product, add its existing source root to products.json. Add its ID
to a category group to expose it in discovery pages. A product omitted from those
groups still has local navigation. A category entry with page instead of
collection adds a shortcut without changing ownership.
To register a reference family, add its root to references.json and include that
root in the appropriate products' references lists. The build checks that roots
and reference destinations exist, product roots aren't duplicated, categories
are valid, and reference families have product entry points. See
validate.html.
context.html finds the most specific
declared root that is the current page or one of its Hugo ancestors. Callers cache
the result per page using partialCached. Matching uses Hugo page identity and
ancestry, so published URL rewriting doesn't determine sidebar ownership.
For example, /reference/api/engine is a declared reference root. Its sidebar
starts there and contains its descendants. A nested product such as MCP Catalog
and Toolkit can have its own sidebar within the Desktop source tree because the
more specific product root takes precedence.
Reference pages derive their category from products that list the selected reference root. reference-category.html caches this result per root. Multiple products can share a reference: if their categories agree, that category supplies the active top navigation, breadcrumb, and wash. Conflicting or missing categories leave the category unset. This doesn't assign a single product owner to the reference or change its sidebar.
The resolver has these explicit exceptions:
- Docker CLI descendants share the complete
/reference/cli/dockercommand tree, including commands associated with other reference families or categories. - Discovery pages omit the local section sidebar. Generated API pages use the API navigation described under Page layouts.
- A page without a declared root or an applicable exception has no local sidebar.
navigation/breadcrumbs.html
resolves the category and published ancestors once per page. The visible
breadcrumb, structured BreadcrumbList, and Pagefind section metadata use this
same trail. Source-only ancestors such as Manuals don't appear in it.
sidebar.html renders the overview
link, tree, and related-reference links.
tree.html recursively walks Hugo's
.Pages; children.html filters the
children used both for rendering and for deciding whether to show an expand
control.
Front matter controls labels, weights, groups, reverse ordering, badges, link overrides, and active-child filtering. See COMPONENTS.md. The current page and ancestor disclosures are marked or expanded on the server. A hidden page stays out of unrelated sidebars. Following a direct link into a hidden section reveals that branch, without revealing unrelated hidden branches. Keep the same navigation state and filtering rules throughout recursion.
Related-reference links come from the product config. Non-rendered API roots have
no permalink; url.html finds their
generated overview in data/api-reference.json. Missing or ambiguous destinations
fail the build rather than producing empty links.
baseof.html provides the shared header, search dialog, chat drawer, reading area, and footer. It uses the navigation context to choose whether to render a sidebar. reading-header.html provides the breadcrumb, title, description, and page actions. Discovery layouts replace the main content block; content layouts retain the shared reading header.
The homepage renders three category cards from categories.json. Its What's new
timeline uses data/whats-new.json, shows featured entries initially, and reveals
other entries in their chronological positions. The Markdown homepage retains
the category and product inventory. Reference directories and llms.txt use the
reference registry rather than a separate list in page front matter.
Sitemap and metadata feeds exclude hidden pages and source-only pages without a
published URL. llms-full.txt applies the same visibility rule to its page index.
CLI layouts render upstream command data. API references have two rendering paths:
layouts/api-docs.htmlrenders the generated API catalog, overviews, operations, and schemas from committeddata/api-reference.json. API operation navigation comes from that model. Generation inputs and commands are documented in the API build guide.layouts/api.htmlrenders legacy Engine versions as standalone ReDoc documents. It loads pinned ReDoc, owns its navigation and styles, and bypasses the shared site shell. Keep this boundary until those references migrate to the generated format.
Engine v1.57 uses api-docs while its authored version page retains its title,
URL, and latest aliases. The model's authoredOverview flag tells the adapter to
skip overview creation; operations and schemas are still generated. The authored
page selects the shared overview layout and model ID as described in
the API build guide.
assets/css/style.css is the Tailwind v4 entry point, compiled by Hugo's
css.TailwindCSS pipeline. docs-shell.css defines shared layout geometry;
components.css styles reusable components. API references and chat have their
own scoped styles.
Trident tokens live in assets/css/vendor/trident/. theme.css applies the docs
adaptations for Onest, JetBrains Mono, reading widths, and neutral inline code.
Colors use the pinned Trident semantic roles: primary and primary-foreground
for action buttons, primary-ink for links, and status roles such as info and
warning for informational states. Surfaces,
text, and borders use their corresponding semantic roles. Token values follow
the active theme. Code blocks use surface-raised, including installation
commands and unrecognized-language blocks. syntax.css styles Chroma tokens
with Trident palette shades chosen for readable contrast in both themes.
Focus indicators use --docs-focus-ring: brand-600 in light mode provides
contrast over the blue category wash; dark mode uses control-focus.
The .prose token mapping in theme.css sits outside Tailwind's layers so it wins
over Typography's default and inverted palettes. Typography supplies document
structure and spacing; Trident supplies the colors. Keep custom prose selectors
scoped away from not-prose components.
theme.js applies a stored light or dark preference before paint. Without an
explicit preference it follows the operating system; using the toggle persists
the selected theme.
category-washes.css selects broad header and footer gradients through the
body's data-category. An unset category uses the default composition. Washes
use CSS and don't require route seeds or browser generation.
ui-icon.html renders the local Trident icon set using canonical icon names.
icon.html delegates interface icons to that partial and resolves explicit SVG
paths for product logos and other local artwork. Icon names in content and
templates match the vendored filenames; no icon-library module mount or alias
registry is required. Generated vendor assets retain their source geometry and
manifests. Refresh instructions and pinned migration versions are
in the migration notes.
Hugo renders navigation links and native disclosures. JavaScript restores sidebar scroll position per collection and collapses the mobile sidebar initially. A breakpoint change reopens it on desktop so the navigation remains available when its mobile disclosure toggle disappears. JavaScript doesn't build or filter the navigation tree.
assets/js/main.js loads the shared browser modules. Alpine.js manages search
and chat state. The search dialog uses native dialog behavior; docs-search.js
loads Pagefind on demand and loads matches in batches without discarding later
results. Editing the query invalidates outstanding requests before the next
search starts. The homepage and dialog share the search composer and results
partials. Selecting Ask Docker passes the query to the Gordon store and
opens the chat drawer. Rebuilding HTML alone doesn't regenerate the Pagefind
index; build that index when checking search results.
Reading pages include layouts/_partials/ask-dock.html, a bottom question field
on desktop and a chat trigger on mobile. CSS sticky positioning keeps it within
the main content area and clear of the footer. It uses the existing Gordon store
and hides while search or chat is open. Discovery pages and standalone ReDoc
omit it; without JavaScript it remains hidden.
Control this component with params.gordon.ask_dock in hugo.yaml:
params:
gordon:
ask_dock: trueSet it to false to omit both the desktop field and mobile trigger from the
rendered HTML. Search and the other chat entry points remain available. An
omitted setting also disables the dock.
The shared code-copy partial and module handle fenced blocks and installation
commands. quick-install.js selects platform examples. It doesn't determine
whether a user is eligible to install a product; installation links remain the
fallback when detection or JavaScript is unavailable.
Run scoped Markdown lint for prose changes as described in AGENTS.md.
For template and navigation changes, build with --panicOnWarning and check the
rendered pages, including mounted and generated content. Navigation registry
validation runs through the shared head partial during the build.
Use hack/redesign/browser.mjs for responsive layouts, themes, navigation,
search, and clipboard behavior. It also runs the focused interaction and wash
checks. npm run test:a11y adds axe scans and keyboard checks for interactive
components. See ACCESSIBILITY.md for coverage and outstanding
content and screen-reader reviews. hack/redesign/verify.py compares routes,
redirects, and article anchors against a baseline. API browser and output checks live under hack/api-docs/.
See the migration verification instructions
for build preparation, Pagefind, and browser commands.