Shortcodes

In addition to the default Hugo shortcodes, govuk-hugo includes the following custom shortcodes, most of which are intended to make it easier to add GOV.UK Design System components.

In-page table of contents

An in-page table of contents, suitable for long-form articles can be included by using the shortcode {{< TOC >}} within your document. Preferably, you should include this after the first section of text but before the first secondary heading.

Paragraph styling

You can use the lead and small paragraph typography through the <</* lead */>> and <</* small */>> shortcodes. These shortcodes do not take arguments, simply use an opening and then closing shortcode to apply the styling.

1
{{< lead >}}A lead paragraph{{< /lead >}}

A lead paragraph

1
{{< small >}}A lead paragraph{{< /small >}}

A small paragraph

Section breaks

By default govukhugo renders section breaks into invisible breaks using the GOV.UK design system’s large section break. The break shortcode allows you to set custom sizes (xl, l or m), you can make a break visible by setting that argument to true.

1
2
3
4
5
6
7
8
A section followed by an invisible `xl` break.
{{< break type="xl" >}}
A section followed by a visible `xl` break.
{{< break type="xl" visible=true >}}
A section followed by a visible `l` break.
{{< break type="l" visible=true >}}
A section followed by a visible `m` break.
{{< break type="m" visible=true >}}

A section followed by an invisible xl break.


A section followed a visible xl break.


A section followed a visible l break.


A section followed a visible m break.


Details

You can add the details component using the {{< details >}} shortcode. In the opening shortcode you specify the summary text, while between that and a closing {{< /details >}} shortcode you include the content that you wish to be revealed when the user chooses to expand the details section.

1
2
3
4
{{< details "More information" >}}
The details component allows you to hide more detailed information 
that might be relevant to only some users.
{{< /details >}}
More information
The details component allows you to hide more detailed information that might be relevant to only some users.

Warning text

You can add the warning text component using the {{< warning >}} shortcode.

1
{{< warning "This is experimental and still under development" >}}
Warning This is experimental and still under development

You can add the button component to style links as buttons using the {{< link_button >}} shortcode. You must name the arguments link (the link to visit) and text (the text for the button). These links will always open in a new tab/window.

1
{{< link_button link="https://www.gov.uk" text="Go to GOV.UK" >}}

Go to GOV.UK

Optionally you can add a type argument to set the button as one of the alternative styles (a secondary button or a warning button).

1
2
{{< link_button link="https://www.gov.uk" text="Go to GOV.UK" type="secondary" >}}
{{< link_button link="https://www.gov.uk" text="Go to GOV.UK" type="warning" >}}

Go to GOV.UK Go to GOV.UK

You can add a file download component to style links as downloads using the {{< download_file >}} shortcode. As with button links must name the arguments link (the link to visit) and text (the text for the button), you must also specify the file type (e.g. “PDF”, “ODS”, “CSV”) and the file size (e.g. “42KB”, “1.4MB”).

1
2
{{< download_file link="my_file.ods" text="Download the spreadsheet" 
     type="ODS" size="1.4MB" >}}

Notification banners

You can add the neutral notification banner component using the {{< notification */}} shortcode. In the opening shortcode specify the banner heading, while between that and a closing {{</* /notification >}} banner you include the content of the notification message.

1
2
3
{{< notification "Important" >}}
Here is an important notice
{{< /notification >}}

Important

Here is an important notice

You can add the success notification banner using the {{< success >}} shortcode.

1
2
3
{{< success "Success" >}}
You have succeeded
{{< /success >}}

If you need to include further information then include you should provide the title and message as named arguments to the shortcode and include the further information within the opening and closing shortcodes. Note you will need to use raw HTML tags for inner content rather than markdown.

1
2
3
{{< success title="Success" message="You have succeeded" >}}
Please visit <a href="https://www.gov.uk">GOV.UK</a> for further details.
{{< /success >}}

Tag

You can add the tag component using the {{< tag >}} shortcode.

1
{{< tag "Tag" >}}

Tag

Optionally you can define a colour (one of grey, green, turquoise, blue, purple, pink, red, orange or yellow), in this case you will need to provide the tag label as the argument title. When using alongside the standard tag, the convention is to use grey.

Shortcode Tag
{{< tag "Tag" >}} Tag
{{< tag title="Grey tag" colour="grey" >}} Grey tag
{{< tag title="Green tag" colour="green" >}} Green tag
{{< tag title="Turquoise tag" colour="turquoise" >}} Turquoise tag
{{< tag title="Blue tag" colour="blue" >}} Blue tag
{{< tag title="Purple tag" colour="purple" >}} Purple tag
{{< tag title="Pink tag" colour="pink" >}} Pink tag
{{< tag title="Red tag" colour="red" >}} Red tag
{{< tag title="Orange tag" colour="orange" >}} Orange tag
{{< tag title="Yellow tag" colour="yellow" >}} Yellow tag