Hugo’s built-in internal shortcodes

Hugo ships with a few shortcodes to handle your own content and configuration.

Resolve internal URLs

To refer to a page on our site we can include the URL into a link like any other. But it’s often long and when our content grows and evolves, the path may change. Therefore, we may leave the resolution to Hugo by using an unambiguous name for the page.

If the name of a page is not unique, we still need to fill in the complete relative path. The advantage of relref is, that Hugo checks the existence of the file and issues a warning or an error.

To replace unique names with URLs, Hugo provides relref or ref. Internal links with these shortcodes look like

[Link]({{< relref "doc/basic/link" >}})
[Introduction]({{< ref "intro" >}})

relref

returns the relative URL of the page, which is usually the better option. Perplex then can distinguish between internal and external URLs and style the links with two different colors.

ref

returns always the absolute URL of the page, which may be necessary under special circumstances.

Show a figure

Markdown contains no element, that gets rendered into a figure, because this is a task beyond simple markup. Therefore, Hugo includes the figure shortcode with many options and the possibility to add styling classes. The resulting HTML includes just the original image, because the internal shortcode is a minimal default and meant to be overridden by theme developers with their specific version.

Perplex does override the built-in figure shortcode with its own, but the variables are kept in place. There are no adjustments necessary. Additional options are presented on the page for the theme figure

highlight Code

The highlight shortcode is complex and may use some additional CSS files.

<section id="main">
  <div>
   <h1 id="title">{{ .Title }}</h1>
    {{ range .Pages }}
        {{ .Render "summary"}}
    {{ end }}
  </div>
</section>

Get parameters with param

We can show a configuration parameter in the content with this shortcode. Their values always get converted to a string:

• The title of this page with {{< param title >}} as “Hugo’s built-in internal shortcodes”.

• The parent of the menu entry with {{< param menu.doc.parent >}} as “shortcode”.

• The description with {{< param description >}} as “Simplify common tasks”.