Navigation and menus
This page covers the ways a reader moves between pages: the navbar menu, the section switcher, breadcrumbs, page actions, previous / next, and the footer. The sidebar tree and the outline belong to Layouts and page types.
The navbar comes from Hugo’s menus.main. Docs and Book navigation defaults
to the content/ tree; sites importing an existing reading order may use
data/docs_nav.json. The sidebar, pager
and section index share the selected order.
The navbar menu
Top-level entries go in each language’s menus.main:
Lower weight values appear first. Use pageRef for site pages and url
for external pages. External links automatically receive target="_blank",
rel="noopener noreferrer", and an external-link mark. The identifier is a
stable configuration reference. The keys quick_links and sidebar_root_menu
match it. Translate name per language. Do not translate the identifier.
You can also define a menu entry in page front matter. Use this when “this page is itself a top-level entry”:
The navbar’s right-hand GitHub entry is not a menu item. It uses
params.github_project_repo, with a fallback to params.github_repo. The menu
area skips entries identified as github. To change the GitHub target, change
the repository parameters. See Repository links and page info.
Dropdowns
Use Hugo’s parent to establish a parent-child relationship. Only one level
of children is supported:
- Every entry is one icon and one title on its own row, in one
moderate-width column. A child’s
params.descriptionis configuration data only; the panel never renders it. - The parent is itself an ordinary link. Hover or focus it to expand the panel. Click it or press Enter to open the parent page. There is no separate expansion arrow. On touch screens, readers open the parent page, whose body lists the same links.
- Keyboard: the down arrow expands the panel and focuses its first item. Esc closes it and returns focus to the link. Clicking outside also closes it.
- The 0.5
params.columnsparameter is retired: setting it emits a build warning and the panel keeps its single column. - A third level produces a build warning and becomes a static group heading. It does not create a third-level flyout. Put deeper levels in the sidebar.
Menu icons
Below lg a menu entry is reduced to its icon, so every top-level entry should
have one. Icons resolve in this order:
iconin the target page’s front matter;- The menu entry’s own
params.icon; - A built-in default matched by identifier or section name (
docs,blog,examples,community,about,download,githuband others); fa-solid fa-linkwhen none matched.
An icon is one Font Awesome class pair, with the free faces supplied locally by the theme:
Taxonomy menus
A top-level taxonomy entry (/tags/, /categories/) needs no manually written
submenu. The panel shows a grid of “term + count” chips, sorted by descending count.
Enabling taxonomies is in Taxonomies.
Navbar controls
The navbar is 50px tall. It contains the brand logo or wordmark, a centered menu, and utility controls at the end. When enabled, it appears across layouts. On narrow screens, Home and Landing use a site-menu drawer. Shell pages with a sidebar use the sidebar’s drawer instead.
The navbar has a full desktop tier and a compact icon tier:
| Viewport | State |
|---|---|
lg and above |
Brand, centered menu text, and search, version, language, theme, and GitHub controls. No drawer button |
md to below lg |
Centered menu icons and utility controls at the end. No drawer button |
Below md |
Centered menu icons remain. Search and the appropriate drawer button remain at the end. Version, language, theme, and keyboard help remain in the footer’s bottom bar |
Enable individual controls through their settings. The search icon requires
params.offline_search; see Search. The version menu
requires params.versions; see Versions. With two
or more configured languages, the language menu appears automatically; see
Languages. The theme control requires
params.ui.dark_mode; see Brand and appearance.
Auto-hide
With auto-hide enabled, the hidden navbar retains its 50px band. Move the pointer into the upper 60% of that band, or focus the navbar with the keyboard. The navbar fades in at the same position. The layout does not move, and the hidden navbar does not cover content. The wake zone excludes 64px on each side. Collapsed sidebar and outline restore controls therefore remain usable.
It is disabled automatically below 768px, on a coarse pointer, and on a
touch-only device, where the navbar stays visible. Home ignores the site-wide
setting unless its own front matter enables it. Hero pages retain their
overlay navbar, which scrolls with the hero. A top-level navbar_autohide in
page front matter or a section cascade overrides the site setting.
Turning the navbar off
It can also be turned off for one page or one section:
If the navbar is off, the theme restores mobile subnavigation, a brand and
search row at the sidebar top, and utility buttons on the outline rail. Use
this switch for pages that need the whole viewport. It is not a general
layout preference. This site’s documentation section keeps
the navbar enabled and disables its auto-hide behavior with
navbar_autohide: false, so section navigation stays visible.
The section switcher
The section switcher is the sidebar’s top row. It selects the displayed tree.
The theme builds and deduplicates entries in this order: eligible top-level
sections → eligible sections with sidebar_root_for: self → the current
resolved root. Candidates must have a permalink. They cannot be divider groups.
To let a large subtree become a root of its own (a versioned API reference, a
self-contained handbook), in its _index.md:
The value self makes the section index and all descendants use the new tree.
The value children keeps the index in the parent tree. Only descendants use
the new tree.
To exclude a top-level section or a nested self-root from the global choices,
set sidebar_root_menu: false in its front matter. The current resolved root is
still appended if absent. Inside that section, it remains a location marker.
The 1.1 implementation excludes both nested self-roots and top-level sections.
The 1.0 implementation could still include a nested self-root despite false.
A root with build.render: never, or a divider root, never becomes a switcher
link.
With no entries, the switcher renders nothing. One entry becomes a borderless link. Two or more entries create a dropdown. The tree below still lists the section index first. The switcher selects a tree. The root link selects a document.
Breadcrumbs and page actions
An ordinary content page has breadcrumbs above its title and page actions at the row’s right end. A top-level section omits single-level breadcrumbs that only repeat its title. Action buttons retain their positions.
Breadcrumb labels use the localized linkTitle, and the hierarchy matches the
sidebar.
The page action menu
The split button at the title row’s end contains page actions. Click its left half to copy the page’s Markdown. A successful copy shows a green check mark. Click the right arrow to expand the full menu. The menu groups actions for exporting content and for changing or producing content:
| Action | When it appears |
|---|---|
| Copy as Markdown | The site enabled the markdown output format |
| Open in ChatGPT | page_context_menu.assistant_links: true |
| Open in Claude | The same |
| View Markdown source | The markdown output format |
| View history | params.github_repo can resolve the source path |
| Edit this page | params.github_repo |
| Create child page | params.github_repo |
| Open a documentation issue | params.github_repo |
| Open a project issue | params.github_project_repo |
| Print the whole section | The section enabled the print output format |
Assistant entries are off by default. When clicked, they send the full current URL, including its query and fragment, to a third party with a localized prompt. They do not upload the body. Before enabling them, confirm that URLs contain no sensitive information. Document this boundary in the privacy statement. Page front matter can restrict the site policy. It cannot enable assistant links that the site has not enabled:
Confirm that ChatGPT and Claude are absent from both the title menu and the command palette on that page. See AI-agent support for the handoff behavior.
Custom external actions come last in the menu, and url supports three
URL-encoded placeholders:
The placeholders are {url} (the page’s full address), {title} (the page
title) and {markdown_url} (the Markdown version’s address).
On the blog root and its first-level subsections, the left half becomes an RSS subscription link. “copy as Markdown” remains in the menu. Without Markdown output, a page has no left half. The arrow becomes a labeled “Actions” button.
These actions are also entries in the command palette.
The pager
Previous / next are two text links at the body end. They follow the visible
sidebar tree: root page → first page → through to the last. The root has no
previous link. The last page has no next link. If the site provides
data/docs_nav.json, that tree also orders the pager and declared docs or book
section indexes. The sidebar, pager, and index therefore show children in the
same order. Undeclared sections and sites without the file use the content
tree. See Layouts and page types.
The pager_types list accepts only docs, book, and blog. Any other value
warns and is discarded. To disable paging on a page, use front matter:
The page’s <head> uses the same order. When previous or next pages exist,
it emits <link rel="prev"> and <link rel="next">. Browsers and crawlers can
then identify the reading sequence.
Paging applies to HTML output only. Print, Markdown and RSS have neither the
links nor the two rel relationships.
The pager is the third of these four page-end components: feedback → annotation → pager → comments. Their order is fixed. Each has an independent switch. An optional Share bar appears before these components.
Backlinks
The right rail can list pages that link to the current page. Its “Linked
from” group has a link icon and appears below the table of contents, above
taxonomy clouds. It starts expanded. Below xl, it moves into the sidebar
drawer with the table of contents. Readers arriving from search can identify
related pages and the current page’s place in the site. Backlinks remain off
until the site enables them:
A page overrides it in front matter, and a section cascades it to everything below:
Hugo derives the index at build time from ordinary Markdown links and
ref / relref shortcodes in page source. No new syntax, migration, or
JavaScript is required. The list is in HTML. Before scanning, the theme removes
fenced and inline code. Multiple links to one target become one entry. It
ignores self links, external links, mailto:, and same-page anchors.
The theme removes fragments when identifying target pages. Each language has its own graph. A Chinese page never appears below an English page. Entries sort by stable page path, so identical content always produces identical order. If no pages link in, the entire block is absent, including its heading and container.
The first eight entries are visible. Remaining entries use a native “Show N more” disclosure. This limits right-rail space for heavily referenced pages. No JavaScript is required. Each entry shows its source page’s description on hover.
Source scanning has a known limit. URLs in custom shortcode parameters and
raw <a href> elements do not become edges. Unresolved destinations are
discarded without a warning. Backlinks enhance navigation. They do not check
links. Continue using a link checker to find broken links.
A non-boolean value warns and falls back to off.
The page’s Markdown output carries the same list, introduced by “Backlinks:”.
RSS omits it, and the print output format omits it with the rest of the rail.
This site enables backlinks site-wide. See this page’s right rail for an example. The most-referenced page, Configuration, lists more than forty inbound links. Most use the disclosure.
The footer
The params.ui.footer_style setting selects fat / slim / none.
See Brand and appearance. The fat link grid
reads data/footer/<language>.yaml. It is not a menu. The theme has no
menus.footer:
- If
brand.nameandbrand.logoare absent, the footer uses the site’s brand name, logo, and wordmark. The fieldstaglineandsloganrender Markdown. - An internal
urlresolves against the current language root. The settingexternal: trueopens a new tab withrel="noopener noreferrer". - The grid has as many columns as the data does.
- A single-language site can use
data/footer.yaml. - If
fatis configured without data, the footer automatically falls back toslim. You can enable it before content exists.
The fat footer’s copyright row has a collapse arrow at its right end. It
hides or restores the link grid above. The grid starts expanded. localStorage
stores the reader’s choice under td-footer-collapsed across pages. The styles
slim and none have no collapse button. This state is independent of focused
reading mode.
Every rendered bottom bar ends with an icon dock in this order: version,
language, theme, then keyboard help. Configured menus open upward. The version
trigger shows only an icon. Its choices retain full labels. The fat footer’s
collapse arrow follows the four controls. The sidebar has no duplicate dock.
The setting footer_style: none removes both the footer and bar.
The copyright row and the centre note are parameters — see Configuration.
Verify
After changing navigation, check each of these:
- Confirm that the build has no
Navbar menu … supports one interactive child levelwarning. This warning indicates a three-level menu; - On desktop, click a parent to open its page. Hover to expand the panel. Press Esc to close it;
- Narrow the window below
lg. Confirm that each top-level entry has an icon. An entry without an icon is blank at this width; - Below
md, confirm that Home and Landing navbars retain search and the drawer button on the right. Version, language, theme, and keyboard help must remain in the footer bottom bar; - The switcher at the top of the sidebar lists every top-level section, with the current one marked;
- On a documentation page, use E / Q to check sidebar paging order. Confirm matching
rel="prev"/rel="next"in page source; - With backlinks enabled, confirm that
grep td-backlinks public/<a page that is linked to>/index.htmlfinds the block. A page with no inbound links must have no backlink markup; - Open the page action menu. Confirm that expected actions appear and unavailable actions are absent. For example, “open a project issue” should be absent without
github_project_repo.
Related
- Layouts and page types — sidebar tree, outline and shell types
- Configuration — defaults of the navigation parameters
- Command palette — page actions and custom commands
- Repository links and page info — the edit, history and issue links
- Organizing content — how the directory structure decides the sidebar