Shortcodes

Alerts, captioned images and task lists.

Shortcodes are small snippets you put in Markdown to get something Markdown cannot do on its own. Lowkey adds three.

Alert

A colored box that draws attention to a note:

{{< alert info "Did you know?" >}}
Alerts have four colors.
{{< /alert >}}

The first value is the type, the second is an optional title.

Info

Extra context or a helpful tip.

Success

Something worked, or a recommended way of doing things.

Warning

Something to be careful about.

Error

Something that will break if ignored.

Leave out the title for a compact box:

An alert without a title.

The text inside an alert is HTML, not Markdown. Use tags such as <b>, <code> and <a href="…"> for formatting:

{{< alert warning >}}
Run <code>npm install</code> before <b>hugo server</b>.
{{< /alert >}}

Run npm install before hugo server.

Alerts switch to dark colors in dark mode.

Image

Shows an image from the post’s own folder, with an optional caption. The post must be a page bundle.

{{< img src="cat.jpg" alt="A Siamese cat" caption="Meet the office cat." caption-position="center" >}}

Option	Required	What it does
`src`	yes	File name inside the post’s folder. Wildcards such as `cat.*` also work.
`alt`	no	Text read by screen readers and shown if the image fails to load. Always fill it in.
`caption`	no	Text under the image.
`caption-position`	no	`center` or `end`. Leave it out to align the caption left.

The image gets its real width and height, so the page does not jump while it loads. If the file cannot be found, the build stops and names the post and line:

img shortcode: "dog.jpg" not found in page bundle. "content/posts/my-trip/index.md:12:1"

See it in action in the Markdown Cheat Sheet.

Task list

Markdown task lists normally keep their bullet points next to the checkboxes. Put task-list on the line before the list to remove them:

{{< task-list >}}

- [x] Write the post
- [ ] Add a cover image
- [ ] Publish

Write the post
Add a cover image
Publish

Hugo’s built-in shortcodes

Hugo ships its own shortcodes, and they all work with Lowkey. The most useful ones:

Shortcode	Use it for
`youtube`	Embedding a YouTube video by its ID
`vimeo`	Embedding a Vimeo video
`gist`	Embedding a GitHub Gist
`figure`	An image with more options than `img`, including images outside the page bundle
`highlight`	Code highlighting with options, inside other shortcodes

See Hugo’s shortcode documentation for their options. To write your own, see Overriding templates.