Components

This theme includes some useful custom components 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 components have got you covered.

Alert Component#

Bring attention to information with these GitHub-style alert components. 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.
   {% </alert> %}

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 Component#

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

Usage#

{{ <mastodon url="https://hachyderm.io/@ebkalderon/114462281016082381" /> }}

References#

This component 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.

{% </references> %}

Responsive Image Component#

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

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 page={page} config={config} src="example-hi-res-image.jpg" alt="Responsive hi-res image" /> }}

The default behavior of the responsive_image component 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 component.

Wide Container Component#

Use this component 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.

{% </wide_container> %}

Presentation Palette Component#

Display the site's currently active presentation style and variant, along with a light/dark colour-palette swatch grid, using the presentation_palette component. 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 config={config} /> }}

Light Mode Only / Dark Mode Only Components#

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 components. Neither takes any parameters — just wrap the content you want to restrict as the component's body.

Visibility is done with pure CSS (no extra JavaScript beyond the theme switcher this theme already ships): if JavaScript is disabled, each component 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.

{% </light_mode_only> %}

{% <dark_mode_only> %}

Only shown while the site is in dark mode.

{% </dark_mode_only> %}

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

{% <light_mode_only> %}

{{ <alert type="tip" text="This tip is only shown in light mode." /> }}

{% </light_mode_only> %}