Plugins
Plugins add a small set of built-in interactive behaviors to your site. Add one by placing its tag in a template:
{% plugin "lightbox" %}A plugin's script is shared and cached across every page that uses it. Published sites only run these built-in scripts, so plugins are the way to add behavior like this to a page. They work in Preview too.
Some plugins take variables, added after the plugin's name:
{% plugin "lightbox", minWidth: 100, selector: ".gallery" %}Lightbox
Opens images to their full resolution in the middle of the page.
{% plugin "lightbox" %}Without variables this applies to every image on any page using the template. Add minWidth and/or selector variables to narrow that down to a smaller set. Both are optional, and combining them always narrows further:
{% plugin "lightbox", minWidth: 100, selector: ".gallery" %}minWidth- only images at least this many pixels wide (by their own natural size, not however CSS has scaled them) open in the lightbox.selector- a CSS selector restricting which images are eligible, e.g. a class name you've set on specific images via their Media Properties in the editor.
Clicking a matching image opens it full-size in an overlay. Click anywhere on the overlay, or press Escape, to close it.
Theme
Adds a light and dark mode toggle to your site. Place the tag in your template's <head>, after your style sheets:
{% plugin "theme" %}It sets data-theme="light" or data-theme="dark" on the page's <html> element, using the visitor's own choice if they've made one, or their system setting if they haven't. Any element with a data-theme-toggle attribute switches between the two when clicked, and the choice is remembered on that visitor's device:
<button type="button" data-theme-toggle>Dark mode</button>Style your site for each mode using the attribute, for example :root[data-theme="dark"] { ... }. A stylesheet link with its own data-theme attribute only applies when it matches, which is how you can switch the code highlighting theme too:
<link rel="stylesheet" href="{{ site.codeThemeLight }}" data-theme="light" />
<link
rel="stylesheet"
href="{{ site.codeThemeDark }}"
media="(prefers-color-scheme: dark)"
data-theme="dark"
/>Keeping media="(prefers-color-scheme: dark)" on the dark link means your site still follows the visitor's system setting if scripts don't run. The toggle also gets aria-checked="true" while dark mode is on, so it can be styled as a switch.
Copy
Adds a Copy button to every code block on the page, which copies its code for the visitor to paste somewhere else. The button shows "Copied" for a moment after it's clicked.
{% plugin "copy" %}Add label and done variables to change what the buttons say, for example to use icons instead:
{% plugin "copy", label: "📋️", done: "✅️" %}label- what the button shows. Optional, defaults to "Copy".done- what it shows for a moment after copying. Optional, defaults to "Copied".
Whatever the labels are, the button has a "Copy code" tooltip, and screen readers announce it as "Copy code".
Each button has the class copy-button, and is added inside the code block's own <pre> element, so you can place it with CSS. For example, in the top right corner:
pre {
position: relative;
}
.copy-button {
position: absolute;
top: 0.5rem;
right: 0.5rem;
}Browsers only allow copying on secure (https://) pages, so the buttons don't appear when a page is opened any other way. Published sites are always secure.
Evade
The easter egg shown on the 404 page: an element wanders around the page, evading the cursor when it comes near. Unlike lightbox, there's no sensible "every element" default, so selector is required:
<div class="orb" style="padding: 40px"></div>
{% plugin "evade", selector: ".orb" %}selector- which element(s) to animate. Required.speed- how fast it drifts, in pixels per second. Optional, defaults to 80.
How close the cursor needs to get before it flees is controlled by the element's own CSS padding - a bigger padding means it evades from further away.