Skip to content

Fields

A plain table plus {.fields} documents configuration keys, command flags and API fields — name, type, default and description each in place, readable on a narrow screen, every entry individually linkable.

Fields render “a list of named values with metadata and a description” as a responsive definition list: the name gets its own line, type / required / default sit beside it as small chips, the description starts on the next line, and every entry carries its own anchor. Use it for configuration keys, command flags and API fields. When readers need to compare many rows across the same columns, keep a plain table; when the content is a sequence of actions, use steps.

There are two spellings: a plain table plus {.fields} (the default choice), and the fields/field shortcode, for when a description needs several paragraphs, a list or a code block. Both render the same entries.

Shortest form

A pipe table with at least two columns and {.fields} on the next line. The first column is the name, the last is the description, and every column in between is metadata labelled with its own header text.

Source
| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `offline_search` | boolean | `false` | Build the local search index and enable the command palette |
| `offline_search_max_results` | integer | `10` | Maximum number of search results |
| `page_width` | string | `normal` | Reading column width: `narrow` `normal` `wide` |
{.fields}
offline_search_max_results Typeinteger Default10
Maximum number of search results
page_width Typestring Defaultnormal
Reading column width: narrow normal wide

Metadata here shows as “Header: value”. The theme infers nothing from the header — Type is only a label. The next section turns those into standard chips. Cells accept inline Markdown (code, emphasis, links) and empty middle cells are omitted.

Semantic columns with meta=

meta says, in order, what each middle column means: type, required, default, or - to keep the header as a plain label. With it, the table form renders the same chips as the shortcode form.

Source
| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `baseURL` | string | yes | | Site address, subpath included |
| `title` | string | yes | | Site name, shown in the navbar and the tab |
| `defaultContentLanguage` | string | | `en` | Default language; decides which language unprefixed paths belong to |
{.fields meta="type required default"}
baseURL string required
Site address, subpath included
title string required
Site name, shown in the navbar and the tab
defaultContentLanguage string defaulten
Default language; decides which language unprefixed paths belong to

The rules:

  • meta should name a role for every middle column — exactly the column count minus two. Too many or too few warns and ignores meta; strict publishing rejects the warning.
  • A required column is “non-empty means true”: “yes”, “是” or “✔” all read the same, and the rendered chip is the untranslated required. An empty cell shows nothing.
  • type and default cells with no inline markup of their own are wrapped in code formatting, matching the shortcode form.
  • The three semantic chips always display in the order type, required, default, whatever order the columns are in; - columns follow, in column order.

- mixes with semantic roles, which is how you keep one custom label:

Source
| Environment variable | Type | Scope | Description |
| --- | --- | --- | --- |
| `HUGO_MODULE_WORKSPACE` | string | build | Points at `go.work` so the theme resolves from a local checkout |
| `HUGO_ENV` | string | build | Set to `production` to enable minification and fingerprinting |
{.fields meta="type -"}
HUGO_MODULE_WORKSPACE string Scopebuild
Points at go.work so the theme resolves from a local checkout
HUGO_ENV string Scopebuild
Set to production to enable minification and fingerprinting

Labels and container IDs

caption gives the whole list a visible label, which is also its accessible name; id names the outer container so it can be linked to or styled.

Source
| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `enable` | boolean | `false` | Turn image zoom on |
| `selector` | string | `.td-content` | Root selector scanned for candidate images |
{.fields caption="params.ui.image_zoom" id="zoom-params" meta="type default"}

params.ui.image_zoom

enable boolean defaultfalse
Turn image zoom on
selector string default.td-content
Root selector scanned for candidate images

Every entry is linkable

Each entry gets an anchor of the form field-<name>, and a self-link icon appears beside the name on hover. page_width in the first table above is #field-page_width — a link you can send on its own when answering a question.

Duplicate names on one page get -2, -3 suffixes, the same rule Goldmark uses for duplicate headings. Anchors are generated in HTML only: print and RSS assemble many pages into one document, where in-page anchors would collide.

