Docs

Args

Use the args shortcode to generates a table of structured arguments.
Overview   Data Format   Options Type   Arguments  

Overview  

Added in v0.22.0     

Use the args shortcode to generate 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.
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.
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" >}}

Data Format  

Arguments support the following elements:

Name Type Required Default Comment
comment string Documentation about the argument.
default string Default value when no value is provided.
deprecated string Points to the version in which the argument was deprecated (it may include the v prefix).
name string yes Argument name.
optional string Flag to indicate if the argument is optional.
options Options Conditional value requirements, depending on data type.
parent select Defines if the argument inherits a value from its parent. The value cascade indicates the child element should inherit the entire parent’s value. When set to merge, the parent and child values are merged together separated by a space character. Supported values: [cascade, merge].
release string Points to the version in which the argument was released (it may include the v prefix).
type string yes Data type of the argument, either a primitive or complex type. Supported primitive types are bool, int, int64, float, float64, string, dict, and slice. Complex types can either be a dict or a slice and should be defined in data/_types.yml.
Name Type Required Default
comment string
Documentation about the argument.
default string
Default value when no value is provided.
deprecated string
Points to the version in which the argument was deprecated (it may include the v prefix).
name string yes
Argument name.
optional string
Flag to indicate if the argument is optional.
options Options
Conditional value requirements, depending on data type.
parent select
Defines if the argument inherits a value from its parent. The value cascade indicates the child element should inherit the entire parent’s value. When set to merge, the parent and child values are merged together separated by a space character. Supported values: [cascade, merge].
release string
Points to the version in which the argument was released (it may include the v prefix).
type string yes
Data type of the argument, either a primitive or complex type. Supported primitive types are bool, int, int64, float, float64, string, dict, and slice. Complex types can either be a dict or a slice and should be defined in data/_types.yml.

Options Type  

Name Type Required Default Comment
max int End of the value range (inclusive).
min int Start of the value range (inclusive).
values slice A slice of permitted select values.
Name Type Required Default
max int
End of the value range (inclusive).
min int
Start of the value range (inclusive).
values slice
A slice of permitted select values.

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.
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.
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.
On this page