Docs

Args

Posted on January 4, 2024  (Last modified on June 20, 2025) • 7 min read • 1,475 words
Component  
Component  
Share via

Use the args shortcode to generates a table of structured arguments.

Overview   Arguments   Data Format   Supported Attributes   Supported Primitive Types   Supported Complex Types   Example File  

Overview  

Added in v0.22.0   

Use the args shortcode to generates a table of structured arguments. The argument definitions are expected to be defined in a data file identified by a provided structure name.

Name Type Required Default Comment
group string Name of the group filter. This is typically used when a shortcode and partial have common arguments. The group filter binds a specific argument to a particular group. By default, an argument belongs to all groups.
header-level int 3 v1.0.0      The header level to use for the user-defined type headers. Supported values: [1 - 6].
page *hugolib.pageState, *hugolib.pageForRenderHooks, *hugolib.pageForShortcode yes Context of the current page.
parent bool Flag to filter only arguments that have a parent attribute (either cascade or merge).
render-type select both v1.0.0      Option whether to render arguments, user-defined types, or both. Please note that the arguments will render a link to a user-defined type in any case. Supported values: [arguments, types, both].
structure string yes Name of the data file that contains argument definitions. Supported data formats include JSON, TOML, YAML, and XML. You can omit the file extension. The file should reside in the data/structures folder. For bookshop components, add the bookshop- prefix to the structure name.
Name Type Required Default
group string
Name of the group filter. This is typically used when a shortcode and partial have common arguments. The group filter binds a specific argument to a particular group. By default, an argument belongs to all groups.
header-level int 3
v1.0.0      The header level to use for the user-defined type headers. Supported values: [1 - 6].
page *hugolib.pageState, *hugolib.pageForRenderHooks, *hugolib.pageForShortcode yes
Context of the current page.
parent bool
Flag to filter only arguments that have a parent attribute (either cascade or merge).
render-type select both
v1.0.0      Option whether to render arguments, user-defined types, or both. Please note that the arguments will render a link to a user-defined type in any case. Supported values: [arguments, types, both].
structure string yes
Name of the data file that contains argument definitions. Supported data formats include JSON, TOML, YAML, and XML. You can omit the file extension. The file should reside in the data/structures folder. For bookshop components, add the bookshop- prefix to the structure name.
markdown 
{{< args "args" >}}

Arguments  

The shortcode supports both unnamed and named arguments.

Name Type Required Default Comment
group string Name of the group filter. This is typically used when a shortcode and partial have common arguments. The group filter binds a specific argument to a particular group. By default, an argument belongs to all groups.
header-level int 3 v1.0.0      The header level to use for the user-defined type headers. Supported values: [1 - 6].
page *hugolib.pageState, *hugolib.pageForRenderHooks, *hugolib.pageForShortcode yes Context of the current page.
parent bool Flag to filter only arguments that have a parent attribute (either cascade or merge).
render-type select both v1.0.0      Option whether to render arguments, user-defined types, or both. Please note that the arguments will render a link to a user-defined type in any case. Supported values: [arguments, types, both].
structure string yes Name of the data file that contains argument definitions. Supported data formats include JSON, TOML, YAML, and XML. You can omit the file extension. The file should reside in the data/structures folder. For bookshop components, add the bookshop- prefix to the structure name.
Name Type Required Default
group string
Name of the group filter. This is typically used when a shortcode and partial have common arguments. The group filter binds a specific argument to a particular group. By default, an argument belongs to all groups.
header-level int 3
v1.0.0      The header level to use for the user-defined type headers. Supported values: [1 - 6].
page *hugolib.pageState, *hugolib.pageForRenderHooks, *hugolib.pageForShortcode yes
Context of the current page.
parent bool
Flag to filter only arguments that have a parent attribute (either cascade or merge).
render-type select both
v1.0.0      Option whether to render arguments, user-defined types, or both. Please note that the arguments will render a link to a user-defined type in any case. Supported values: [arguments, types, both].
structure string yes
Name of the data file that contains argument definitions. Supported data formats include JSON, TOML, YAML, and XML. You can omit the file extension. The file should reside in the data/structures folder. For bookshop components, add the bookshop- prefix to the structure name.

Data Format  

Define a file in the data/structures folder that contains the argument specifications.

Supported Attributes  

The format supports the following attributes:

Name Required Description
name yes Argument name.
type yes Data type of the argument, either a primitive or complex type.
optional Flag to indicate if the argument is optional, defaults to false.
default Default value when no value is provided.
parent Defines if the argument inherits a value from its parent, either cascade or merge.
release Points to the version in which the argument was released. See the Release shortcode for more details.
deprecated Points to the version in which the argument was deprecated. See the Release shortcode for more details.
comment Documentation about the argument.
options Conditional value requirements, pending data type.

