Blog posts
Write a blog post’s body like a documentation page. The shell differs. A post has a date, author, tags, and featured image. The list uses date order, newest first. The section has an RSS feed. This page covers creating the blog section, a post’s front matter, featured images, list layouts, pagination and feeds.
The blog directory
A blog is a section under content/, and type: blog gives it the blog shell.
Subdirectories divide it by publisher and audience, with posts sitting flat
inside. Year directories are unnecessary: the list orders posts by their
date.
this site's content/blog/
content/
blog/
- _index.mdtype: blog + cascade
- _index.zh.md
oink/engineering notes and announcements
- _index.mdcascade: images: [/images/oink.webp]
- oink-announcement.md
- oink-announcement.zh.md
release/versioned release notes
- _index.mdcascade: images: [/images/releasenote.webp]
- 0.4.0.md
- 0.4.0.zh.md
The section root applies the type to the whole subtree. It sets the section’s shared behavior:
params.ui.blog_section (default blog) names where the blog root is. Rename
the directory and either change that parameter or use sidebar_root_for: self
as above.
Blog sections are expanded by default in the sidebar and ordered by date, newest
first. To place one post at the top, give it a weight.
A post’s front matter
Where it differs from a documentation page:
dateis required. It decides the post’s place in the list and its RSS timestamp. A future date excludes the post from the default build. Usehugo server -Fto preview it.descriptionappears as an introduction above the body and as a search snippet. Write a sentence for the reader.authoraccepts inline Markdown, so[Vonng](https://vonng.com)works. For more than one author, a portrait, or a profile page, use theauthorstaxonomy below. The two do not interfere. A post rendersauthorifauthorsis absent.- The date display format comes from
params.time_format_blogand can be set per language (this site usesMonday, January 02, 2006in English and2006年1月2日in Chinese).
Bilingual posts are stored in pairs, keeping date, author, weight and
aliases identical across the two. Titles, descriptions and tags are
translated. Do not translate commit IDs, version numbers, commands, or URLs.
Featured image
Each row on a list or tag page has a thumbnail on the left. The resolver uses the first match in this order:
imagesin the post’s front matter, first entry;- An image resource in the page bundle whose filename matches
featuredorfeature, thencoverorthumbnail(it is cropped to a thumbnail, and the resource’s ownbylinebecomes its caption); - An
imagesvalue inherited from an ancestor section’scascade, nearest first.
A section-wide default uses Hugo’s native cascade over the whole subtree.
This site sets one for each of its two subsections:
To clear an inherited image on one post, write images: [] in its front matter.
To clear it for a whole subsection, put it in that level’s cascade. This does not suppress
an image supplied by the page bundle. To hide the image on the article itself,
use featured_image: none. List thumbnails and share cards use images separately.
The site-level params.images feeds the share card only and is never rendered
as a list thumbnail.
On the article itself
By default the resolved image appears on list rows and in the social card. Set
params.ui.featured_image to use the same image on the article itself:
| Mode | What the article shows |
|---|---|
none |
No article image. This is the theme default |
banner |
The image above the title in a fixed 16:9 figure. Articles use a consistent layout |
wash |
A faint image behind the article header, fading before the body |
hero |
A full-width image header |
The page key is featured_image. A subsection’s cascade enables it for that
tree. An individual post can opt out. A post without an image shows none in
any mode. A section can therefore enable it even if only some posts have images. These modes need no additional script.
List layouts and pagination
After the section _index.md body, the theme appends the post index, sorted
by date, newest first, without year groups. Choose its layout with blog_index:
| Value | Layout | What the reader sees |
|---|---|---|
list |
Horizontal entries (default) | Thumbnail, title, date, subsection, tags, and a summary |
cards |
Regular card grid | A cropped 16:9 cover above the title, metadata, and summary |
table |
Compact table | Date, title, and tags in one row per article |
gallery |
Image gallery | Proportional covers with titles and descriptions; click to open the article |
OINK v1.4.0 includes list, cards, table, and gallery.
Set the site default with params.ui.blog_index in hugo.yml, or set
blog_index in a blog section’s _index.md front matter to override it.
Use a section’s cascade to apply it to descendant sections. These settings
control native blog section indexes; term and taxonomy pages keep their own
layouts, and custom homepages need their own template integration.
List, card, and gallery views show 12 posts per page by default. Set the theme’s
blog_index_size in hugo.yml to change it:
The same key in a blog section’s front matter overrides the site value. The
theme explicitly passes this size to Hugo’s paginator. pagination.pagerSize
does not control these lists.
The card form
params.ui.blog_index: cards renders the same list as a grid of content cards
instead of rows. Each card shows a 16:9 image crop above the title, a date and
subsection line, and a three-line summary.
The column count applies above the xl breakpoint. Between md and xl, the grid
has two columns. Below md, it has one. If a card image resource supports
processing, Hugo applies .Fill, so readers download cropped previews.
Table and layout switching
A standalone blog_index: table with blog_index_toggle: false lists the
entire section without pagination. Set blog_index_toggle: true to add the
layout switch beside the title. In OINK 1.4.0, it cycles through
list → cards → table → gallery → list:
All layouts preserve date order and manual_link destinations. With switching
enabled, all four views show the same current page of posts, using
blog_index_size. Only the standalone table shows the entire section.
The switch remembers the reader’s choice. Set blog_index_toggle: false to
publish only the configured layout, regardless of a saved reader preference.
Hidden views use lazy images, although their markup and generated thumbnails
still contribute to build work. In v1.4.0, the switch cycles through all four
layouts.
Gallery form
gallery makes each article a linked cover,
using the existing images field or bundled featured image. The default wall
joins images into rows while preserving their proportions. Hover or keyboard
focus reveals the title and description; touch devices show them below the
image. Clicking opens the article. Posts without a cover keep a title tile.
The gallery toolbar offers three arrangements:
blog_gallery.mode |
Arrangement | Captions |
|---|---|---|
wall (default) |
Justified rows with 6px gaps | On hover or keyboard focus; below images on touch devices |
seamless |
The same rows without gaps | On hover or keyboard focus; below images on touch devices |
cards |
Masonry columns | Always visible below images |
blog_index: cards selects the regular card grid. blog_index: gallery with
blog_gallery.mode: cards selects masonry inside the gallery.
blog_gallery.size sets the target tile size, from 160 to 360 CSS pixels,
with a default of 240. It is independent of blog_index_size, the number of
posts per page. Readers can change the arrangement and size; their choices
are remembered separately from Expo albums.
Site defaults use the same blog_gallery block under params.ui; a page or
cascade block replaces it in full. Omitted fields use wall and 240;
invalid values warn and use those defaults. These settings are available in
v1.4.0. See the
site parameters and
page parameters for the reference tables.
RSS
outputs determines which pages produce a feed. Adding RSS to section
gives every section its own feed:
Setting outputs replaces all Hugo defaults. Include RSS explicitly if you
need feeds. If you omit it, that page kind has no feed. The build does not warn.
This site therefore has /blog/index.xml (the whole blog) and
/blog/release/index.xml (release notes only). A section feed recursively
includes every subsection’s posts. Subscribing to /blog/ covers the whole blog. An individual post has no .xml of its own.
Each language has its own feed at that language’s route plus index.xml. The
item limit is Hugo’s services.rss.limit. On the blog root and its first-level
subsection pages, the first action button beside the title row is the RSS link,
so readers do not need to construct the address manually.
To drop feeds site-wide, turn the kind off with disableKinds, which is more
thorough than removing RSS from each page kind:
Components use their static form in a feed. Disclosures are expanded, and interactive controls are removed. The four-output rules are the same for blog posts as for documentation.
Categories and tags
tags and categories are Hugo’s taxonomies, and the theme renders them as
chips in the post header, a tag cloud in the right column, and a filter menu in
the navbar. Enabling them, bilingual term labels, and switching them per content
type are covered in Taxonomies.
Release notes
A versioned release announcement is an ordinary post, conventionally under
blog/release/, with the version in linkTitle (Oink v0.4.0). For a download
page with release cards, asset tables and checksums, see
Releases and downloads.
Components in a post
Callouts, tabs, code blocks, images and tables work exactly as on a
documentation page. The syntax is in Components. Headings
in a post body take explicit English {#id} anchors too.
The four blocks at the end of a post — feedback, last modified, pager, comments — behave as on a documentation page. See Writing pages. A blog usually turns feedback off and keeps comments.
Authors and bylines
Declare the taxonomy to enable this feature. The theme adds no parameter:
A post then names its authors in order:
The article header renders portraits and linked names in that order. List rows
show the names. The blog feed includes each author alongside the site-level
managingEditor.
An author’s profile is the taxonomy term page. No data/authors file is needed:
The display name is the term page’s link title. It uses linkTitle if
available, otherwise title. A profile can use a full name and the byline a
short handle. description gives a one-line introduction. The body gives the
long introduction. The featured-image resolver selects the avatar. images:
and a bundled portrait follow the same rules as an article’s image. A bilingual profile is an _index.zh.md beside it.
An author without a profile page still has a byline. It shows the link title,
an initial, and an archive link.
The 0.4 author: string is untouched wherever authors is absent, and neither
form warns about the other.
Series
A series is a reading path through articles that each stand alone. Numbering, cross-references, and aggregate output belong to Book. A series has less structure. Declare the taxonomy to enable it:
An article names the series and may place itself in it:
The article then shows a strip above its body. It names the series, position,
and next part. A <details> contains the full list. This requires no JavaScript
or bundle member.
The term page content/series/<name>/_index.md is the introduction, and an
_index.zh.md beside it makes the pair bilingual.
Members with series_weight come first in ascending order. Other members follow
from oldest to newest. The content path breaks ties. The series strip
and term page use this same reading order. For implementation details, see
Authors and series.
A member of several series shows one strip, for the first term it names. A series of one shows none.
Neither authors nor series appears in the generic taxonomy chip row on an
article, because each has a surface of its own. Name one in
params.taxonomy.page_header to put it back.
Share
params.ui.share puts a share bar at the top of the page end. It is empty by
default, so nothing renders until a site names its targets, in the order it
wants them:
Sixteen targets are available: x, bluesky, mastodon, facebook,
linkedin, reddit, hackernews, telegram, whatsapp, line,
pinterest, weibo, chatgpt, claude, email, and copy. An unknown name
warns and is dropped. Discord is deliberately absent. It provides no share-intent URL. Use copy
for Discord. The theme does not infer a private scheme.
The page key is share, so a cascade scopes the bar to one tree, a page’s own
list replaces the inherited one, and share: false opts a single page out:
Only regular pages render the bar. Lists, term pages, and the home page have no single item to share. Print, Markdown, and RSS omit the bar.
Share targets are links carrying the page’s permalink and title, plus a local copy button. The bar loads no third-party scripts or stylesheets. It contacts a target only when the reader clicks its link. See the Share contract for the implementation rules.
chatgpt and claude hand that same build-time permalink to an assistant with
a prompt asking it to read the page. They are not the “open in ChatGPT” /
“open in Claude” entries of the page action menu, which the runtime rewrites at
activation time to the live browser URL and which therefore stay behind
page_context_menu.assistant_links.
The copy button is the built-in copy_link action, so the Command
Palette includes it on every page of every site. This applies even if no bar
is configured.
Verify
The build must complete with Total in … and no ERROR. Then confirm:
- The post appears in the right date order at
/blog/, with the date in the expected format. public/blog/index.xmlexists, contains the post, and its links are complete absolute addresses.- The thumbnail shows in the list (a missing one means none of the three featured-image sources matched).
- Tag chips lead to the corresponding tag page.
Related
- Writing pages — how to write the body
- Page parameters — the full definition of
author,imagesand the rest - Organizing content — directories and the sidebar
- Taxonomies — tags and categories
- Releases and downloads — version cards and asset tables