Skip to content

Page parameters

The full front matter table — every page key the theme actually reads, grouped by sidebar, shell, search, output, page end, Book, landing and release pages.

This page is the complete table of page-level parameters, listing only the keys the OINK theme reads. Keys the theme reads solely to warn that they were renamed or removed are not listed here — they are in Migration, and they are also kept out of the generated editor schema. Hugo’s own front matter fields (slug, url, build, sitemap, expiryDate and the rest) work as usual; their meaning is in the Hugo documentation. Site parameters (params.* in hugo.yml) are in Configuration.

How to read the tables

Precedence, highest first:

  1. The page’s own front matter;
  2. The nearest cascade (when several cascade layers set the same key, the one closest to the page wins);
  3. The site parameter in hugo.yml.

Keys whose Default column says “site value” fall back to the site parameter of the same name when unset.

Page keys are written at the top level of the front matter, and the key name is the site key with its ui. prefix dropped: the site’s params.ui.section_index is the page’s section_index. Front matter never carries a ui: block; the keys sit at the top level. A ui: block written there is not read and not reported, so check the key name against this page when a setting seems to have no effect.

content/docs/wide-reference.md
---
title: Compatibility matrix
weight: 40
page_width: wide
footer_style: slim
image_zoom: true
section_index: list
---

Inside a cascade the key names are unchanged, just one level deeper:

content/docs/reference/_index.md
cascade:
  pager: false
  section_index: list

An invalid value does not stop the build. The theme warns — naming the key, the value it got and the fallback it used — and renders the page with the default in the table, so one typo degrades one setting instead of serving HTTP 500 on every URL under hugo server. It still never ships: every publishing gate builds with --panicOnWarning, which turns that warning back into a hard failure where it counts.

No front matter key stops the build; the theme’s templates never raise an error. Where carrying on would publish something wrong rather than merely plain — an incomplete upstream attribution, for instance, because a partial notice reads exactly like a complete one — the warning is followed by omitting that block entirely rather than by a fallback. The one thing here that does stop a build belongs to Hugo, not the theme: a reference that cannot resolve.

Basics

title string default—
Page heading, browser title, search result title. Required on every page
linkTitle string defaulttitle
Short name in the sidebar, breadcrumbs, pager and cards
description string default—
One-sentence summary: section cards, search snippet, meta description; rendered as a standfirst above the body on blog pages
weight integer default0
Ordering among siblings; use multiples of 10. 0 (unset) sorts after every page that has a weight — see Organizing content
draft boolean defaultfalse
A draft never reaches the build output; hugo server -D previews it — see Writing pages
date date default—
Blog date, and the sort key for release pages; a future date is excluded by default
lastmod date defaultGit commit time
The page-end “last modified”; not needed by hand when the site enables enableGitInfo
aliases string array default—
Redirects an old path to this page; for page migration, not for everyday navigation
type string defaulttop-level directory name
Decides the template and the shell: docs, book, blog, swagger — see Organizing content
layout string default—
Picks a layout for one page: landing, releases
cascade map default—
Pushes the keys below down the whole subtree

The guide is Organizing content.

