Skip to content

Page parameters

The full front matter table — active page keys and retained 1.x compatibility no-ops, grouped by sidebar, shell, search, output, page end, Book, Expo, landing and release pages.

This page lists all page-level parameters that OINK reads, including explicit 1.x compatibility no-ops. It omits keys that the theme reads only to warn about a rename or removal. Those keys 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 others) work as usual. For their meaning, see 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. If several cascade layers set the same key, the closest layer takes precedence.
  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.

Write page keys at the top level of front matter, without the site key’s ui. prefix. For example, the site’s params.ui.section_index becomes the page’s section_index. Do not nest these keys in a ui: block: the theme neither reads nor reports a ui: block there. If a setting has no effect, check its key name against this page.

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, use the same key names one level deeper:

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

An invalid value does not abort the build: the theme logs a warning naming the key, supplied value, and fallback, then renders the page with the default listed below so a single typo does not return HTTP 500 across hugo server.

When continuing with a default would publish misleading metadata—such as an incomplete upstream attribution—the theme logs a warning and omits the block entirely. Unresolved content references (ref / relref) still fail the build through Hugo.

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 for section cards, search snippets, and meta description. Blog pages also show it as an introduction above the body
weight , integer , default0
Order among siblings. Use multiples of 10. 0 (unset) sorts after every page with a weight. See Organizing content
draft , boolean , defaultfalse
A draft never reaches build output. Use hugo server -D to preview it. See Writing pages
date , date , default—
Blog date and release-page sort key. A future date excludes the page by default
lastmod , date , defaultGit commit time
The page-end “last modified” time. No manual value is needed if the site enables enableGitInfo
aliases , string array , default—
Redirects an old path to this page. Use for page migration rather than 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—
Applies the keys below to 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
Excludes this page and its subtree from sidebar navigation and the pager sequence, in both content-derived and explicit trees
hide_summary , boolean , defaultfalse
Absent from the section index
sidebar_divider , boolean , defaultfalse
A non-link group heading, excluded from pager destinations. The 1.1 implementation retains a section’s children. Use build.render: never for a group without its own page
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
Includes a top-level section or nested self-root in global switcher choices. An excluded current root remains a location marker. The nested-root exclusion is fixed in 1.1
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. Blog defaults off
theme_color , string , defaultsite value
#rgb/#rrggbb hex value for this page’s accent backgrounds. In a section root’s cascade, it gives the whole section an identity. See Brand and appearance
theme_color_dark , string , defaultderived
The dark-mode accent. If a page overrides theme_color under a cascade that sets this key, it inherits that dark value. 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 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 width on Book pages. Applies only to type: book
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
Silent 1.x compatibility no-op. The normal shell runtime always provides active-heading tracking
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
Each page can override sidebar behavior. The values are in Configuration
sidebar_width_min, sidebar_width_max , positive integer , defaultsite value (220 / 480)
Per-page minimum and maximum 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= takes precedence
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
The output formats this page generates. [HTML] disables the .md version
no_print , boolean , defaultfalse
Excluded from the whole-chapter and whole-book print aggregate

Page end: comments, feedback and provenance

The order is fixed: 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. Other values warn and fall 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 license, 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. The most specific declaration takes precedence.

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 omits the attribution
upstream_modified , boolean , defaultfalse
Changes the credit verb to say the work was adapted. If the site has repository information, the same attribution sentence also includes a “view history” link. 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 can mislead readers more 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.

See List layouts for the four presentation choices. gallery and blog_gallery are available in OINK v1.4.0; the supported layouts are list, cards, table, and gallery.

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 / gallery , defaultsite value (list)
Blog section index layout. A standalone table with blog_index_toggle: false 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, cards, gallery, and all four views when switching is enabled. A standalone table ignores it
blog_index_toggle , boolean , defaultsite value (false)
Publishes all four layouts and remembers the reader’s choice. When false, publishes only the configured layout and ignores saved layout choices
share , string array or false , defaultsite params.ui.share (empty)
The page-end share targets. Replaces any inherited list. false opts this page out. See Share. An unknown target warns and is dropped
summary , string , default—
Fallback excerpt for gallery entries and post rows on tag and category pages. description takes precedence

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

Expo albums

OINK 1.3.0 uses type: expo for album pages. See Expo albums for the authoring guide.

expo , map , defaultsite params.ui.expo
Replaces the site block; absent fields use the built-in defaults below
expo.images , string , defaultimages/*
Pattern for image resources in the page bundle
expo.mode , wall / cards / seamless , defaultwall
Initial mode when the reader has no stored choice
expo.size , integer , default240
Target size from 160 to 360 CSS pixels; a stored reader size takes precedence

Image titles, captions, credits, weights, explicit IDs, and separate originals use native Hugo resources metadata. See Image metadata for the fields and an example.

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. A non-array value warns. 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 extracts the owner, project and tag and generates source archive links. The date comes from the page’s date. Download assets come from the release body’s checksums block (see Releases). Anything else warns and the release block is skipped