Shortcodes

Shortcodes are utilities that help simplify adding pieces to your page and help us keep them consistent across all pages. Because shortcodes are processed separately from Markdown, they are only available in pages that begin with front matter.

Images

To add an image to your Handbook page, first put it somewhere in the _img directory. Then, you can reference that image using a shortcode that will copy it into the correct place in the output and provide a URL to that image. There are two shortcodes, depending on your needs. Most commonly, you'll use the image shortcode:

{% image "_img/ocelot.png"
  "ocelot" %}

The first part after image is the path to the image and the second part is the alt text. The example above will result in this image being displayed:

If you need to apply a CSS class to your image for styling purposes, you can instead use the image_with_class shortcode, like so:

{% image_with_class
  "_img/ocelot.png"
  "usa-input--error"
  "alt text"
%}

Will result in this image being displayed:

Linking to other Handbook pages

Because the Handbook can be deployed in multiple environments, we need to take care with how we link between pages. Thankfully there's a shortcode to help! To link to another page in the Handbook, simply use the page shortcode with the path to the other page. For example:

{% page "updating-the-handbook/components" %}

This shortcode will produce a URL that is suitable for use in links, like so:

[Handbook components]
({% page "updating-the-handbook/components" %})

Will produce this correct link: Handbook components

Linking to Slack channels

Rather than hunting down the exact link to a Slack channel, the slack_channel shortcode enables you to quickly create a link to it based solely on the channel name. By default, the link is rendered with the channel name, but you can optionally set the link text to anything you want.

- {% slack_channel "tts-handbook" %}
- {% slack_channel
    "tts-handbook"
    "TTS Handbook community" %}

Produces this:

• , external,TTS-only, #tts-handbook
• , external,TTS-only, TTS Handbook community

Alert

The Handbook alert shortcode is a convenience wrapper around the , external,USWDS Alert component. It takes ordered arguments:

0. heading - The alert heading or title. If omitted, no heading is shown.
1. level - the alert level. Allowed values are info, warning, error, success, or info. If not provided, defaults to info.
2. content - the body of the alert. If omitted, no body is shown.
3. slim - provide if using the slim version of the alert banner.
4. no-icon - provide if omitting the icon.

Example:

{% alert %}
  A basic alert.
{% endalert %}

{% alert "Heads up!" %}
  This is the body of the info alert message, and the heading is above.
{% endalert %}

{% alert "An error has occurred." "error" "slim" "no-icon" %}
  This is the body of the error alert message.
{% endalert %}

Produces this:

USWDS Icons

The , external,US Web Design System includes , external,a set of icons that are available for use in the Handbook. The uswds_icon shortcode makes it nice and easy to get them:

{% uswds_icon "campaign" %}

Produces the following icon:

Downloadable files

To include a file for download in your Handbook page, you must use the download shortcode.

Arguments

• file path: The location of your file in the Handbook source code, relative to the source code base directory. For convenience, there is already a downloads directory you can use.

Returns the URL to a downloadable file.

Example:

If you have a file called my-form.pdf in the downloads directory, you need to use this shortcode to make the file available for download:

[download link]
({% download
  "downloads/my-form.pdf"
%})

Produces a link like this:

download link

Other internal links

Sometimes you need to create links that may be elsewhere in the Handbook or possibly external (for example, if you are iterating over a list of links provided in a data file). In those cases, use the link shortcode. This shortcode does nothing if the provided link begins with http or https, but for other cases, it modifies the link based on the Handbook's deployment environment. For example:

- [link 1]({% link "about-us/code-of-conduct" %})
- [link 2]({% link "https://www.gsa.gov" %})

Produces:

• link 1
• link 2

Identifying the current page

The Handbook has a CSS class called usa-current that can be used to identify an element as being associated with the current page. To simplify figuring out which element is "current," you can use the usa-current shortcode. This is primarily useful in navigation links where you are iterating over a list of URLs and want to know which one corresponds to the current page. The short code returns either the text usa-current if the URL is current or empty text otherwise, making it suitable to use as a class attribute.

<a href="my-page" class="
  {% usa-current list-item.path page.inputPath %}
">Some navigation link</a>

In this example, list-item is presumably a single item from a list and it has a path property. page is a variable provided by 11ty for each page, and inputPath is that page's location in the filesystem.