Shortcodes

This theme includes some useful custom shortcodes that you can use to enhance your posts. Whether you want to display a gallery of images, or format a professional-looking reference section, these custom shortcodes have got you covered.

Alert Shortcode#

Bring attention to information with these GitHub-style alert shortcodes. They come in five types: note, tip, info, warning, and danger.

You can change the title and icon of the alert. Both parameters take a string and default to the type of alert. icon can be any of the available alert types.

Usage#

You can use alerts in two ways:

1. Inline with parameters:

   {{ alert(type="danger", icon="tip", title="An important tip", text="Stay hydrated~") }}

2. With a content body:

   {% alert(type="danger", icon="tip", title="An important tip") %}
   Stay hydrated~
   
   This method is particularly useful for longer content or multiple paragraphs.
   {% end %}

Both methods support the same parameters (type, icon, and title), with the content either passed as the text parameter or as the body between tags.

> [!NOTE]
> This is a note.

Mastodon Shortcode#

Embed a Mastodon post into your content using the mastodon shortcode.

Usage#

{{ mastodon(url="https://hachyderm.io/@ebkalderon/114462281016082381") }}

References#

This shortcode formats a reference section with a hanging indent like so:

Usage#

{% references() %}

Your references go here.

Each in a new line. Markdown (links, italics...) will be rendered.

{% end %}

Responsive Image Shortcode#

Convert a high-resolution source image into a responsive image using the responsive_image shortcode.

By default, responsive_image will generate at most five versions of the source image, with the following maximum widths (measured in pixels):

1. 640×height
2. 784×height
3. 1280×height
4. 1920×height
5. 2560×height

The browser will automatically select the smallest possible resolution while still retaining visual sharpness. Which image the browser displays depends on the device's native screen resolution, pixel density, viewport size, etc.

Usage#

{{ responsive_image(src="example-hi-res-image.jpg", alt="Responsive hi-res image") }}

The default behavior of the responsive_image shortcode can be overridden by adding the following lines to your website's config.toml.

[extra.responsive_images]
widths = [640, 784, 1280, 1920, 2560]
fallback_width = 1280

Responsive images are lazy-loaded by default to improve performance for below-the-fold content (see MDN docs). This behavior can be overridden on a case-by-case basis by passing lazy=false to the responsive_image shortcode.

Wide Container Shortcode#

Use this shortcode if you want to have a wider table, paragraph, code block... On desktop, it will take up the width of the article. It will have no effect on mobile, except for tables, which will get a horizontal scroll.

Usage#

{% wide_container() %}

Place your code block, paragraph, table… here.

Markdown will of course be rendered.

{% end %}

Presentation Palette Shortcode#

Display the site's currently active presentation style and variant, along with a light/dark colour-palette swatch grid, using the presentation_palette shortcode. It takes no parameters — it reads extra.presentation_style and extra.presentation_variant directly from your site's config.toml, with the same fallback rules the theme itself uses (see CONSTITUTION.md §7), so the name and swatches shown always match whichever group/variant your site is actually configured for.

Usage#

{{ presentation_palette() }}

Light Mode Only / Dark Mode Only Shortcodes#

Show content only while the site is in light mode, or only while it's in dark mode, using the light_mode_only and dark_mode_only shortcodes. Neither takes any parameters — just wrap the content you want to restrict as the shortcode's body.

Visibility is done with pure CSS (no extra JavaScript beyond the theme switcher this theme already ships): if JavaScript is disabled, each shortcode falls back to your system's prefers-color-scheme instead of showing both, or neither.

Usage#

{% light_mode_only() %}

Only shown while the site is in light mode.

{% end %}

{% dark_mode_only() %}

Only shown while the site is in dark mode.

{% end %}

The body supports Markdown, and other shortcodes may be nested inside it, for example:

{% light_mode_only() %}

{{/* alert(type="tip", text="This tip is only shown in light mode.") */}}

{% end %}