icon Font Awesome class pair default—
Icon in the sidebar, section cards and search results, e.g. fa-solid fa-rocket
toc_hide boolean defaultfalse
Absent from the sidebar tree and from the pager sequence
hide_summary boolean defaultfalse
Absent from the section index
sidebar_divider boolean defaultfalse
The row renders as a sidebar group heading: not a link, and not in the pager sequence
sidebar_expanded boolean defaulttrue for blog sections, false otherwise
This section is expanded by default in the sidebar
sidebar_root_for self / children default—
Makes this section a sidebar tree root; self includes the section index, children covers descendants only. Any other value warns and is ignored
sidebar_root_menu boolean defaulttrue
Whether a top-level section appears in the root switcher
toc_root boolean defaultfalse
When the sidebar root is the site home, excludes this whole top-level section from the tree and the pager sequence
no_list boolean defaultfalse
The section index generates no child list
simple_list boolean defaultfalse
The child index renders as a compact bulleted list
section_index list / cards defaultsite value (list)
Style of the child index. An invalid value warns and falls back
section_index_columns integer default2
Column count in the card style
notoc boolean defaultfalse
Hides the right-hand page outline
pager boolean defaultdecided by params.ui.pager_types
false turns off previous / next for this page. A non-boolean warns and is ignored
navbar_enabled boolean defaultsite value (true)
Whether this page renders the navbar
navbar_autohide boolean defaultsite value (false)
The navbar hides itself on pointer devices
breadcrumb boolean defaultshell default
Whether this page renders breadcrumbs; Docs/Book default on and Blog defaults off
theme_color string defaultsite value
#rgb/#rrggbb hex tinting this page’s accent grounds. On a section root’s cascade it gives the whole section an identity — see Brand and appearance
theme_color_dark string defaultderived
The dark half of the accent. A page overriding theme_color under a cascade that also sets this key inherits that dark value, so override both. theme_color: false opts the page out of an inherited section color entirely
page_context_menu boolean defaultsite value (true)
The page action menu on the title row (copy Markdown, edit this page, print, …)
page_context_menu.assistant_links boolean defaultsite value (false)
The ChatGPT / Claude handover items, written page_context_menu: { assistant_links: false }. A page may only narrow the site policy, never enable it alone

Page shell

Site-level defaults and what they do are in Layouts and page types.

page_width normal / wide / full defaultnormal
Width of the content column. An invalid value warns and falls back
reading_width slim / normal / wide defaultnormal
Reading measure on Book pages; applies to type: book only
body_class string default—
A class appended to <body> for the site’s own CSS
reading_time boolean defaultsite value
Whether this page shows a reading time; false hides it
sidebar_enabled boolean defaulttrue
Whether this page shows the left sidebar; false hides it
scroll_spy boolean defaultsite value
Scroll tracking in the outline; true enables it
keyboard_nav boolean defaultsite value (true)
Single-key keyboard navigation — see Keyboard navigation. A non-boolean warns and falls back
lastmod_commit subject / hash / none defaultsubject
How the commit is shown after “last modified”. An invalid value warns and falls back
sidebar_expand_levels, sidebar_menu_compact, sidebar_menu_foldable, sidebar_item_overflow as the site parameter defaultsite value
Sidebar behaviour can be overridden per page too; the values are in Configuration
sidebar_width_min, sidebar_width_max positive integer defaultsite value (220 / 480)
Per-page lower and upper bounds for desktop sidebar resizing; a minimum above its maximum warns and restores the site pair
code_copy boolean defaultsite value (true)
Default copy control for code blocks on this page; an explicit fence copy= still wins
toc_style fixed / flow defaultsite value (fixed)
Fixed right-rail panel or a wider rail beginning in the content flow
toc_taxonomies boolean defaultsite value (true)
Whether taxonomy clouds join the right-rail outline
taxonomy_icons map defaultsite value
Per-taxonomy icon overrides for this page or section cascade

The guide is Search.

search_keywords string or string array default—
Extra search terms, including synonyms and other languages
search_boost positive number default1.0
Ranking multiplier; the final score is the text match score times this value. A non-numeric, non-finite, zero or negative value warns and falls back to 1.0
search_exclude boolean defaultfalse
Keeps the page out of the local index

Output formats

The guides are AI-agent support (.md and llms.txt) and Print.

outputs string array defaultsite outputs
Which output formats this page generates; [HTML] stops the .md twin
no_print boolean defaultfalse
Excluded from the whole-chapter and whole-book print aggregate

Page end: comments, feedback and provenance

The order is fixed as feedback → provenance → pager → comments; see Writing pages.

comments boolean defaultsite params.comments.enable (false)
Whether this page shows the giscus comment section — see Comments
feedback boolean or map defaultsite params.ui.feedback (off)
The map form takes enable and reasons. Anything else warns and falls back
annotation boolean defaultsite params.ui.annotation (on)
The “last modified / provenance” block at the page end. Only a boolean is accepted; anything else warns and falls back
translation_notice language code or false defaultsite params.ui.translation_notice (off)
The language code of the authoritative version, so a translation can say so and link back; write false on a page authored natively in this language

Upstream attribution

When a page is derived from material elsewhere, upstream_link declares the source and the page-end provenance line gives the work, the copyright holder, the licence and a link to the full notice. This family resolves site parameters → the data/upstreams entry named by upstream_source → this page’s front matter, so the most specific declaration wins.