Supported Primitive Types  

Several primitives are supported. The validation function uses these to test if the provided argument value conforms to the expected data type.

Primitive Description
bool Boolean, either true or false. The validation supports both quoted and unquoted values. Maps to the Hugo type bool.
string Free format plain text. Maps to the Hugo type string.
int A whole number, including negative values. Optionally, specify the allowed value range using options.min and options.max. Maps to the Hugo type int.
float A fractional number, including negative values. Optionally, specify the allowed value range using options.min and options.max. Maps to the Hugo type float64.
select A single string value from a set of options. Specify the allowed values in options.values. Maps to the Hugo type string.
datetime A date with optional time value.
url A web address to a particular file or page. The address should include the protocol, hostname, and optional file name. Maps to the Hugo type string.
path Path to a local file or directory. By convention, paths that start with / are relative to the repository root. When used as source argument, the base directory may be mapped to one of Hugo’s mount folders (e.g. assets, data, content, static). Windows paths are mapped to Unix-style paths using forward slashes. Maps to the Hugo type string.

Supported Complex Types  

Any provided type not matching a primitive is considered a complex type. Type confirmation is tested with printf "%T". For example, to validate if the page context is of the correct type, use *hugolib.pageState.

Example File  

The following file illustrates the definition of the card shortcode and partial.

comment: >-
  Displays a Bootstrap card. Either specify a valid path, or set the arguments
  title, href, header, description, and thumbnail individually. The latter
  arguments override any page attributes.
arguments:
  title:
    optional: true
  path:
  href:
    group: partial
  class:
    parent: merge
  color:
    optional: true
    parent: cascade
  padding:
    parent: cascade
  gutter:
    default: 0
    parent: cascade
  header-style:
    parent: cascade
    release: 1.0.0
  body-style:
    parent: cascade
    release: 1.0.0
  footer-style:
    parent: cascade
    release: 1.0.0
  description:
    group: partial
  loading:
    parent: cascade
    group: partial
  thumbnail:
  ratio:
    parent: cascade
    group: partial
  portrait:
    parent: cascade
    release: v0.24.16
  alt:
    release: v0.19.0
  icon:
  icon-rounded:
    release: v1.0.0
  align:
    parent: cascade
    release: v0.23.0
  scroll:
    parent: cascade
    group: partial
  wrapper:
  icon-style:
    release: v1.0.0
  orientation:
    parent: cascade
  subtle:
    parent: cascade
    release: v0.23.0
  button:
    parent: cascade
    release: v0.23.0
  button-label:
    release: v1.0.0
  link-type:
  hook:
    default: assets/image.html
    group: partial
  sizes:
    group: partial
  anchor:
    release: v0.24.23
  # deprecated arguments
  header:
    type: select
    optional: true
    default: full
    parent: cascade
    comment: >-
      Header components of the card, displayed in small caps. 
    options:
      values:
        - full
        - publication
        - tags
        - none
    deprecated: 1.0.0
    alternative: header-style
  body:
    type: select
    optional: true
    default: full
    parent: cascade
    release: v0.24.16
    comment: >-
      Body components of the element. 
    options:
      values:
        - full
        - title
        - none
    deprecated: 1.0.0
    alternative: body-style
  footer:
    type: select
    optional: true
    default: none
    parent: cascade
    comment: >-
      Footer components of the element, displayed in small caps.
    options:
      values:
        - full
        - publication
        - tags
        - none
    deprecated: v1.0.0
    alternative: footer-style
  iconRounded:
    type: bool
    parent: cascade
    optional: true
    release: v0.24.8
    deprecated: v1.0.0
    alternative: icon-rounded
    comment: Stack the icon in a round container.
  buttonType:
    type: select
    parent: cascade
    optional: true
    default: button
    comment: Type of the button element.
    release: v0.23.18
    deprecated: v1.0.0
    alternative: link-type
    options:
      values:
        - link
        - button
  style:
    type: string
    parent: cascade
    optional: true
    release: v0.23.0
    comment: Icon style.
    deprecated: v1.0.0
    alternative: icon-style
  buttonLabel:
    type: string
    optional: true
    release: v0.23.2
    comment: >-
      Label of the link button, defaults to the card title.
    deprecated: v1.0.0
    alternative: button-label
body:
  optional: true
  comment: >-
    Description of the card.
  group: shortcode
On this page: