Shortcodes

Platen relies on Hugo’s shortcodes feature to help you go beyond basic Markdown when authoring the digital editions of your books. Without shortcodes, you are limited to static elements, like headers, paragraphs, lists, and tables. With shortcodes, you can embed iframes, create forms, make your tables interactive, and more—without having to hand-write HTML in your Markdown files.

Using shortcodes #

Shortcodes always have a tag. Some shortcodes require both opening and closing tags.

Basic shortcodes
When a shortcode doesn’t require a closing tag, write it like this:
{{% ShortcodeName parameters %}}

Where ShortcodeName is the name of the shortcode, like ref, and parameters is the list of values to pass to the shortcode separated by spaces. For example:

{{% ref "/docs/tutorials/getting-started.md" %}}
{{% twitter "dril" "1576784267769618433" %}}
Named parameter shortcodes
Some shortcodes use named parameters instead of positional ones. Write them like this:
{{% ShortcodeName ParameterName=ParameterValue %}}

For example:

{{% itchio id="1299168" square=true %}}
Paired shortcodes
When shortcodes require inner text, they also require paired tags to open and close the shortcode. Write them like this, with a / before the shortcode name in the closing tag:
{{% ShortcodeName parameters %}}
{{% /ShortCodeName %}}
{{% ShortcodeName ParamaterName=ParameterValue %}}
{{% /ShortCodeName %}}

For example:

{{% details "warning" "Credentials in Repositories" %}}
Don't include your credentials---API tokens, passwords, etc---in your site's
repository. If you do, they're publicly available to anyone who can see your
source files.
{{% /details %}}
{{% details title="Credentials in Repositories" class="warning" %}}
Don't include your credentials---API tokens, passwords, etc---in your site's
repository. If you do, they're publicly available to anyone who can see your
source files.
{{% /details %}}

There’s more nuance about shortcodes, but this covers the majority of use cases. For more information on shortcodes, see the Hugo documentation.

Hugo’s shortcodes #

Hugo itself provides several shortcodes:

  • figure extends your ability to place images on a page, using the <figure> HTML element instead of the simpler—but less versatile—image tag Markdown supports.
  • instagram enables you to embed an image from Instagram.
  • param is useful for debugging, allowing you to check the value of a page or site parameter without having to do any special coding.
  • ref and relref help you cross reference your site, creating permalinks and handling complex features like linking across language versions or to other formats.
  • tweet enables you to embed tweets in a consistent way.
  • vimeo and youtube enable you to embed videos from those platforms.

Creating shortcodes #

You can also create your own shortcodes if the ones Hugo and Platen provide don’t meet your needs. If you find yourself wishing a shortcode existed though, you can always reach out or file an issue and we’ll be happy to see if we can help.

Edit this page