Organizing content
_index.md, weight, index styles, icons, folding, hidden pages, and documentation paths.OINK requires no separate navigation configuration. The directory structure
under content/ creates the sidebar tree. This page covers how directories and files are
arranged, section indexes, ordering, icons, folding, hiding, and multiple
sidebar roots.
Directories are the sidebar
Hugo calls a directory a section. Its Markdown files are pages. A nested
directory is a subsection. The sidebar renders this tree level by level.
weight determines order. linkTitle supplies labels, with title as fallback. The tree on the left comes from this source:
the first two levels of content/docs/
content/
docs/
- _index.mdsection root: type: docs + cascade
about/Introduction
- _index.md
- features.md
start/Get started
- _index.md
write/Authoring (this section)
- _index.mdweight: 30
- pages.mdweight: 10
- organize.mdweight: 20
- frontmatter.mdweight: 30
components/Components
- _index.md
Every directory needs an _index.md
A section index is the _index.md inside the directory (_index.zh.md for
Chinese). Without this file, Hugo still creates the section. It has no title,
description, icon, or weight. The sidebar shows the directory name. You cannot
control its order.
A section _index.md also supports cascade. It applies shared settings to
the whole subtree. You do not need to repeat them on each page.
Ordering: use multiples of 10 for weight
Pages in a section use ascending weight order. Only equal weights use date
and linkTitle. Always use multiples of 10, such as 10, 20, and 30. You can
then insert a page between others without changing their weights. A section’s own
weight decides its position among its siblings.
A page with no weight counts as 0, and Hugo places those after every page that
does have one, ordered among themselves by date and title. That order changes as
content changes. Give every page a weight.
Single file or page bundle
A page with no resources of its own is a single slug.md. For a page with
images, cast files, or example files, use a directory. Put index.md and the
resources in that directory. The two shapes look identical in the sidebar and
produce the same URL. See
Writing pages.
List or cards on a section index
After the body of an _index.md, the theme appends an index of the child pages
in one of two styles:
list is the theme default. It shows one line per child page with its title
and description. cards is a grid of link cards reading each child’s icon,
linkTitle and description. This site uses cards, and this section’s index
page is the example. Override it in a single section’s front matter when that
section needs the other style:
Two page-level switches work independently of the style. simple_list: true
renders a compact bulleted list. no_list: true generates no index. Use the
latter when the page body supplies its own navigation.
In the card style, description is the card body. Keep it to one sentence
that fits on a single line.
Sidebar icons
Write one Font Awesome class pair in a page’s or section’s front matter:
Icon density is a site-level policy, so that leaf pages do not all carry icons:
| Value | Effect |
|---|---|
all |
Every entry that declares an icon shows it (the compatibility default when unset) |
groups |
Only the root and nodes with children show icons. Ordinary leaf pages do not |
none |
No entry icons in the sidebar |
For a new site, set groups explicitly. Groups then keep their identifying
icons, and leaf pages omit icons. This site uses that setting. Only the six
sections on the left have icons.
Expanding and folding
A section with children carries a fold arrow in the sidebar. OINK saves the whole sidebar’s collapse, width, and scroll state. To persist individual branch choices, add optional site code using the sidebar runtime API. By default, the path containing the current page is expanded. Other paths are collapsed. Blog-type sections are expanded by default.
Site-level folding, compact mode, initial expansion depth, width and truncation are configured in Layouts and page types. The full key definitions are in Configuration.
Hiding from the sidebar
| Front matter | Effect |
|---|---|
toc_hide: true |
The page is absent from the sidebar tree (it is still published, and links to it still work) |
hide_summary: true |
The page is absent from the section index |
sidebar_divider: true |
The entry stops being a link and becomes a group heading in the sidebar |
manual_link: https://… |
The sidebar row points elsewhere. Pair it with manual_link_title and manual_link_target: _blank |
toc_hide and hide_summary control two different entry points, so set both
only when the page should appear in neither.
Groups without a landing page
Since OINK 1.1, a divider section keeps its children while its title has no
link. This fixes the missing children in v1.0.0. Use this
_index.md when the directory should only organize child pages:
The title is a group label. If sidebar folding is enabled, its button folds
the children. The children remain in the pager, search, navigation JSON, and Print. Without JavaScript,
the group stays expanded. Omit build to keep publishing the section page
while still showing a non-link sidebar label. Leaf dividers keep their old
separator appearance.
toc_hide hides a section’s entire subtree. no_list only removes the child
list from a section’s body, and hide_summary removes an entry from its parent
page. None of these is a replacement for a group-only section. build.render: link retains a permalink without publishing a page. For an unpublished group,
prefer never. This prevents other navigation from creating a destination.
The shell follows type, not the path
The documentation shell (sidebar, table of contents, breadcrumbs, pager) does
not depend on the directory name. It depends only on whether the page’s type
is listed in params.ui.shell_types:
Documentation can therefore live at any path, with type assigned by a cascade.
To put a handbook at content/handbook/, the section root reads:
When the documentation directory is not called docs, sidebar_root_for: self
is needed alongside type: docs. Otherwise the sidebar looks for its root at
params.ui.docs_section (default docs), and a reader under /handbook/
sees the /docs/ tree.
Multiple sidebar roots
By default, the current top-level section is the sidebar root. A row above the tree names that root. A large subtree can have its own root. For example, use a separate root for a versioned API reference or a self-contained handbook:
| Value | Meaning |
|---|---|
self |
The section’s index page and all its descendants take it as their sidebar root |
children |
The index page stays in the parent tree. Only descendants use this root |
The switcher above the root is site-wide. It lists every top-level section and
every section that declares sidebar_root_for: self. With one entry, it shows
a plain link. With two or more entries, it shows a dropdown. To keep a
top-level section or nested self-root out of the global choices, write
sidebar_root_menu: false in its _index.md. The current root remains as a
location marker when browsing that section.
Below the switcher, the section index remains the tree’s first link. The
switcher selects a tree. The root link opens a document.
sidebar_root_link_self: false makes that row point at the parent section
instead.
Verify
The build must complete with Total in … and no ERROR. --printPathWarnings
flags any two pages that resolve to the same output path when restructuring
directories.
Then confirm each of these in the browser:
- The sidebar order matches the
weightvalues you wrote, and a new section appears where expected. - The section index lists every child (a missing one comes from
hide_summaryor a missing_index.md). - Breadcrumbs and the pager follow the same order as the sidebar, because the pager reads the same tree.
- The tree has the same shape after switching language (every
_index.mdneeds a.zh.mdcounterpart).
When sidebar entries exceed params.ui.sidebar_menu_truncate, the build warns
and says what to raise it to. Do not ignore that warning. Truncated entries
never appear in the sidebar.
Controlling a branch from site code
The window.OinkSidebar API is available since OINK 1.1. v1.0.0 does not
provide it. Load site code after the theme scripts, for example through
layouts/_partials/hooks/body-end.html, and wait for ready before reading or
restoring branch state. This example expands the first sidebar group:
Use the button’s existing aria-controls value as the region ID.
getState(id) returns {id, expanded} or null. A change sends one
oink:sidebar-disclosure event on document, after the button, region and
accessibility state agree. Its detail is {id, expanded, source}. Repeated
writes of the same value send no event. Restoring through the API keeps the
current page’s ancestor groups open, while a reader can still fold them.
The theme does not save individual branch preferences. A site that adds this should own the storage key’s language and navigation-version scope, tolerate unavailable storage, and ignore IDs absent from the current page. The sidebar contract defines the lifecycle.
Related
- Writing pages — how to write a single page
- Page parameters — the full definition of every front matter key used here
- Layouts and page types — site-level shell, sidebar and table-of-contents settings
- Navigation and menus — the navbar menu, breadcrumbs and pager
- Languages — keeping a bilingual tree consistent