Fields
{.fields} to a table to document configuration keys, command flags, and API fields. Entries adapt to narrow screens and have individual anchors.Fields display named values, metadata, and descriptions as a responsive definition list. Each name has its own line. Small chips beside it show type, required status, and default value. The description starts on the next line. Each entry has an anchor. Use fields for configuration keys, command flags, and API fields. Use a plain table to compare many rows across the same columns. Use steps for sequences of actions.
There are two forms. Use a plain table with {.fields} by default.
Use fields/field shortcodes for descriptions with multiple paragraphs, lists, or code blocks. Both forms display the same entries.
Shortest form
Write a pipe table with at least two columns, then put {.fields} on the next line.
The first column is the name. The last is the description. Middle columns are metadata labeled with their header text.
Metadata appears as “Header: value”. The theme does not infer meaning from headers. Type is only a label.
The next section explains standard chips. Cells accept inline Markdown, including code, emphasis, and links. Empty middle cells are omitted.
Semantic columns with meta=
meta assigns a role to each middle column, in order: type, required, default, or - for a plain header label.
With this attribute, tables display the same chips as shortcodes.
The rules:
metashould specify one role per middle column: the total column count minus two. Too many or too few roles warns and ignoresmeta. Review the warning and rendered fallback before publication.- Every nonempty
requiredcell means true. “yes”, “是”, and “✔” all display the untranslatedrequiredchip. Empty cells display nothing. Leave optional fields empty, becausenoand否also mean true. typeanddefaultcells without their own inline markup receive code formatting, as in the shortcode form.- Semantic chips always appear in this order:
type,required,default, regardless of column order.-columns follow in their original order.
Combine - with semantic roles to keep a custom label:
Labels and container IDs
caption sets the list’s visible label and accessible name. id identifies the outer container for links or styles.
params.ui
Every entry is linkable
Each entry has a field-<name> anchor. A self-link icon appears beside the name on hover.
For example, page_width in the first table has #field-page_width. Share this link to refer to that entry.
Duplicate names on a page receive -2 and -3 suffixes, as Goldmark does for duplicate headings.
Only HTML generates these anchors. Print and RSS combine pages into one document, where these anchors would collide.
The shortcode form
If a description needs multiple paragraphs, a list, or a code block, use fields/field. A table cell cannot contain these blocks.
Common pig flags
required=true and default=false are booleans. Do not quote them.
default accepts any scalar. Both default=0 and default="" display their values; the empty string appears as "".
If you omit default, the chip is omitted. Every field needs a nonempty 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 readable on GitHub and remains a table in OINK’s Markdown output. It is therefore the default.
Output
| Output | Shape |
|---|---|
| HTML | <div class="td-fields"> around a semantic <dl>; entries carry #field-<name> anchors and self-links |
| 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:
The fields shortcode:
The field shortcode:
Limits
- The first column must be nonempty and unique within each table. Empty or duplicate names warn and skip the row.
.fieldscannot be combined with.matrix,.full-width, ornum.metarequires a table with.fields.- Table cells cannot contain block content. Use shortcodes for paragraphs, lists, and fences.
requiredanddefaultremain untranslated English API terms in every language. They are contract terms, not interface text.- Fields do not support
kind,since,deprecated,location, per-field links, or nested structures. They do not parse TypeScript or OpenAPI schemas at build time.
Related
- 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