The shortcode form

When the description needs several paragraphs, a list or a code block, a table cell cannot hold it. Use fields/field:

Source
{{< fields label="Common pig flags" >}}
{{< field name="--config" type="path" required=true >}}
Path to the configuration file. Relative paths resolve against the working
directory.

When `PIG_CONFIG` is also set, the command-line flag wins.
{{< /field >}}
{{< field name="--log-level" type="string" default="info" >}}
Log level, from low to high:

- `debug`: print every remote call
- `info`: the default
- `error`: output only on failure
{{< /field >}}
{{< field name="--dry-run" type="boolean" default=false >}}
Print what would happen and change nothing:

```bash
pig ext install pg_duckdb --dry-run
```
{{< /field >}}
{{< /fields >}}

Common pig flags

--config path required

Path to the configuration file. Relative paths resolve against the working directory.

When PIG_CONFIG is also set, the command-line flag wins.

--log-level string defaultinfo

Log level, from low to high:

  • debug: print every remote call
  • info: the default
  • error: output only on failure
--dry-run boolean defaultfalse

Print what would happen and change nothing:

pig ext install pg_duckdb --dry-run

required=true and default=false are booleans and take no quotes. default accepts any scalar: default=0 and default="" both display faithfully (the empty string shows as ""), and omitting default omits the chip. Every field needs a non-empty body and must be a direct child of fields.

Which form to use

Situation Use
One-sentence descriptions that fit in a table cell table + {.fields}
Descriptions with paragraphs, lists or code blocks the fields/field shortcode
Readers comparing many rows across the same columns a plain table, not a field list
Content that is a sequence of actions Steps

The table form stays a readable table on GitHub, and OINK’s Markdown output keeps it as a table. That is why it is the default.

Output

Output Shape
HTML <div class="td-fields"> around a semantic <dl>; entries carry #field-<name> anchors and self-links
Print The complete definition list, without entry anchors
Markdown The table form keeps the source table; the shortcode form emits a bulleted list of “name — type; required; default: value” plus the indented description
RSS The complete static <dl>, without entry anchors

No script is loaded.

Parameter reference

The table attribute line, on the row below the table:

.fields marker defaultnone
Required; renders the table as a field list
meta role list defaultnone
Space-separated type required default -; one per middle column; semantic roles cannot repeat
caption plain text defaultnone
Visible label and the list’s accessible name
id identifier defaultnone
ID of the outer container
class class list defaultnone
Passed through for site CSS
data-* / aria-* string defaultnone
Passed through

The fields shortcode:

label non-empty string required
Visible label; the same thing the table’s caption does
id identifier required
Container ID; no whitespace, quotes, <, > or &
class / data-* / aria-* string required
The same policy as the table attribute line

The field shortcode:

name non-empty string required
The field name
type non-empty string required
Type label such as boolean, string[], duration
required boolean required
true shows the untranslated required chip; defaults to false
default scalar required
String / boolean / integer / float; false, 0 and "" all display

Limits

  • The first column must be non-empty and unique within one table; a duplicate or empty name warns and skips that row, and strict publishing rejects the warning.
  • .fields cannot combine with .matrix, .full-width or num, and meta cannot appear on a table without .fields.
  • Block content does not fit in a table cell: paragraphs, lists and fences need the shortcode form.
  • required and default are untranslated API vocabulary and stay in English in every language. They are contract words, not interface copy.
  • No kind, since, deprecated, location, per-field links or nested structures, and nothing parses TypeScript or an OpenAPI schema at build time.
  • Tables — the rest of the attribute line and the exclusion rules
  • Configuration — the full site parameter table, itself a field list
  • Front matter — the full front matter table
  • Steps — ordered actions do not belong in a field list
Last modified 2026-09-03 · docs(i18n): clarify Hugo 0.160 Chinese locale config (bb79ec1)