Fields and Field

Describe configuration, parameters, properties, and response fields with responsive semantic HTML.

Categories:

Components

Use fields with field children to document named values and their metadata. The component favors a responsive definition list over a wide fixed table, so long names and descriptions remain usable on narrow screens.

When to use

Fields works for configuration keys, command or API parameters, object properties, and response members. Use a regular Markdown table when readers must compare many rows across the same columns. Use prose when the entries are steps rather than definitions.

Quick start

Source

GO-HTML-TEMPLATE

{{< fields label="Search configuration" >}}
  {{< field name="offlineSearch" type="boolean" required=true default=true >}}
  Builds a **local** search index and command palette.
  {{< /field >}}

  {{< field name="offlineSearchMaxResults" type="integer" default=10 >}}
  Limits the number of visible results.
  {{< /field >}}
{{< /fields >}}

Rendered result

Search configuration

offlineSearch , boolean , required , default: true: Builds a local search index and command palette.
offlineSearchMaxResults , integer , default: 10: Limits the number of visible results while retaining keyboard navigation.
searchPlaceholder , string , default: "": Sets optional placeholder text. The empty-string default remains visible.
theme.components.media.previewMaximumWidthInCharacters , string , default: auto: This deliberately long field name demonstrates wrapping without widening the page.

Descriptions accept Markdown, including links, emphasis, inline code, and lists. Keep each description self-contained because Markdown output presents each one beneath its metadata.

Fields parameters

fields parameters

label , string: A nonempty visible label associated with the complete definition list.

The container must have at least one direct field child. Text or another shortcode directly inside fields stops the build.

Field parameters

field parameters

name , string , required: A nonempty string identifying the field.
type , string: A nonempty type label such as boolean, string[], or duration.
required , boolean , default: false: When true, adds the literal required marker. The marker is untranslated API vocabulary.
default , scalar: A string, boolean, integer, or floating-point value. false, 0, and "" are preserved.

Every field also requires a nonempty body. It must be a direct child of fields. Parameter names and types are validated at build time, and unknown parameters are errors.

Semantics and fallback

HTML uses dl, dt, and dd. Each entry stacks a header row — the field name followed by its type, required, and default markers — above the description, and hairline dividers separate entries. The required and default labels stay in English in every locale. The optional label names the definition list for assistive technology. Markdown emits an indented bullet list with code-formatted names, types, and defaults; print and RSS retain every definition. No JavaScript is loaded.

Deliberate limits

Version one does not implement kind, deprecated, since, location, or per-field links. It also does not parse TypeScript or an API schema inside Hugo. An external generator may emit these shortcodes later, keeping compiler and schema runtimes outside the theme while preserving this output contract.

JavaScript is required to load comments. View discussions on GitHub.