upstream_link is read from front matter only (a cascade counts, site parameters do not) — a site-wide value would make every page claim the same source. A companion key without upstream_link warns and the attribution is omitted.

upstream_name string default—
The upstream work, as the attribution names it. Required once upstream_link is set
upstream_license SPDX identifier default—
Must be found in data/licenses, or it warns and the attribution is omitted. Required
upstream_notice site path or URL default—
The page carrying the full notice (licence text, warranty disclaimer, upstream NOTICE, snapshot pin). Required
upstream_ref string default—
The tag or commit the snapshot pins, shown in parentheses after the work
upstream_source string defaultsite parameter
The entry name in data/upstreams, for upstream facts shared by many pages; a missing entry warns and the attribution is omitted
upstream_modified boolean defaultfalse
Changes the credit verb to say the work was adapted, and adds a “view history” link to that same sentence when the site has repository information — one line, not two. A non-boolean warns and the page is treated as unmodified

Missing any one of the four required keys (upstream_name, upstream_copyright, upstream_license, upstream_notice) warns and omits the attribution: a partial attribution is worse than an obvious omission. The theme ships an SPDX table at data/licenses.yaml, and a site adds to or overrides it with a file of the same name.

Image zoom

image_zoom boolean defaultsite value (false)
Whether images on this page open full size — see Images. A non-boolean warns and falls back

Blog posts

The guide is Blog posts.

author string default—
Post byline; inline Markdown is allowed. Ignored on a page that has authors
authors string array default—
Terms of the authors taxonomy, in byline order — see Authors and bylines. Needs author: authors under taxonomies:
series string array default—
Terms of the series taxonomy. The strip above the body uses the first one — see Series
series_weight integer default—
Place in the series. Weighted members come first in ascending order, the rest follow by ascending date
tags string array default—
Tags — see Taxonomies
categories string array default—
Categories, likewise
images string array default—
The first entry becomes the post’s featured image and share card; put it in a section _index.md cascade for a section-wide default. images: [] opts the page out of an inherited cascade value; it does not suppress an image the page bundle already supplies under a featured, cover or thumbnail name
byline string default—
Credit shown with the resolved featured image when that image is rendered
blog_index list / cards / table defaultsite value (list)
Written on a blog root, the index form for that section. table lists the whole section without pagination. An invalid value warns and falls back
blog_index_columns positive integer defaultsite value (3)
Card columns at wide breakpoints; medium and narrow layouts retain their responsive limits
blog_index_size positive integer defaultsite value (12)
Posts per page for list and cards; table always lists the whole section
blog_index_toggle boolean defaultsite value (false)
Publishes all three index forms and lets the reader switch among them; hidden forms do not load images
share string array or false defaultsite params.ui.share (empty)
The page-end share targets, replacing any inherited list; false opts this page out — see Share. An unknown target warns and is dropped
summary string default—
Fallback excerpt for post rows on tag and category pages; description wins

Book

The guide is Books. A whole book sets type: book through a section cascade.

book_number string default—
Chapter number, shown before the page title and the sidebar entry
book_status draft default—
Marks a draft chapter: flagged in the sidebar and contents, and left out of the indexes by default
sidebar_headings false / true / integer 2–4 defaultsite value (false)
Expands the h2–h4 branch under the current sidebar entry. Out of range warns and falls back
book_draft_banner boolean defaultsite value (false)
Adds a banner at the top of a draft chapter. A non-boolean warns and falls back

Landing

The guide is Home and landing pages. Any page with layout: landing uses the landing shell.

landing string default—
Data is taken from data/landing/<key>/<language>.yaml
sections array default—
Section definitions inlined in front matter, taking precedence over landing. Anything but an array warns and no sections render

Release pages

The guide is Releases and downloads. A section with layout: releases ignores weight and sorts by release date and SemVer, newest first.

release_url string default—
One GitHub release URL, https://github.com/<owner>/<repo>/releases/tag/<tag>. The theme derives the project, tag, date and asset list from it. Anything else warns and the release block is skipped
Last modified 2026-09-03 · docs(i18n): clarify Hugo 0.160 Chinese locale config (bb79ec1)