Args
Use the args shortcode to generates a table of structured arguments.
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. | ||
| parent | bool | Flag to filter only arguments that have a parent attribute (either cascade or merge). |
||
| 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. |
{{< args "args" >}}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. | ||
| parent | bool | Flag to filter only arguments that have a parent attribute (either cascade or merge). |
||
| 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. |
Define a file in the data/structures folder that contains the argument specifications.
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. |
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. |
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.
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:
type: string
optional: true
comment: >-
Title of the card, replaces the title of the referenced page (if any).
path:
type: path
optional: true
comment: >-
Path of the page that the card reference to. If omitted, specify the
title, icon, thumbnail, and description (inner content) as needed.
href:
type: url
optional: true
comment: >-
Address for the button or hyperlink.
group: partial
class:
type: string
optional: true
parent: merge
comment: >-
Class attribute of the card element, e.g. “w-50”.
color:
type: select
optional: true
parent: cascade
comment: >-
Theme color of the card. By default, no color is specified.
options:
values:
- primary
- secondary
- success
- danger
- warning
- info
- light
- dark
- white
- black
- body
- body-tertiary
padding:
type: select
optional: true
default: auto
parent: cascade
comment: >-
Padding of the content.
options:
values:
- "0"
- "1"
- "2"
- "3"
- "4"
- "5"
- "auto"
gutter:
type: select
optional: true
default: "0"
parent: cascade
comment: >-
Gutter between columns in a group.
options:
values:
- "0"
- "1"
- "2"
- "3"
- "4"
- "5"
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
body:
type: select
optional: true
default: full
parent: cascade
release: v0.24.16
comment: >-
Body of the card.
options:
values:
- full
- title
- none
footer:
type: select
optional: true
default: none
parent: cascade
comment: >-
Footer components of the card, displayed in small caps.
options:
values:
- full
- publication
- tags
- none
description:
type:
- string
- template.HTML
optional: true
comment: >-
Description of the card.
group: partial
loading:
type: select
optional: true
parent: cascade
default: eager
comment: >-
Loading behavior of the image. The loading of lazily loaded images is
deferred until the image is within scrolling range of the viewport. This
should reduce the initial loading time of the website. It is recommended
to lazily load only those images that are below the page fold.
options:
values:
- lazy
- eager
group: partial
thumbnail:
type: path
optional: true
comment: >-
Thumbnail image url, displayed on top or the left of the card.
ratio:
type: select
optional: true
parent: cascade
comment: >-
Ratio of the thumbnail image, defaults to `16x9` (stacked orientation)
or `1x1` (horizontal orientation).
options:
values:
- 1x1
- 3x2
- 4x3
- 16x9
- 21x9
group: partial
portrait:
type: bool
parent: cascade
optional: true
default: false
release: v0.24.16
comment: >-
Flag to adjust the ratio from landscape to portrait. The image itself is
not rotated, only the crop area is adjusted. Not applicable to vector
graphics.
alt:
type: string
optional: true
release: v0.19.0
comment: >-
Alternate text for the thumbnail, uses `title` by default.
icon:
type: string
optional: true
comment: >-
Font Awesome icon, displayed on top or the left of the card.
iconRounded:
type: bool
parent: cascade
optional: true
release: v0.24.8
comment: Stack the icon in a round container.
align:
type: select
parent: cascade
optional: true
default: start
release: v0.23.0
comment: Icon alignment.
options:
values:
- start
- end
- center
scroll:
type: bool
parent: cascade
optional: true
group: partial
comment: >-
Enables horizontal scrolling of the cards. By default, the card group
wraps any cards beyond the amount of defined columns to a new line. When
`scroll` is set to true, a horizontal scroll bar is added instead.
wrapper:
type: string
optional: true
comment: Element class of the card wrapper.
style:
type: string
parent: cascade
optional: true
release: v0.23.0
comment: Icon style.
orientation:
type: select
optional: true
default: stacked
parent: cascade
comment: Placement of the thumbnail or icon.
options:
values:
- stacked
- horizontal
- horizontal-sm
- overlay
- none
subtle:
type: bool
parent: cascade
optional: true
release: v0.23.0
comment: Apply subtle background colors.
button:
type: bool
parent: cascade
optional: true
release: v0.23.0
comment: >-
Flag indicating the cards should include a button that links to the provided address.
buttonLabel:
type: string
optional: true
release: v0.23.2
comment: >-
Label of the link button, defaults to the card title.
buttonType:
type: select
parent: cascade
optional: true
default: button
comment: Type of the button element.
release: v0.23.18
options:
values:
- link
- button
hook:
type: string
optional: true
comment: Render hook for the image partial.
group: partial
sizes:
type: string
default: 100vw
optional: true
comment: >-
One or more strings separated by commas, indicating the source sizes of an
image set.
group: partial
anchor:
type: select
optional: true
comment:
Anchor of the thumbnail's crop box, defaults to anchor value set in
`imaging` section of the site configuration (usually `Smart`).
options:
values:
- TopLeft
- Top
- TopRight
- Left
- Center
- Right
- BottomLeft
- Bottom
- BottomRight
- Smart
release: v0.24.23
body:
optional: true
comment: >-
Description of the card.
group: shortcode