to fire click events. */
+ cursor: pointer;
+ transition: background 150ms ease, border-color 150ms ease, color 150ms ease;
+}
+
+.gitlink-widget-trigger:hover,
+.gitlink-widget-trigger:focus-visible,
+.gitlink-widget-open .gitlink-widget-trigger {
+ background: var(--gitlink-widget-accent-soft, color-mix(in srgb, var(--gitlink-widget-accent, var(--bs-link-color, #0d6efd)) 15%, transparent));
+ border-color: var(--gitlink-widget-accent, var(--bs-link-color, #0d6efd));
+ color: var(--gitlink-widget-accent, var(--bs-link-color, #0d6efd));
+}
+
+.gitlink-widget-platform-icon {
+ flex-shrink: 0;
+}
+
+.gitlink-widget-stats {
+ display: flex;
+ align-items: center;
+ gap: 8px;
+}
+
+.gitlink-widget-stat {
+ display: flex;
+ align-items: center;
+ gap: 3px;
+ font-weight: 500;
+ font-variant-numeric: tabular-nums;
+}
+
+.gitlink-widget-stat svg {
+ opacity: 0.85;
+}
+
+.gitlink-widget-count {
+ min-width: 1rem;
+ text-align: center;
+}
+
+.gitlink-widget-arrow {
+ opacity: 0.7;
+ transition: transform 150ms ease;
+}
+
+.gitlink-widget-open .gitlink-widget-arrow {
+ transform: rotate(180deg);
+}
+
+/* Menu rules are scoped under `.gitlink-widget` so they outrank Quarto's
+ `.navbar a` and `.sidebar-navigation a` colours, which would otherwise
+ force the surrounding navigation foreground onto the items. */
+.gitlink-widget .gitlink-widget-dropdown {
+ position: absolute;
+ top: calc(100% + 6px);
+ right: 0;
+ min-width: 14rem;
+ background: var(--gitlink-widget-menu-bg, var(--bs-body-bg, #ffffff));
+ border: 1px solid var(--gitlink-widget-border, var(--bs-border-color-translucent, rgba(128, 128, 128, 0.3)));
+ border-radius: 0.5rem;
+ box-shadow: 0 12px 30px -16px rgba(0, 0, 0, 0.55);
+ padding: 0.35rem;
+ opacity: 0;
+ visibility: hidden;
+ transform: translateY(-8px);
+ transition: opacity 150ms ease, transform 150ms ease, visibility 150ms ease;
+ z-index: 1000;
+}
+
+.gitlink-widget.gitlink-widget-open .gitlink-widget-dropdown {
+ opacity: 1;
+ visibility: visible;
+ transform: translateY(0);
+}
+
+.gitlink-widget .gitlink-widget-item {
+ display: flex;
+ align-items: center;
+ gap: 10px;
+ padding: 0.4rem 0.7rem;
+ color: var(--gitlink-widget-menu-fg, var(--bs-body-color, #212529));
+ text-decoration: none;
+ font-size: 0.9rem;
+ font-weight: 500;
+ border-radius: 0.375rem;
+ transition: background 150ms ease, color 150ms ease;
+}
+
+.gitlink-widget .gitlink-widget-item svg,
+.gitlink-widget .gitlink-widget-item .bi {
+ flex-shrink: 0;
+}
+
+/* Labels may carry inline markup (e.g. an iconify icon from a shortcode in
+ the entry's `text`); keep any such icon aligned with the text. */
+.gitlink-widget .gitlink-widget-item .gitlink-widget-item-label {
+ display: inline-flex;
+ align-items: center;
+ gap: 6px;
+}
+
+.gitlink-widget .gitlink-widget-item:hover,
+.gitlink-widget .gitlink-widget-item:focus-visible {
+ background: var(--gitlink-widget-accent-soft, color-mix(in srgb, var(--gitlink-widget-accent, var(--bs-link-color, #0d6efd)) 15%, transparent));
+ color: var(--gitlink-widget-accent, var(--bs-link-color, #0d6efd));
+ text-decoration: none;
+}
+
+.gitlink-widget .gitlink-widget-divider {
+ height: 1px;
+ margin: 0.35rem 0;
+ background: var(--gitlink-widget-border, var(--bs-border-color-translucent, rgba(128, 128, 128, 0.3)));
+}
+
+/* Sidebar navigation item (`sidebar.contents`). Quarto's sidebar is an
+ `overflow-auto` scroll container, which would clip an absolutely positioned
+ menu, so the menu expands inline below the trigger, like a sidebar section.
+ `display` is not animatable, hence no transition. */
+.gitlink-widget-sidebar {
+ display: flex;
+ flex-direction: column;
+ align-items: stretch;
+ width: 100%;
+}
+
+.gitlink-widget-sidebar .gitlink-widget-trigger {
+ width: 100%;
+ justify-content: space-between;
+}
+
+.gitlink-widget-sidebar .gitlink-widget-dropdown {
+ position: static;
+ display: none;
+ min-width: 0;
+ width: 100%;
+ margin-top: 0.35rem;
+ box-shadow: none;
+ transform: none;
+ transition: none;
+}
+
+.gitlink-widget-sidebar.gitlink-widget-open .gitlink-widget-dropdown {
+ display: block;
+}
+
+/* A tools row holding the widget stacks vertically: the widget trigger is a
+ counted pill, not an icon, so it takes its own line above the remaining
+ tools (colour-scheme toggle, reader toggle, overlay search). The marker
+ class is set by widget.js on whichever tools container the placeholder was
+ in; the id keeps this ahead of Quarto's own `.sidebar-tools-main` rather
+ than relying on stylesheet order.
+
+ The row is also the containing block for the overlay menu below. It spans
+ the sidebar, where the centred trigger does not, so anchoring the menu here
+ is what keeps it inside the column. */
+#quarto-sidebar .gitlink-widget-tools {
+ position: relative;
+ display: flex;
+ flex-direction: column;
+ align-items: center;
+ gap: 0.4rem;
+ width: 100%;
+}
+
+/* Quarto pulls the tools row up under the sidebar title (`margin-top: -6px`),
+ which crowds the widget pill; give it room instead. */
+.sidebar-title .sidebar-tools-main.gitlink-widget-tools {
+ margin-top: 0.5rem;
+}
+
+/* The widget sits below the icon tools (colour-scheme and reader toggles) and
+ above the search control, whether search is the sidebar field below the row
+ or an overlay button inside it. `position: static` hands the menu's
+ containing block up to the row: the widget is `position: relative` by
+ default, which would otherwise anchor the menu to the trigger pill. */
+.gitlink-widget-tools .gitlink-widget {
+ order: 1;
+ position: static;
+}
+
+.gitlink-widget-tools #quarto-search {
+ order: 2;
+}
+
+/* A tool sits in a strip of icon-sized controls, where an inline menu would
+ be laid out as another flex item beside them, so it keeps the overlay menu.
+
+ Quarto's sidebar does not clip: it sets `overflow-y: auto` and leaves
+ `overflow-x` at `visible`, which computes to `auto`, so a menu wider than
+ the column scrolls it sideways instead. The menu is hidden with
+ `visibility` rather than `display`, so it takes part in layout even while
+ shut and the scrollbar is there before anything is opened.
+
+ Stretching it between both edges of the row (which the rule above made the
+ containing block) is what bounds it: the trigger is centred, so anchoring
+ to the trigger left the menu running past the column's right edge. `width`
+ has to give way with it, since a specified width over-constrains an
+ absolutely positioned box and `right` is the offset that gets dropped, and
+ the 14rem floor has to go for the same reason on a narrow sidebar. */
+.gitlink-widget-tools .gitlink-widget-dropdown {
+ left: 0;
+ right: 0;
+ min-width: 0;
+ width: auto;
+}
+
+/* The collapsed navbar-nav is a Bootstrap `.navbar-nav-scroll` region
+ (max-height + overflow-y: auto) that clips the absolute dropdown, showing a
+ scrollbar instead of the menu. Neutralise it so the menu overlays on top,
+ and anchor the menu to the left edge so it stays on screen. */
+@media (max-width: 991.98px) {
+ .navbar .navbar-collapse .navbar-nav {
+ max-height: none;
+ overflow: visible;
+ }
+
+ .navbar .gitlink-widget .gitlink-widget-dropdown {
+ left: 0;
+ right: auto;
+ }
+}
+
+/* Visually hidden, available to assistive technology. */
+.gitlink-widget-sr-only {
+ position: absolute;
+ width: 1px;
+ height: 1px;
+ padding: 0;
+ margin: -1px;
+ overflow: hidden;
+ clip: rect(0, 0, 0, 0);
+ white-space: nowrap;
+ border: 0;
+}
+
+@media (prefers-reduced-motion: reduce) {
+ .gitlink-widget-trigger,
+ .gitlink-widget-arrow,
+ .gitlink-widget-dropdown,
+ .gitlink-widget-item {
+ transition: none;
+ }
+}
diff --git a/docs/_extensions/mcanouil/gitlink/widget.js b/docs/_extensions/mcanouil/gitlink/widget.js
new file mode 100644
index 0000000..cb9dd90
--- /dev/null
+++ b/docs/_extensions/mcanouil/gitlink/widget.js
@@ -0,0 +1,374 @@
+/**
+ * Gitlink - Repository Navigation Widget
+ * Replaces every `#gitlink-widget` placeholder (navbar item, sidebar tool, or
+ * sidebar contents item) with a button showing live star and fork counts and a
+ * dropdown menu of repository links. Configuration is injected by the gitlink
+ * Lua filter as a JSON script element; counts come from the platform REST API,
+ * cached in localStorage for four hours so the rate limit is not hit on every
+ * page view, and shared by every widget on the page. A stale cache or `?`
+ * covers a failed request. Octicon path data for the icons the menu uses
+ * arrives in the configuration (`icons`); other icon names render as Bootstrap
+ * Icons, which Quarto bundles with every HTML page.
+ *
+ * @license MIT
+ * @copyright 2026 Mickaël Canouil
+ * @author Mickaël Canouil
+ */
+// Widget inspired by and derived from the GitHub button in
+// https://github.com/posit-dev/great-docs by Rich Iannone
+// (https://github.com/rich-iannone).
+(function () {
+ "use strict";
+
+ const CACHE_DURATION = 4 * 60 * 60 * 1000;
+
+ const SVG_NS = "http://www.w3.org/2000/svg";
+
+ const ARROW_PATHS = [
+ { d: "M4.427 7.427l3.396 3.396a.25.25 0 00.354 0l3.396-3.396A.25.25 0 0011.396 7H4.604a.25.25 0 00-.177.427z" },
+ ];
+
+ const readConfig = () => {
+ const node = document.getElementById("gitlink-widget-config");
+ if (!node) return null;
+ try {
+ return JSON.parse(node.textContent);
+ } catch (error) {
+ return null;
+ }
+ };
+
+ // Large numbers read better abbreviated: 1500 -> 1.5k, 2000000 -> 2M.
+ const formatCount = (value) => {
+ if (value === undefined || value === null || value === "?") return "?";
+ if (value >= 1e6) return (value / 1e6).toFixed(1).replace(/\.0$/, "") + "M";
+ if (value >= 1e3) return (value / 1e3).toFixed(1).replace(/\.0$/, "") + "k";
+ return String(value);
+ };
+
+ // Read and parse the cached stats, or null. Freshness is judged by the
+ // caller so expired data can still serve as a fallback on a failed refresh.
+ const readCache = (cacheKey) => {
+ try {
+ const raw = localStorage.getItem(cacheKey);
+ return raw ? JSON.parse(raw) : null;
+ } catch (error) {
+ return null;
+ }
+ };
+
+ const writeCache = (cacheKey, data) => {
+ try {
+ localStorage.setItem(cacheKey, JSON.stringify(data));
+ } catch (error) {
+ // localStorage may be unavailable (private mode, quota); counts still
+ // render from the live response, only the cache is skipped.
+ }
+ };
+
+ // Only http(s) links belong in the menu; anything else (e.g. javascript:)
+ // is dropped.
+ const safeHref = (href) => {
+ try {
+ const url = new URL(href, window.location.href);
+ return url.protocol === "http:" || url.protocol === "https:" ? url.href : null;
+ } catch (error) {
+ return null;
+ }
+ };
+
+ // Labels arrive either as plain strings or as structured parts emitted by
+ // the Lua filter: {text} or {tag, attrs} with tags and attributes already
+ // allowlisted at render time. The same allowlist is enforced again here,
+ // and everything is built with createElement/createTextNode, so no HTML
+ // string is ever parsed in the browser.
+ const ALLOWED_LABEL_TAGS = ["span", "em", "strong", "code", "sub", "sup", "i", "iconify-icon"];
+ const ALLOWED_LABEL_ATTRIBUTES = [
+ "class", "icon", "width", "height", "inline", "title", "role",
+ "aria-label", "aria-hidden",
+ ];
+
+ const buildLabelInto = (target, label) => {
+ if (typeof label === "string") {
+ target.appendChild(document.createTextNode(label));
+ return;
+ }
+ (label || []).forEach((part) => {
+ if (typeof part.text === "string") {
+ target.appendChild(document.createTextNode(part.text));
+ return;
+ }
+ if (!part.tag || ALLOWED_LABEL_TAGS.indexOf(part.tag) === -1) return;
+ const element = document.createElement(part.tag);
+ const attrs = part.attrs || {};
+ ALLOWED_LABEL_ATTRIBUTES.forEach((name) => {
+ if (typeof attrs[name] === "string") {
+ element.setAttribute(name, attrs[name]);
+ }
+ });
+ target.appendChild(element);
+ });
+ };
+
+ // Build an SVG element from path attribute objects ({d, fill-rule}) so no
+ // HTML string is ever parsed.
+ const buildSvg = (paths, size) => {
+ const svg = document.createElementNS(SVG_NS, "svg");
+ svg.setAttribute("viewBox", "0 0 16 16");
+ svg.setAttribute("width", String(size));
+ svg.setAttribute("height", String(size));
+ svg.setAttribute("fill", "currentColor");
+ svg.setAttribute("aria-hidden", "true");
+ paths.forEach((attrs) => {
+ const path = document.createElementNS(SVG_NS, "path");
+ path.setAttribute("d", attrs.d);
+ if (attrs["fill-rule"]) path.setAttribute("fill-rule", attrs["fill-rule"]);
+ svg.appendChild(path);
+ });
+ return svg;
+ };
+
+ // An icon spec is a name whose octicon paths were embedded in the config,
+ // or a Bootstrap icon name (Quarto bundles Bootstrap Icons and uses the
+ // same names for its navbar tools and callouts). Returns an element or null.
+ const buildIcon = (spec, size, icons) => {
+ if (!spec) return null;
+ const paths = icons && icons[spec];
+ if (paths) {
+ return buildSvg(paths, size);
+ }
+ if (typeof spec === "string" && /^[a-z0-9-]+$/.test(spec)) {
+ const icon = document.createElement("i");
+ icon.className = "bi bi-" + spec;
+ icon.setAttribute("aria-hidden", "true");
+ icon.style.fontSize = size + "px";
+ icon.style.lineHeight = "1";
+ return icon;
+ }
+ return null;
+ };
+
+ const buildStat = (name, title, iconKey, icons) => {
+ const stat = document.createElement("span");
+ stat.className = "gitlink-widget-stat gitlink-widget-" + name;
+ stat.title = title;
+ const icon = buildIcon(iconKey, 14, icons);
+ if (icon) stat.appendChild(icon);
+ const count = document.createElement("span");
+ count.className = "gitlink-widget-count";
+ count.dataset.stat = name;
+ count.textContent = "-";
+ stat.appendChild(count);
+ return stat;
+ };
+
+ // Disclosure pattern: a native button toggling a plain list of links, per
+ // the ARIA Authoring Practices for navigation link collections. No menu
+ // roles, so Tab moves through the links naturally.
+ const buildTrigger = (config, menuId) => {
+ const trigger = document.createElement("button");
+ trigger.type = "button";
+ trigger.className = "gitlink-widget-trigger";
+ trigger.setAttribute("aria-expanded", "false");
+ trigger.setAttribute("aria-controls", menuId);
+ trigger.setAttribute("aria-label", config.menuLabel);
+
+ const platformIcon = buildIcon(config.icon, 20, config.icons);
+ if (platformIcon) {
+ platformIcon.classList.add("gitlink-widget-platform-icon");
+ trigger.appendChild(platformIcon);
+ }
+
+ if (config.api) {
+ const stats = document.createElement("span");
+ stats.className = "gitlink-widget-stats";
+ stats.appendChild(buildStat("stars", "Stars", "star", config.icons));
+ stats.appendChild(buildStat("forks", "Forks", "fork", config.icons));
+ trigger.appendChild(stats);
+ }
+
+ const arrow = buildSvg(ARROW_PATHS, 16);
+ arrow.classList.add("gitlink-widget-arrow");
+ trigger.appendChild(arrow);
+ return trigger;
+ };
+
+ const buildDropdown = (config, menuId) => {
+ const dropdown = document.createElement("div");
+ dropdown.id = menuId;
+ dropdown.className = "gitlink-widget-dropdown";
+ dropdown.setAttribute("aria-hidden", "true");
+
+ config.links.forEach((link) => {
+ if (link.divider) {
+ const divider = document.createElement("div");
+ divider.className = "gitlink-widget-divider";
+ dropdown.appendChild(divider);
+ return;
+ }
+ const href = safeHref(link.href);
+ if (!href) return;
+ const item = document.createElement("a");
+ item.className = "gitlink-widget-item";
+ item.href = href;
+ item.target = "_blank";
+ item.rel = "noopener";
+ const icon = buildIcon(link.icon, 16, config.icons);
+ if (icon) item.appendChild(icon);
+ const label = document.createElement("span");
+ label.className = "gitlink-widget-item-label";
+ buildLabelInto(label, link.label);
+ item.appendChild(label);
+ const newTabHint = document.createElement("span");
+ newTabHint.className = "gitlink-widget-sr-only";
+ newTabHint.textContent = " (opens in new tab)";
+ item.appendChild(newTabHint);
+ dropdown.appendChild(item);
+ });
+ return dropdown;
+ };
+
+ // The first widget on a page keeps the historical `gitlink-widget` id; any
+ // further placeholder gets a suffixed one so ids stay unique.
+ const buildWidget = (config, index) => {
+ const rootId = index === 0 ? "gitlink-widget" : "gitlink-widget-" + index;
+ const menuId = rootId + "-menu";
+ const root = document.createElement("div");
+ root.id = rootId;
+ root.className = "gitlink-widget";
+ root.appendChild(buildTrigger(config, menuId));
+ root.appendChild(buildDropdown(config, menuId));
+ return root;
+ };
+
+ const showStats = (widget, stats, config) => {
+ const setCount = (selector, value) => {
+ const node = widget.querySelector(selector);
+ if (node) node.textContent = formatCount(value);
+ };
+ setCount('.gitlink-widget-count[data-stat="stars"]', stats.stars);
+ setCount('.gitlink-widget-count[data-stat="forks"]', stats.forks);
+
+ // Surface the counts to assistive technology; the visual counters are
+ // bare numbers with mouse-only tooltips.
+ const spoken = [];
+ if (typeof stats.stars === "number") spoken.push(formatCount(stats.stars) + " stars");
+ if (typeof stats.forks === "number") spoken.push(formatCount(stats.forks) + " forks");
+ if (spoken.length > 0) {
+ const trigger = widget.querySelector(".gitlink-widget-trigger");
+ if (trigger) {
+ trigger.setAttribute("aria-label", config.menuLabel + ", " + spoken.join(", "));
+ }
+ }
+ };
+
+ // The in-flight request, shared by every widget on the page (they all read
+ // the same configuration) so several placeholders make one API call instead
+ // of racing each other before the cache is written.
+ let pendingStats = null;
+
+ const fetchStats = (config) => {
+ // Read + parse the cache once; branch on freshness so the stale-fallback
+ // path does not re-read and re-parse the same entry.
+ const cached = readCache(config.cacheKey);
+ if (cached && Date.now() - cached.timestamp <= CACHE_DURATION) {
+ return Promise.resolve(cached);
+ }
+ if (pendingStats) return pendingStats;
+
+ const options = { headers: config.api.headers || {} };
+ // Bound the request so a slow API falls back to the stale cache instead
+ // of leaving the counts pending; older browsers just skip the timeout.
+ if (typeof AbortSignal !== "undefined" && AbortSignal.timeout) {
+ options.signal = AbortSignal.timeout(8000);
+ }
+
+ const request = fetch(config.api.endpoint, options)
+ .then((response) => (response.ok ? response.json() : Promise.reject(response.status)))
+ .then((data) => {
+ const stats = {
+ stars: data[config.api.starsField],
+ forks: data[config.api.forksField],
+ timestamp: Date.now(),
+ };
+ writeCache(config.cacheKey, stats);
+ return stats;
+ })
+ .catch(() => cached || { stars: "?", forks: "?" });
+ pendingStats = request;
+ return request;
+ };
+
+ const loadStats = (widget, config) => {
+ if (!config.api) return;
+ fetchStats(config).then((stats) => showStats(widget, stats, config));
+ };
+
+ const setupDropdown = (widget) => {
+ const trigger = widget.querySelector(".gitlink-widget-trigger");
+ const dropdown = widget.querySelector(".gitlink-widget-dropdown");
+ if (!trigger || !dropdown) return;
+
+ const setOpen = (open) => {
+ trigger.setAttribute("aria-expanded", String(open));
+ dropdown.setAttribute("aria-hidden", String(!open));
+ widget.classList.toggle("gitlink-widget-open", open);
+ };
+
+ // The trigger is a native button, so Enter/Space activation is built in.
+ trigger.addEventListener("click", (event) => {
+ event.stopPropagation();
+ setOpen(trigger.getAttribute("aria-expanded") !== "true");
+ });
+
+ document.addEventListener("click", (event) => {
+ if (!widget.contains(event.target)) setOpen(false);
+ });
+
+ document.addEventListener("keydown", (event) => {
+ if (event.key !== "Escape") return;
+ // Closing while focus is on a link inside the menu would drop focus
+ // into a hidden subtree; hand it back to the trigger.
+ if (widget.contains(document.activeElement) && document.activeElement !== trigger) {
+ trigger.focus();
+ }
+ setOpen(false);
+ });
+ };
+
+ // Replace one placeholder anchor with a widget. Only the anchor goes, so
+ // whatever Quarto wrapped it in (`li.nav-item`, `li.sidebar-item >
+ // div.sidebar-item-container`, `div.sidebar-tools-main`) is preserved, and
+ // the widget inherits the spacing and colours of its neighbours.
+ const mountWidget = (anchor, index, config) => {
+ const root = buildWidget(config, index);
+
+ // The tools row is a horizontal strip of icon-sized controls; flag it so
+ // the CSS can stack the widget above the search and colour-scheme
+ // controls instead of squeezing the counts in beside them.
+ const tools = anchor.closest(".sidebar-tools-main, .sidebar-tools-collapse");
+ if (tools) {
+ tools.classList.add("gitlink-widget-tools");
+ } else if (anchor.closest("#quarto-sidebar")) {
+ // A sidebar navigation item is as wide as the sidebar and sits in its
+ // scroll container, so its menu expands inline rather than overlaying.
+ root.classList.add("gitlink-widget-sidebar");
+ }
+
+ anchor.replaceWith(root);
+
+ loadStats(root, config);
+ setupDropdown(root);
+ };
+
+ document.addEventListener("DOMContentLoaded", function () {
+ const config = readConfig();
+ if (!config) return;
+
+ // Quarto rewrites the placeholder href to a relative path
+ // (`./#gitlink-widget` at the root, `../#gitlink-widget` deeper), so
+ // match the fragment suffix rather than an exact href.
+ const anchors = document.querySelectorAll('a[href$="#gitlink-widget"]');
+ anchors.forEach((anchor, index) => mountWidget(anchor, index, config));
+ });
+})();
diff --git a/docs/_extensions/mcanouil/iconify/LICENSE b/docs/_extensions/mcanouil/iconify/LICENSE
new file mode 100644
index 0000000..4b53bb8
--- /dev/null
+++ b/docs/_extensions/mcanouil/iconify/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mickaël Canouil
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/docs/_extensions/mcanouil/iconify/_extension.yml b/docs/_extensions/mcanouil/iconify/_extension.yml
new file mode 100644
index 0000000..36d2ef0
--- /dev/null
+++ b/docs/_extensions/mcanouil/iconify/_extension.yml
@@ -0,0 +1,11 @@
+title: Iconify
+author: Mickaël Canouil
+version: 4.0.0
+quarto-required: '>=1.5.57'
+source: mcanouil/quarto-iconify@4.0.0
+source-type: registry
+contributes:
+ filters:
+ - iconify-filter.lua
+ shortcodes:
+ - iconify.lua
diff --git a/docs/_extensions/mcanouil/iconify/_modules/logging.lua b/docs/_extensions/mcanouil/iconify/_modules/logging.lua
new file mode 100644
index 0000000..a538809
--- /dev/null
+++ b/docs/_extensions/mcanouil/iconify/_modules/logging.lua
@@ -0,0 +1,62 @@
+--- MC Logging - Formatted log output for Quarto Lua filters and shortcodes
+--- @module "logging"
+--- @license MIT
+--- @copyright 2026 Mickaël Canouil
+--- @author Mickaël Canouil
+--- @version 1.0.0
+
+local M = {}
+
+-- ============================================================================
+-- LOGGING UTILITIES
+-- ============================================================================
+
+--- Format and log an error message with extension prefix.
+--- Provides standardised error messages with consistent formatting across extensions.
+--- Format: [extension-name] Message with details.
+---
+--- @param extension_name string The name of the extension (e.g., "external", "lua-env")
+--- @param message string The error message to display
+--- @usage M.log_error("external", "Could not open file 'example.md'.")
+function M.log_error(extension_name, message)
+ quarto.log.error('[' .. extension_name .. '] ' .. message)
+end
+
+--- Format and log a warning message with extension prefix.
+--- Provides standardised warning messages with consistent formatting across extensions.
+--- Format: [extension-name] Message with details.
+---
+--- @param extension_name string The name of the extension (e.g., "external", "lua-env")
+--- @param message string The warning message to display
+--- @usage M.log_warning("lua-env", "No variable name provided.")
+function M.log_warning(extension_name, message)
+ quarto.log.warning('[' .. extension_name .. '] ' .. message)
+end
+
+--- Format and log an output message with extension prefix.
+--- Provides standardised informational messages with consistent formatting across extensions.
+--- Format: [extension-name] Message with details.
+---
+--- @param extension_name string The name of the extension (e.g., "lua-env")
+--- @param message string The informational message to display
+--- @usage M.log_output("lua-env", "Exported metadata to: output.json")
+function M.log_output(extension_name, message)
+ quarto.log.output('[' .. extension_name .. '] ' .. message)
+end
+
+--- Format and log a debug message with extension prefix.
+--- Provides standardised debug messages with consistent formatting across extensions.
+--- Format: [extension-name] Message with details.
+---
+--- @param extension_name string The name of the extension (e.g., "lua-env")
+--- @param message string The debug message to display
+--- @usage M.log_debug("lua-env", "Variable 'x' has value: 42")
+function M.log_debug(extension_name, message)
+ quarto.log.debug('[' .. extension_name .. '] ' .. message)
+end
+
+-- ============================================================================
+-- MODULE EXPORT
+-- ============================================================================
+
+return M
diff --git a/docs/_extensions/mcanouil/iconify/_modules/metadata.lua b/docs/_extensions/mcanouil/iconify/_modules/metadata.lua
new file mode 100644
index 0000000..bab2087
--- /dev/null
+++ b/docs/_extensions/mcanouil/iconify/_modules/metadata.lua
@@ -0,0 +1,182 @@
+--- MC Metadata - Extension configuration and metadata access for Quarto Lua filters and shortcodes
+--- @module "metadata"
+--- @license MIT
+--- @copyright 2026 Mickaël Canouil
+--- @author Mickaël Canouil
+--- @version 1.0.0
+
+local M = {}
+
+--- Load a sibling module from the same directory as this file.
+--- @param filename string The sibling module filename (e.g., 'string.lua')
+--- @return table The loaded module
+local function load_sibling(filename)
+ local source = debug.getinfo(1, 'S').source:sub(2)
+ local dir = source:match('(.*[/\\])') or ''
+ return require((dir .. filename):gsub('%.lua$', ''))
+end
+
+--- Load required modules
+local str = load_sibling('string.lua')
+local log = load_sibling('logging.lua')
+
+-- ============================================================================
+-- METADATA UTILITIES
+-- ============================================================================
+
+--- Get configuration from extensions.name namespace.
+--- @param meta table Document metadata
+--- @param extension_name string The extension name (e.g., "github", "iconify")
+--- @return any The value/table or nil
+--- @usage local value = M.get_extension_config(meta, 'section-outline')
+function M.get_extension_config(meta, extension_name)
+ local config_ext = meta.extensions and meta.extensions[extension_name]
+ if not config_ext then return nil end
+ return config_ext
+end
+
+--- Extract metadata value from document meta using nested structure.
+--- Supports the extensions.{extension-name}.{key} pattern.
+--- @param meta table The document metadata table
+--- @param extension_name string The extension name (e.g., "github", "iconify")
+--- @param key string The metadata key to retrieve
+--- @return string|nil The metadata value as a string, or nil if not found
+--- @usage local repo = M.get_metadata_value(meta, "github", "repository-name")
+function M.get_metadata_value(meta, extension_name, key)
+ if meta['extensions'] and meta['extensions'][extension_name] and meta['extensions'][extension_name][key] then
+ return str.stringify(meta['extensions'][extension_name][key])
+ end
+ return nil
+end
+
+--- Check for deprecated top-level configuration and emit warning
+--- @param meta table The document metadata table
+--- @param extension_name string The extension name
+--- @param key string|nil The configuration key being accessed (nil to check entire extension config)
+--- @param deprecation_warning_shown boolean Flag to track if warning has been shown
+--- @return any|nil The value from deprecated config, or nil if not found
+--- @return boolean Updated deprecation warning flag
+function M.check_deprecated_config(meta, extension_name, key, deprecation_warning_shown)
+ -- Handle array-based configuration (when key is nil)
+ if key == nil then
+ if not str.is_empty(meta[extension_name]) then
+ if not deprecation_warning_shown then
+ log.log_warning(
+ extension_name,
+ 'Top-level "' .. extension_name .. '" configuration is deprecated. ' ..
+ 'Please use:\n' ..
+ 'extensions:\n' ..
+ ' ' .. extension_name .. ':\n' ..
+ ' - (configuration array)'
+ )
+ deprecation_warning_shown = true
+ end
+ return meta[extension_name], deprecation_warning_shown
+ end
+ return nil, deprecation_warning_shown
+ end
+
+ -- Handle key-value configuration (original behaviour)
+ if not str.is_empty(meta[extension_name]) and not str.is_empty(meta[extension_name][key]) then
+ if not deprecation_warning_shown then
+ log.log_warning(
+ extension_name,
+ 'Top-level "' .. extension_name .. '" configuration is deprecated. ' ..
+ 'Please use:\n' ..
+ 'extensions:\n' ..
+ ' ' .. extension_name .. ':\n' ..
+ ' ' .. key .. ': value'
+ )
+ deprecation_warning_shown = true
+ end
+ return str.stringify(meta[extension_name][key]), deprecation_warning_shown
+ end
+ return nil, deprecation_warning_shown
+end
+
+-- ============================================================================
+-- ENHANCED METADATA/CONFIGURATION UTILITIES
+-- ============================================================================
+
+--- Get option value with fallback hierarchy: args -> extensions.{extension}.{key} -> defaults.
+--- Provides a standardised way to read configuration values with multiple fallback levels.
+--- Priority: 1. Named arguments (kwargs), 2. Document metadata, 3. Default values.
+---
+--- @param spec table Configuration spec with fields: extension (string), key (string), args (table|nil), meta (table|nil), default (any|nil)
+--- @return any The resolved option value (type depends on what's stored in config)
+--- @usage local duration = M.get_option_with_fallbacks({extension = 'animate', key = 'duration', args = kwargs, meta = meta, default = '3s'})
+function M.get_option_with_fallbacks(spec)
+ -- Validate required fields
+ if not spec.extension or not spec.key then
+ error("Configuration spec must include 'extension' and 'key' fields")
+ end
+
+ --- @type string The extension name
+ local extension = spec.extension
+ --- @type string The configuration key
+ local key = spec.key
+ --- @type table|nil Named arguments table
+ local args = spec.args
+ --- @type table|nil Document metadata
+ local meta = spec.meta
+ --- @type any Default value if not found elsewhere
+ local default = spec.default
+
+ -- Priority 1: Check named arguments (kwargs)
+ if args and args[key] then
+ local arg_value = str.stringify(args[key])
+ if not str.is_empty(arg_value) then
+ return arg_value
+ end
+ end
+
+ -- Priority 2: Check metadata extensions.{extension}.{key}
+ if meta then
+ local meta_value = M.get_metadata_value(meta, extension, key)
+ if not str.is_empty(meta_value) then
+ return meta_value
+ end
+ end
+
+ -- Priority 3: Return default value
+ return default
+end
+
+--- Get multiple option values at once with fallback hierarchy.
+--- Batch version of get_option_with_fallbacks for retrieving multiple configuration values.
+--- Returns a table mapping each key to its resolved value.
+---
+--- @param spec table Configuration spec with fields: extension (string), keys (table
), args (table|nil), meta (table|nil), defaults (table|nil)
+--- @return table Table mapping each key to its resolved value
+--- @usage local opts = M.get_options({extension = 'animate', keys = {'duration', 'delay'}, args = kwargs, meta = meta, defaults = {duration = '3s', delay = '2s'}})
+function M.get_options(spec)
+ -- Validate required fields
+ if not spec.extension or not spec.keys then
+ error("Configuration spec must include 'extension' and 'keys' fields")
+ end
+
+ --- @type table Result table
+ local result = {}
+
+ --- @type table Default values table
+ local defaults = spec.defaults or {}
+
+ -- Get each key using the single-option fallback logic
+ for _, key in ipairs(spec.keys) do
+ result[key] = M.get_option_with_fallbacks({
+ extension = spec.extension,
+ key = key,
+ args = spec.args,
+ meta = spec.meta,
+ default = defaults[key]
+ })
+ end
+
+ return result
+end
+
+-- ============================================================================
+-- MODULE EXPORT
+-- ============================================================================
+
+return M
diff --git a/docs/_extensions/mcanouil/iconify/_modules/string.lua b/docs/_extensions/mcanouil/iconify/_modules/string.lua
new file mode 100644
index 0000000..8f89e0b
--- /dev/null
+++ b/docs/_extensions/mcanouil/iconify/_modules/string.lua
@@ -0,0 +1,198 @@
+--- MC String - String manipulation and escaping for Quarto Lua filters and shortcodes
+--- @module "string"
+--- @license MIT
+--- @copyright 2026 Mickaël Canouil
+--- @author Mickaël Canouil
+--- @version 1.0.0
+
+local M = {}
+
+-- ============================================================================
+-- STRING UTILITIES
+-- ============================================================================
+
+--- Pandoc utility function for converting values to strings
+--- @type function
+M.stringify = pandoc.utils.stringify
+
+--- Check if a string is empty or nil.
+--- Utility function to determine if a value is empty or nil,
+--- which is useful for parameter validation throughout the module.
+--- @param s string|nil|table The value to check for emptiness
+--- @return boolean True if the value is nil or empty, false otherwise
+--- @usage local result = M.is_empty("") -- returns true
+--- @usage local result = M.is_empty(nil) -- returns true
+--- @usage local result = M.is_empty("hello") -- returns false
+function M.is_empty(s)
+ return s == nil or s == ''
+end
+
+--- Escape special pattern characters in a string for Lua pattern matching
+--- @param s string The string to escape
+--- @return string The escaped string
+--- @usage local escaped = M.escape_pattern("user/repo#123")
+function M.escape_pattern(s)
+ local escaped = s:gsub('([%^%$%(%)%%%.%[%]%*%+%-%?])', '%%%1')
+ return escaped
+end
+
+--- Split a string by a separator
+--- @param str string The string to split
+--- @param sep string The separator pattern
+--- @return table Array of string fields
+--- @usage local parts = M.split("a.b.c", ".")
+function M.split(str, sep)
+ local fields = {}
+ local pattern = string.format('([^%s]+)', sep)
+ str:gsub(pattern, function(c) fields[#fields + 1] = c end)
+ return fields
+end
+
+--- Trim leading and trailing whitespace from a string
+--- @param str string The string to trim
+--- @return string The trimmed string
+--- @usage local trimmed = M.trim(" hello world ") -- returns "hello world"
+function M.trim(str)
+ if str == nil then return '' end
+ return str:match('^%s*(.-)%s*$')
+end
+
+--- Convert any value to a string, handling Pandoc objects and empty values.
+--- Returns nil for empty or nil values, otherwise returns a string representation.
+--- @param val any The value to convert
+--- @return string|nil The string value or nil if empty
+--- @usage local str = M.to_string(kwargs.value)
+function M.to_string(val)
+ if not val then return nil end
+ if type(val) == 'string' then
+ return val ~= '' and val or nil
+ end
+ -- Handle Pandoc objects
+ if pandoc and pandoc.utils and pandoc.utils.stringify then
+ local str = pandoc.utils.stringify(val)
+ return str ~= '' and str or nil
+ end
+ local str = tostring(val)
+ return str ~= '' and str or nil
+end
+
+-- ============================================================================
+-- ESCAPE UTILITIES
+-- ============================================================================
+
+--- Escape special LaTeX characters in text.
+--- @param text string The text to escape
+--- @return string The escaped text safe for LaTeX
+function M.escape_latex(text)
+ text = string.gsub(text, '\\', '\\textbackslash{}')
+ text = string.gsub(text, '%{', '\\{')
+ text = string.gsub(text, '%}', '\\}')
+ text = string.gsub(text, '%$', '\\$')
+ text = string.gsub(text, '%&', '\\&')
+ text = string.gsub(text, '%%', '\\%%')
+ text = string.gsub(text, '%#', '\\#')
+ text = string.gsub(text, '%^', '\\textasciicircum{}')
+ text = string.gsub(text, '%_', '\\_')
+ text = string.gsub(text, '~', '\\textasciitilde{}')
+ return text
+end
+
+--- Escape special Typst characters in text.
+--- @param text string The text to escape
+--- @return string The escaped text safe for Typst
+function M.escape_typst(text)
+ text = string.gsub(text, '%#', '\\#')
+ return text
+end
+
+--- Escape characters for Typst string literals (inside `"..."`).
+--- @param text string The text to escape
+--- @return string The escaped text safe for Typst string literals
+function M.escape_typst_string(text)
+ return text:gsub('\\', '\\\\'):gsub('"', '\\"')
+end
+
+--- Escape special Lua pattern characters for use in string.gsub.
+--- @param text string The text containing characters to escape
+--- @return string The escaped text safe for Lua patterns
+function M.escape_lua_pattern(text)
+ text = string.gsub(text, '%%', '%%%%')
+ text = string.gsub(text, '%^', '%%^')
+ text = string.gsub(text, '%$', '%%$')
+ text = string.gsub(text, '%(', '%%(')
+ text = string.gsub(text, '%)', '%%)')
+ text = string.gsub(text, '%.', '%%.')
+ text = string.gsub(text, '%[', '%%[')
+ text = string.gsub(text, '%]', '%%]')
+ text = string.gsub(text, '%*', '%%*')
+ text = string.gsub(text, '%+', '%%+')
+ text = string.gsub(text, '%-', '%%-')
+ text = string.gsub(text, '%?', '%%?')
+ return text
+end
+
+--- Escape special HTML characters in text.
+--- Escapes &, <, >, ", and ' to prevent XSS and ensure valid HTML.
+--- @param text string The text to escape
+--- @return string Escaped text safe for use in HTML
+--- @usage local escaped = M.escape_html('Hello ')
+function M.escape_html(text)
+ if text == nil then return '' end
+ if type(text) ~= 'string' then text = tostring(text) end
+ local result = text
+ :gsub('&', '&')
+ :gsub('<', '<')
+ :gsub('>', '>')
+ :gsub('"', '"')
+ :gsub("'", ''')
+ return result
+end
+
+--- Escape special HTML attribute characters.
+--- Escapes characters that could break attribute values.
+--- @param value string The attribute value to escape
+--- @return string Escaped value safe for use in HTML attributes
+--- @usage local escaped = M.escape_attribute('Hello "World"')
+function M.escape_attribute(value)
+ if value == nil then return '' end
+ if type(value) ~= 'string' then value = tostring(value) end
+ local result = value
+ :gsub('&', '&')
+ :gsub('"', '"')
+ :gsub('<', '<')
+ :gsub('>', '>')
+ return result
+end
+
+--- Escape text for different formats.
+--- @param text string The text to escape
+--- @param format string The format to escape for (e.g., "latex", "typst", "lua")
+--- @return string The escaped text
+function M.escape_text(text, format)
+ local escape_functions = {
+ latex = M.escape_latex,
+ typst = M.escape_typst,
+ lua = M.escape_lua_pattern
+ }
+
+ local escape = escape_functions[format]
+ if escape then
+ return escape(text)
+ else
+ error('Unsupported escape format: ' .. format)
+ end
+end
+
+--- Converts a string to a valid HTML id by lowercasing and replacing spaces.
+--- @param text string The text to convert
+--- @return string The HTML id
+function M.ascii_id(text)
+ local id = text:lower():gsub('[^a-z0-9 ]', ''):gsub(' +', '-')
+ return id
+end
+
+-- ============================================================================
+-- MODULE EXPORT
+-- ============================================================================
+
+return M
diff --git a/docs/_extensions/mcanouil/iconify/_modules/typst.lua b/docs/_extensions/mcanouil/iconify/_modules/typst.lua
new file mode 100644
index 0000000..511ae36
--- /dev/null
+++ b/docs/_extensions/mcanouil/iconify/_modules/typst.lua
@@ -0,0 +1,435 @@
+--- MC Iconify Typst - Iconify SVG retrieval, on-disk caching and Typst emission
+--- @module "typst"
+--- @license MIT
+--- @copyright 2026 Mickaël Canouil
+--- @author Mickaël Canouil
+--- @version 1.0.0
+---
+--- Typst cannot natively reach the Iconify icon library. This module fetches
+--- the SVG for a requested icon from the public Iconify API, caches it on disk
+--- under the Quarto project cache, and emits a Typst `#image(...)` referencing
+--- the cached file. The cache is bounded (age- and count-based) and the
+--- cleanup is lock-free yet concurrency-safe: it only ever removes entries
+--- whose `.used` stamp is older than the threshold, and every in-flight render
+--- re-stamps the icons it uses so a concurrent sweep never selects them.
+
+local M = {}
+
+--- Load a sibling module from the same directory as this file.
+--- @param filename string The sibling module filename (e.g., 'string.lua')
+--- @return table The loaded module
+local function load_sibling(filename)
+ local source = debug.getinfo(1, 'S').source:sub(2)
+ local dir = source:match('(.*[/\\])') or ''
+ return require((dir .. filename):gsub('%.lua$', ''))
+end
+
+local str = load_sibling('string.lua')
+local log = load_sibling('logging.lua')
+local meta_mod = load_sibling('metadata.lua')
+
+--- Extension name constant
+local EXTENSION_NAME = 'iconify'
+--- Base URL of the public Iconify SVG API.
+local API_BASE = 'https://api.iconify.design/'
+--- Default cache directory, relative to the Quarto project root.
+local DEFAULT_CACHE_REL = '.quarto/iconify-svg'
+--- Default maximum age (days) before a cache entry is evicted.
+local DEFAULT_MAX_AGE_DAYS = 30
+--- Grace window (seconds) during which a recently-used entry is never evicted
+--- by the count cap, protecting icons an in-flight render is relying on.
+local GRACE_SECONDS = 300
+
+--- Units that Typst's `image` height/width accept. CSS units such as `px`,
+--- `rem`, `ex` and the viewport units are intentionally excluded.
+--- @type table
+local TYPST_UNITS = {
+ pt = true, mm = true, cm = true, ['in'] = true, em = true, ['%'] = true
+}
+
+-- ============================================================================
+-- PATH / NAMING HELPERS
+-- ============================================================================
+
+--- Resolve the Quarto project root. Falls back to the working directory for
+--- single-file renders where no project is active.
+--- @return string
+local function project_base()
+ local base = os.getenv('QUARTO_PROJECT_DIR')
+ if base == nil or base == '' then
+ return '.'
+ end
+ return base
+end
+
+--- Resolve the cache directory relative to the project root, honouring the
+--- `extensions.iconify.typst-cache` metadata override. The result is kept
+--- inside the project root: leading/trailing slashes are trimmed and any
+--- `..` segments are dropped so the override cannot escape the project (and
+--- so the Typst root-relative `#image` path stays valid).
+--- @param meta table|nil Document metadata
+--- @return string A normalised, project-root-relative directory
+local function resolve_reldir(meta)
+ local rel = meta and meta_mod.get_metadata_value(meta, 'iconify', 'typst-cache')
+ if str.is_empty(rel) then
+ rel = DEFAULT_CACHE_REL
+ end
+ --- @cast rel string
+ --- @type table
+ local segments = {}
+ for segment in rel:gmatch('[^/\\]+') do
+ if segment ~= '..' and segment ~= '.' then
+ segments[#segments + 1] = segment
+ end
+ end
+ if #segments == 0 then
+ return DEFAULT_CACHE_REL
+ end
+ return table.concat(segments, '/')
+end
+
+--- URL-encode a query parameter value (RFC 3986 unreserved set kept verbatim).
+--- @param value string
+--- @return string
+local function urlencode(value)
+ return (value:gsub('[^%w%-_%.~]', function(c)
+ return string.format('%%%02X', string.byte(c))
+ end))
+end
+
+--- Build a deterministic, sorted query string from a parameter table.
+--- Keys are sorted so the resulting string (and its hash) is stable.
+--- @param params table
+--- @return string The query string without a leading `?` (empty if no params)
+function M.build_query(params)
+ --- @type table
+ local keys = {}
+ for k, v in pairs(params) do
+ if not str.is_empty(v) then
+ keys[#keys + 1] = k
+ end
+ end
+ table.sort(keys)
+ --- @type table
+ local parts = {}
+ for _, k in ipairs(keys) do
+ parts[#parts + 1] = k .. '=' .. urlencode(params[k])
+ end
+ return table.concat(parts, '&')
+end
+
+--- Assemble the Iconify SVG API URL for an icon and query.
+--- @param set string Icon set (prefix)
+--- @param icon string Icon name
+--- @param query string Pre-built query string (may be empty)
+--- @return string
+function M.build_api_url(set, icon, query)
+ local url = API_BASE .. set .. '/' .. icon .. '.svg'
+ if query ~= '' then
+ url = url .. '?' .. query
+ end
+ return url
+end
+
+--- Deterministic cache file name for an icon variant.
+--- @param set string
+--- @param icon string
+--- @param query string
+--- @return string
+local function entry_name(set, icon, query)
+ local hash = pandoc.utils.sha1(set .. '/' .. icon .. '?' .. query):sub(1, 8)
+ return set .. '-' .. icon .. '-' .. hash .. '.svg'
+end
+
+-- ============================================================================
+-- FILESYSTEM HELPERS
+-- ============================================================================
+
+--- Ensure a directory exists (creating parents). Failure is non-fatal.
+--- @param dir string
+--- @return nil
+local function ensure_dir(dir)
+ pcall(function() pandoc.system.make_directory(dir, true) end)
+end
+
+--- Write content to a path atomically: write to a unique temp file then
+--- rename into place so a concurrent reader never sees a partial file.
+--- @param path string Destination path
+--- @param content string
+--- @return boolean True on success
+local function write_atomic(path, content)
+ local tmp = path .. '.tmp.' .. tostring(os.time()) .. '.' ..
+ tostring(math.random(0, 1000000)) .. tostring(os.clock())
+ local handle = io.open(tmp, 'wb')
+ if not handle then
+ return false
+ end
+ handle:write(content)
+ handle:close()
+ if os.rename(tmp, path) then
+ return true
+ end
+ -- Windows rename fails if the destination exists; replace then retry.
+ os.remove(path)
+ if os.rename(tmp, path) then
+ return true
+ end
+ os.remove(tmp)
+ return false
+end
+
+--- Path of the sidecar last-used stamp for a cache entry.
+--- @param fspath string
+--- @return string
+local function stamp_path(fspath)
+ return fspath .. '.used'
+end
+
+--- Record the current time as the last-used stamp for a cache entry.
+--- @param fspath string
+--- @return nil
+local function touch(fspath)
+ write_atomic(stamp_path(fspath), tostring(os.time()))
+end
+
+--- Read the last-used epoch from a cache entry's stamp.
+--- @param fspath string
+--- @return integer|nil
+local function read_stamp(fspath)
+ local handle = io.open(stamp_path(fspath), 'rb')
+ if not handle then
+ return nil
+ end
+ local content = handle:read('*a')
+ handle:close()
+ if content == nil then
+ return nil
+ end
+ return tonumber(content:match('%d+'))
+end
+
+-- ============================================================================
+-- FETCHING
+-- ============================================================================
+
+--- Check that a payload looks like an SVG document.
+--- @param data string|nil
+--- @return boolean
+local function valid_svg(data)
+ if str.is_empty(data) then
+ return false
+ end
+ --- @cast data string
+ local head = data:gsub('^%s+', ''):sub(1, 5):lower()
+ return head:sub(1, 4) == '/dev/null")
+ if handle then
+ local out = handle:read('*a')
+ handle:close()
+ if valid_svg(out) then
+ return out
+ end
+ end
+
+ return nil
+end
+
+-- ============================================================================
+-- PUBLIC API
+-- ============================================================================
+
+--- Ensure an icon SVG is cached on disk, fetching it if needed.
+--- Refreshes the last-used stamp on every hit and write.
+--- @param set string
+--- @param icon string
+--- @param query string Pre-built query string (may be empty)
+--- @param meta table|nil Document metadata
+--- @return string|nil Typst project-root-relative image path, or nil on failure
+function M.ensure_cached(set, icon, query, meta)
+ local reldir = resolve_reldir(meta)
+ local dir = project_base() .. '/' .. reldir
+ local name = entry_name(set, icon, query)
+ local fspath = dir .. '/' .. name
+ --- Leading slash makes the path relative to the Typst project root.
+ local typst_path = '/' .. reldir .. '/' .. name
+
+ local existing = io.open(fspath, 'rb')
+ if existing then
+ existing:close()
+ touch(fspath)
+ return typst_path
+ end
+
+ local data = fetch_svg(M.build_api_url(set, icon, query))
+ if data == nil then
+ return nil
+ end
+
+ ensure_dir(dir)
+ if not write_atomic(fspath, data) then
+ return nil
+ end
+ touch(fspath)
+ return typst_path
+end
+
+--- Render an icon as a Typst `#image`, fetching/caching as needed.
+--- @param opts table Fields: set, icon, query, size_value, inline, alt,
+--- fallback, meta.
+--- @return any Pandoc RawInline (Typst), Str (fallback), or Null
+function M.render(opts)
+ local typst_path = M.ensure_cached(opts.set, opts.icon, opts.query, opts.meta)
+ if typst_path == nil then
+ log.log_warning(
+ EXTENSION_NAME,
+ 'Could not retrieve icon "' .. opts.set .. ':' .. opts.icon ..
+ '" for Typst output' ..
+ (str.is_empty(opts.fallback) and '.' or '; using fallback.')
+ )
+ if not str.is_empty(opts.fallback) then
+ return pandoc.Str(opts.fallback)
+ end
+ return pandoc.Null()
+ end
+
+ --- @type string
+ local height = opts.size_value
+ if str.is_empty(height) then
+ height = '1em'
+ end
+
+ --- @type string
+ local image_args = '"' .. str.escape_typst_string(typst_path) ..
+ '", height: ' .. height
+ if not str.is_empty(opts.alt) then
+ image_args = image_args .. ', alt: "' .. str.escape_typst_string(opts.alt) .. '"'
+ end
+
+ --- @type string
+ local code
+ if opts.inline then
+ code = '#box(baseline: 0.125em, image(' .. image_args .. '))'
+ else
+ code = '#image(' .. image_args .. ')'
+ end
+ return pandoc.RawInline('typst', code)
+end
+
+--- Validate that a length value uses a Typst-supported unit.
+--- @param value string|nil
+--- @return string|nil The value if Typst-compatible, otherwise nil
+function M.typst_length(value)
+ if str.is_empty(value) then
+ return nil
+ end
+ --- @cast value string
+ local number_part, unit = value:match('^([-+]?%d*%.?%d+)(.*)$')
+ if not number_part or unit == '' then
+ return nil
+ end
+ if TYPST_UNITS[unit] then
+ return value
+ end
+ return nil
+end
+
+--- Evict cache entries to keep the cache bounded. Age pass first, then a
+--- least-recently-used count cap. Lock-free and idempotent; safe to run
+--- concurrently across independent renders: the age pass only removes entries
+--- unused for `max-age` days (which no live render references, since every use
+--- re-stamps), and the count cap never evicts entries used within a short
+--- grace window (so an in-flight render's freshly-cached icons are protected).
+--- @param meta table Document metadata
+--- @return nil
+function M.cleanup(meta)
+ local dir = project_base() .. '/' .. resolve_reldir(meta)
+
+ --- @type table|nil
+ local listing
+ local ok = pcall(function() listing = pandoc.system.list_directory(dir) end)
+ if not ok or listing == nil then
+ -- Cache directory does not exist yet (nothing rendered): nothing to do.
+ return
+ end
+
+ --- @type number
+ local max_age_days = tonumber(
+ meta_mod.get_metadata_value(meta, 'iconify', 'typst-cache-max-age')
+ ) or DEFAULT_MAX_AGE_DAYS
+ --- @type number
+ local max_entries = tonumber(
+ meta_mod.get_metadata_value(meta, 'iconify', 'typst-cache-max-entries')
+ ) or 0
+ --- @type integer
+ local now = os.time()
+
+ --- @type table
+ local entries = {}
+ for _, fname in ipairs(listing) do
+ if fname:sub(-4) == '.svg' then
+ local fspath = dir .. '/' .. fname
+ local used = read_stamp(fspath)
+ if used == nil then
+ -- Missing/garbled stamp: treat as in use, re-stamp, never evict now.
+ touch(fspath)
+ used = now
+ end
+ entries[#entries + 1] = { path = fspath, used = used }
+ end
+ end
+
+ --- @param entry table
+ --- @return nil
+ local function remove_entry(entry)
+ os.remove(entry.path)
+ os.remove(stamp_path(entry.path))
+ end
+
+ --- @type table
+ local survivors = {}
+ if max_age_days > 0 then
+ local cutoff = now - math.floor(max_age_days * 86400)
+ for _, entry in ipairs(entries) do
+ if entry.used < cutoff then
+ remove_entry(entry)
+ else
+ survivors[#survivors + 1] = entry
+ end
+ end
+ else
+ survivors = entries
+ end
+
+ if max_entries > 0 and #survivors > max_entries then
+ -- Oldest first; never evict entries used within the grace window, as a
+ -- concurrent render may be relying on them right now.
+ local grace = now - GRACE_SECONDS
+ table.sort(survivors, function(a, b) return a.used < b.used end)
+ local count = #survivors
+ for i = 1, #survivors do
+ if count <= max_entries then break end
+ if survivors[i].used >= grace then break end
+ remove_entry(survivors[i])
+ count = count - 1
+ end
+ end
+end
+
+-- ============================================================================
+-- MODULE EXPORT
+-- ============================================================================
+
+return M
diff --git a/docs/_extensions/mcanouil/iconify/_schema.yml b/docs/_extensions/mcanouil/iconify/_schema.yml
new file mode 100644
index 0000000..dd1658e
--- /dev/null
+++ b/docs/_extensions/mcanouil/iconify/_schema.yml
@@ -0,0 +1,171 @@
+# Schema for the iconify extension
+
+$schema: https://m.canouil.dev/quarto-wizard/assets/schema/v2/extension-schema.json
+
+options:
+ set:
+ type: string
+ default: "octicon"
+ description: "Default icon set to use when not specified in the shortcode (e.g. 'mdi', 'fa-solid')."
+ size:
+ type: string
+ description: "Default icon size as a keyword or CSS value (e.g. 'large', '2x', '1.5em')."
+ width:
+ type: string
+ description: "Default icon width."
+ height:
+ type: string
+ description: "Default icon height."
+ flip:
+ type: string
+ description: "Default flip transformation for icons."
+ enum:
+ - horizontal
+ - vertical
+ - horizontal,vertical
+ rotate:
+ type: string
+ description: "Default rotation for icons (e.g. '90deg', '180deg', '1')."
+ style:
+ type: string
+ description: "Default additional inline CSS styles applied to all icons."
+ inline:
+ type: boolean
+ default: true
+ description: "Whether to render icons inline by default."
+ mode:
+ type: string
+ description: "Default rendering mode for icons."
+ enum:
+ - svg
+ - style
+ - bg
+ - mask
+ fallback:
+ type: string
+ description: "Default fallback text or emoji shown when an icon cannot be loaded (e.g. unknown name, offline, CDN unreachable)."
+ preload:
+ type: array
+ description: "List of local file paths containing Iconify icon-collection JSON to preload, enabling offline rendering of those icons; requires the iconify filter to be active (e.g. `filters: [iconify]`)."
+ items:
+ type: string
+ typst-cache:
+ type: string
+ default: ".quarto/iconify-svg"
+ description: "Directory (relative to the project root) where SVGs retrieved for Typst output are cached. Point at a tracked directory to commit a reproducible offline cache."
+ typst-cache-max-age:
+ type: number
+ default: 30
+ description: "Maximum age in days before an unused Typst cache entry is pruned. Set to 0 to disable age-based pruning."
+ typst-cache-max-entries:
+ type: number
+ default: 0
+ description: "Maximum number of Typst cache entries; the least-recently-used beyond this cap are pruned. 0 means unlimited."
+
+shortcodes:
+ iconify:
+ description: "Renders an Iconify icon, accepting either 'set:icon' or 'set icon' syntax."
+ arguments:
+ - name: set-or-icon
+ type: string
+ description: "Icon set name, or the combined 'set:icon' format."
+ - name: icon
+ type: string
+ description: "Icon name when the first argument is the set name."
+ attributes:
+ size:
+ type: string
+ description: "Icon size as a keyword or CSS value (e.g. 'large', '2x', '1.5em')."
+ width:
+ type: string
+ description: "Icon width."
+ height:
+ type: string
+ description: "Icon height."
+ flip:
+ type: string
+ description: "Flip transformation for the icon."
+ enum:
+ - horizontal
+ - vertical
+ - horizontal,vertical
+ rotate:
+ type: string
+ description: "Rotation for the icon (e.g. '90deg', '180deg', '1')."
+ color:
+ type: string
+ description: "Icon colour for Typst output (e.g. 'red', '#74aadb'); applied to monochrome icons via the Iconify API."
+ inline:
+ type: string
+ description: "Whether to render the icon inline."
+ enum:
+ - "true"
+ - "false"
+ mode:
+ type: string
+ description: "Rendering mode for the icon."
+ enum:
+ - svg
+ - style
+ - bg
+ - mask
+ style:
+ type: string
+ description: "Additional inline CSS styles for the icon."
+ label:
+ type: string
+ description: "Accessible label for the icon (aria-label)."
+ title:
+ type: string
+ description: "Title attribute for the icon tooltip."
+ fallback:
+ type: string
+ description: "Text or emoji shown when the icon cannot be loaded (e.g. unknown name, offline, CDN unreachable)."
+ quarto:
+ description: "Renders the Quarto icon with default blue styling from the simple-icons set."
+ attributes:
+ size:
+ type: string
+ description: "Icon size as a keyword or CSS value."
+ width:
+ type: string
+ description: "Icon width."
+ height:
+ type: string
+ description: "Icon height."
+ flip:
+ type: string
+ description: "Flip transformation for the icon."
+ enum:
+ - horizontal
+ - vertical
+ - horizontal,vertical
+ rotate:
+ type: string
+ description: "Rotation for the icon (e.g. '90deg', '180deg', '1')."
+ inline:
+ type: string
+ description: "Whether to render the icon inline."
+ enum:
+ - "true"
+ - "false"
+ mode:
+ type: string
+ description: "Rendering mode for the icon."
+ enum:
+ - svg
+ - style
+ - bg
+ - mask
+ style:
+ type: string
+ description: "Additional inline CSS styles for the icon."
+ label:
+ type: string
+ description: "Accessible label for the icon."
+ title:
+ type: string
+ description: "Title attribute for the icon tooltip."
+ fallback:
+ type: string
+ description: "Text or emoji shown when the icon cannot be loaded."
diff --git a/docs/_extensions/mcanouil/iconify/_snippets.json b/docs/_extensions/mcanouil/iconify/_snippets.json
new file mode 100644
index 0000000..e2fba87
--- /dev/null
+++ b/docs/_extensions/mcanouil/iconify/_snippets.json
@@ -0,0 +1,17 @@
+{
+ "Icon": {
+ "prefix": "iconify",
+ "body": "{{< iconify ${1:fluent-emoji}:${2:exploding-head} >}}",
+ "description": "Insert an Iconify icon using set:icon syntax"
+ },
+ "Icon with size": {
+ "prefix": "iconify-size",
+ "body": "{{< iconify ${1:fluent-emoji}:${2:exploding-head} size=${3:1em} >}}",
+ "description": "Insert an Iconify icon with a size"
+ },
+ "Icon with style": {
+ "prefix": "iconify-style",
+ "body": "{{< iconify ${1:simple-icons}:${2:quarto} style=\"color:${3:#74aadb};\" >}}",
+ "description": "Insert an Iconify icon with custom CSS style"
+ }
+}
diff --git a/docs/_extensions/mcanouil/iconify/iconify-fallback.css b/docs/_extensions/mcanouil/iconify/iconify-fallback.css
new file mode 100644
index 0000000..86af140
--- /dev/null
+++ b/docs/_extensions/mcanouil/iconify/iconify-fallback.css
@@ -0,0 +1,15 @@
+/* Iconify fallback wrapper. Keeps the iconify-icon and fallback text inline. */
+
+.iconify-icon-wrapper {
+ display: inline-block;
+ vertical-align: -0.125em;
+ line-height: 1;
+}
+
+.iconify-icon-wrapper > .iconify-icon-fallback {
+ display: inline;
+}
+
+.iconify-icon-wrapper > .iconify-icon-fallback[hidden] {
+ display: none;
+}
diff --git a/docs/_extensions/mcanouil/iconify/iconify-fallback.js b/docs/_extensions/mcanouil/iconify/iconify-fallback.js
new file mode 100644
index 0000000..b15536d
--- /dev/null
+++ b/docs/_extensions/mcanouil/iconify/iconify-fallback.js
@@ -0,0 +1,70 @@
+// Iconify fallback runtime.
+// For each `.iconify-icon-wrapper`, watch the contained `` and
+// reveal the sibling `.iconify-icon-fallback` element when the icon fails to
+// load. Failure covers unknown icon names, offline use, and CDN unreachable.
+
+(function () {
+ 'use strict';
+
+ // Maximum number of poll cycles before declaring the icon failed.
+ // Iconify's default request timeout is 5s; we poll for ~6s.
+ var MAX_POLLS = 60;
+ var POLL_INTERVAL_MS = 100;
+
+ function watchWrapper(wrapper) {
+ var icon = wrapper.querySelector('iconify-icon');
+ var fallback = wrapper.querySelector('.iconify-icon-fallback');
+ if (!icon || !fallback) return;
+
+ var polls = 0;
+
+ function reveal() {
+ fallback.hidden = false;
+ icon.setAttribute('hidden', '');
+ wrapper.setAttribute('data-iconify-state', 'failed');
+ }
+
+ function settle() {
+ wrapper.setAttribute('data-iconify-state', 'rendered');
+ }
+
+ function tick() {
+ var status = icon.status;
+ if (status === 'rendered') {
+ settle();
+ return;
+ }
+ if (status === 'failed') {
+ reveal();
+ return;
+ }
+ polls += 1;
+ if (polls >= MAX_POLLS) {
+ reveal();
+ return;
+ }
+ setTimeout(tick, POLL_INTERVAL_MS);
+ }
+
+ // `iconify-icon` may not be defined yet if the script load order differs;
+ // wait for the custom element to be upgraded before polling its `status`.
+ if (window.customElements && typeof window.customElements.whenDefined === 'function') {
+ window.customElements.whenDefined('iconify-icon').then(tick, reveal);
+ } else {
+ tick();
+ }
+ }
+
+ function init() {
+ var wrappers = document.querySelectorAll('.iconify-icon-wrapper[data-iconify-fallback]');
+ for (var i = 0; i < wrappers.length; i += 1) {
+ watchWrapper(wrappers[i]);
+ }
+ }
+
+ if (document.readyState === 'loading') {
+ document.addEventListener('DOMContentLoaded', init);
+ } else {
+ init();
+ }
+})();
diff --git a/docs/_extensions/mcanouil/iconify/iconify-filter.lua b/docs/_extensions/mcanouil/iconify/iconify-filter.lua
new file mode 100644
index 0000000..3fd1fbd
--- /dev/null
+++ b/docs/_extensions/mcanouil/iconify/iconify-filter.lua
@@ -0,0 +1,121 @@
+--- @module iconify-filter
+--- @license MIT
+--- @copyright 2026 Mickaël Canouil
+--- @author Mickaël Canouil
+---
+--- Document-level filter for the Iconify extension. Reads one or more
+--- author-supplied JSON files containing Iconify icon-collection payloads
+--- and injects them as `window.IconifyPreload`. The Iconify Web Component
+--- reads that global at boot and renders the preloaded icons without any
+--- CDN call, which makes the document work offline (or when the public
+--- Iconify CDN is unreachable) for those icons.
+
+--- Extension name constant
+local EXTENSION_NAME = "iconify"
+
+--- Load modules
+local str = require(quarto.utils.resolve_path('_modules/string.lua'):gsub('%.lua$', ''))
+local log = require(quarto.utils.resolve_path('_modules/logging.lua'):gsub('%.lua$', ''))
+
+--- Tracker so the preload payload is only injected once per document, even
+--- when the filter runs multiple passes.
+--- @type boolean
+local preload_injected = false
+
+--- Collect preload file paths from metadata.
+--- Accepts a single string, a Pandoc Inlines value, or a list of either.
+--- @param value any The raw metadata value
+--- @return table
+local function collect_paths(value)
+ --- @type table
+ local paths = {}
+ if value == nil then
+ return paths
+ end
+ -- Pandoc MetaList is a table with sequential integer keys and no `.t` tag.
+ if type(value) == 'table' and value[1] ~= nil and value.t == nil then
+ for _, item in ipairs(value) do
+ local raw = str.stringify(item)
+ if not str.is_empty(raw) then
+ table.insert(paths, raw)
+ end
+ end
+ else
+ local raw = str.stringify(value)
+ if not str.is_empty(raw) then
+ table.insert(paths, raw)
+ end
+ end
+ return paths
+end
+
+--- Read the entire content of a file. Returns nil if the file cannot be opened.
+--- @param path string
+--- @return string|nil
+local function read_file(path)
+ local handle = io.open(path, 'rb')
+ if not handle then return nil end
+ local content = handle:read('*a')
+ handle:close()
+ return content
+end
+
+--- Inject author-supplied icon data as a global `IconifyPreload` payload.
+--- @param meta table
+--- @return nil
+local function inject_preload(meta)
+ if preload_injected then return end
+ if meta == nil or meta.extensions == nil or meta.extensions.iconify == nil then
+ return
+ end
+ if meta.extensions.iconify.preload == nil then
+ return
+ end
+
+ --- @type table
+ local paths = collect_paths(meta.extensions.iconify.preload)
+ if #paths == 0 then return end
+
+ --- @type table
+ local payloads = {}
+ for _, path in ipairs(paths) do
+ local content = read_file(path)
+ if content == nil then
+ log.log_warning(
+ EXTENSION_NAME,
+ 'Preload file "' .. path .. '" could not be read; skipping.'
+ )
+ else
+ --- @type string
+ local trimmed = content:gsub('^%s+', ''):gsub('%s+$', '')
+ if trimmed:sub(1, 1) ~= '{' then
+ log.log_warning(
+ EXTENSION_NAME,
+ 'Preload file "' .. path .. '" does not start with "{"; skipping.'
+ )
+ else
+ table.insert(payloads, trimmed)
+ end
+ end
+ end
+
+ if #payloads == 0 then return end
+
+ --- @type string
+ local joined = table.concat(payloads, ',')
+ quarto.doc.include_text(
+ 'in-header',
+ ''
+ )
+ preload_injected = true
+end
+
+--- Pandoc Meta handler. Inject preload script for HTML output only.
+--- @param meta table
+--- @return table
+function Meta(meta)
+ if quarto.doc.is_format('html:js') then
+ inject_preload(meta)
+ end
+ return meta
+end
diff --git a/docs/_extensions/mcanouil/iconify/iconify-icon.min.js b/docs/_extensions/mcanouil/iconify/iconify-icon.min.js
new file mode 100644
index 0000000..2b9c109
--- /dev/null
+++ b/docs/_extensions/mcanouil/iconify/iconify-icon.min.js
@@ -0,0 +1,13 @@
+/**
+* (c) Iconify
+*
+* For the full copyright and license information, please view the license.txt
+* files at https://github.com/iconify/iconify
+*
+* Licensed under MIT.
+* Source: https://github.com/iconify/code/tree/gh-pages/iconify-icon
+*
+* @license MIT
+* @version 3.0.2
+*/
+!function(){"use strict";const t=Object.freeze({left:0,top:0,width:16,height:16}),e=Object.freeze({rotate:0,vFlip:!1,hFlip:!1}),n=Object.freeze({...t,...e}),i=Object.freeze({...n,body:"",hidden:!1}),r=Object.freeze({width:null,height:null}),o=Object.freeze({...r,...e});const s=/[\s,]+/;const c={...o,preserveAspectRatio:""};function a(t){const e={...c},n=(e,n)=>t.getAttribute(e)||n;var i;return e.width=n("width",null),e.height=n("height",null),e.rotate=function(t,e=0){const n=t.replace(/^-?[0-9.]*/,"");function i(t){for(;t<0;)t+=4;return t%4}if(""===n){const e=parseInt(t);return isNaN(e)?0:i(e)}if(n!==t){let e=0;switch(n){case"%":e=25;break;case"deg":e=90}if(e){let r=parseFloat(t.slice(0,t.length-n.length));return isNaN(r)?0:(r/=e,r%1==0?i(r):0)}}return e}(n("rotate","")),i=e,n("flip","").split(s).forEach(t=>{switch(t.trim()){case"horizontal":i.hFlip=!0;break;case"vertical":i.vFlip=!0}}),e.preserveAspectRatio=n("preserveAspectRatio",n("preserveaspectratio","")),e}const u=/^[a-z0-9]+(-[a-z0-9]+)*$/,l=(t,e,n,i="")=>{const r=t.split(":");if("@"===t.slice(0,1)){if(r.length<2||r.length>3)return null;i=r.shift().slice(1)}if(r.length>3||!r.length)return null;if(r.length>1){const t=r.pop(),n=r.pop(),o={provider:r.length>0?r[0]:i,prefix:n,name:t};return e&&!f(o)?null:o}const o=r[0],s=o.split("-");if(s.length>1){const t={provider:i,prefix:s.shift(),name:s.join("-")};return e&&!f(t)?null:t}if(n&&""===i){const t={provider:i,prefix:"",name:o};return e&&!f(t,n)?null:t}return null},f=(t,e)=>!!t&&!(!(e&&""===t.prefix||t.prefix)||!t.name);function d(t,n){const r=function(t,e){const n={};!t.hFlip!=!e.hFlip&&(n.hFlip=!0),!t.vFlip!=!e.vFlip&&(n.vFlip=!0);const i=((t.rotate||0)+(e.rotate||0))%4;return i&&(n.rotate=i),n}(t,n);for(const o in i)o in e?o in t&&!(o in r)&&(r[o]=e[o]):o in n?r[o]=n[o]:o in t&&(r[o]=t[o]);return r}function h(t,e,n){const i=t.icons,r=t.aliases||Object.create(null);let o={};function s(t){o=d(i[t]||r[t],o)}return s(e),n.forEach(s),d(t,o)}function p(t,e){const n=[];if("object"!=typeof t||"object"!=typeof t.icons)return n;t.not_found instanceof Array&&t.not_found.forEach(t=>{e(t,null),n.push(t)});const i=function(t){const e=t.icons,n=t.aliases||Object.create(null),i=Object.create(null);return Object.keys(e).concat(Object.keys(n)).forEach(function t(r){if(e[r])return i[r]=[];if(!(r in i)){i[r]=null;const e=n[r]&&n[r].parent,o=e&&t(e);o&&(i[r]=[e].concat(o))}return i[r]}),i}(t);for(const r in i){const o=i[r];o&&(e(r,h(t,r,o)),n.push(r))}return n}const g={provider:"",aliases:{},not_found:{},...t};function b(t,e){for(const n in e)if(n in t&&typeof t[n]!=typeof e[n])return!1;return!0}function v(t){if("object"!=typeof t||null===t)return null;const e=t;if("string"!=typeof e.prefix||!t.icons||"object"!=typeof t.icons)return null;if(!b(t,g))return null;const n=e.icons;for(const t in n){const e=n[t];if(!t||"string"!=typeof e.body||!b(e,i))return null}const r=e.aliases||Object.create(null);for(const t in r){const e=r[t],o=e.parent;if(!t||"string"!=typeof o||!n[o]&&!r[o]||!b(e,i))return null}return e}const m=Object.create(null);function y(t,e){const n=m[t]||(m[t]=Object.create(null));return n[e]||(n[e]=function(t,e){return{provider:t,prefix:e,icons:Object.create(null),missing:new Set}}(t,e))}function x(t,e){return v(e)?p(e,(e,n)=>{n?t.icons[e]=n:t.missing.add(e)}):[]}function _(t,e){let n=[];return("string"==typeof t?[t]:Object.keys(m)).forEach(t=>{("string"==typeof t&&"string"==typeof e?[e]:Object.keys(m[t]||{})).forEach(e=>{const i=y(t,e);n=n.concat(Object.keys(i.icons).map(n=>(""!==t?"@"+t+":":"")+e+":"+n))})}),n}let w=!1;function k(t){return"boolean"==typeof t&&(w=t),w}function A(t){const e="string"==typeof t?l(t,!0,w):t;if(e){const t=y(e.provider,e.prefix),n=e.name;return t.icons[n]||(t.missing.has(n)?null:void 0)}}function j(t,e){const n=l(t,!0,w);if(!n)return!1;const i=y(n.provider,n.prefix);return e?function(t,e,n){try{if("string"==typeof n.body)return t.icons[e]={...n},!0}catch(t){}return!1}(i,n.name,e):(i.missing.add(n.name),!0)}function O(t,e){if("object"!=typeof t)return!1;if("string"!=typeof e&&(e=t.provider||""),w&&!e&&!t.prefix){let e=!1;return v(t)&&(t.prefix="",p(t,(t,n)=>{j(t,n)&&(e=!0)})),e}const n=t.prefix;return!!f({prefix:n,name:"a"})&&!!x(y(e,n),t)}function C(t){return!!A(t)}function I(t){const e=A(t);return e?{...n,...e}:e}function E(t,e){t.forEach(t=>{const n=t.loaderCallbacks;n&&(t.loaderCallbacks=n.filter(t=>t.id!==e))})}let T=0;const F=Object.create(null);function R(t,e){F[t]=e}function S(t){return F[t]||F[""]}function L(t){let e;if("string"==typeof t.resources)e=[t.resources];else if(e=t.resources,!(e instanceof Array&&e.length))return null;return{resources:e,path:t.path||"/",maxURL:t.maxURL||500,rotate:t.rotate||750,timeout:t.timeout||5e3,random:!0===t.random,index:t.index||0,dataAfterTimeout:!1!==t.dataAfterTimeout}}const P=Object.create(null),M=["https://api.simplesvg.com","https://api.unisvg.com"],N=[];for(;M.length>0;)1===M.length||Math.random()>.5?N.push(M.shift()):N.push(M.pop());function z(t,e){const n=L(e);return null!==n&&(P[t]=n,!0)}function Q(t){return P[t]}function q(){return Object.keys(P)}P[""]=L({resources:["https://api.iconify.design"].concat(N)});const U={resources:[],index:0,timeout:2e3,rotate:750,random:!1,dataAfterTimeout:!1};function D(t,e,n,i){const r=t.resources.length,o=t.random?Math.floor(Math.random()*r):t.index;let s;if(t.random){let e=t.resources.slice(0);for(s=[];e.length>1;){const t=Math.floor(Math.random()*e.length);s.push(e[t]),e=e.slice(0,t).concat(e.slice(t+1))}s=s.concat(e)}else s=t.resources.slice(o).concat(t.resources.slice(0,o));const c=Date.now();let a,u="pending",l=0,f=null,d=[],h=[];function p(){f&&(clearTimeout(f),f=null)}function g(){"pending"===u&&(u="aborted"),p(),d.forEach(t=>{"pending"===t.status&&(t.status="aborted")}),d=[]}function b(t,e){e&&(h=[]),"function"==typeof t&&h.push(t)}function v(){u="failed",h.forEach(t=>{t(void 0,a)})}function m(){d.forEach(t=>{"pending"===t.status&&(t.status="aborted")}),d=[]}function y(){if("pending"!==u)return;p();const i=s.shift();if(void 0===i)return d.length?void(f=setTimeout(()=>{p(),"pending"===u&&(m(),v())},t.timeout)):void v();const r={status:"pending",resource:i,callback:(e,n)=>{!function(e,n,i){const r="success"!==n;switch(d=d.filter(t=>t!==e),u){case"pending":break;case"failed":if(r||!t.dataAfterTimeout)return;break;default:return}if("abort"===n)return a=i,void v();if(r)return a=i,void(d.length||(s.length?y():v()));if(p(),m(),!t.random){const n=t.resources.indexOf(e.resource);-1!==n&&n!==t.index&&(t.index=n)}u="completed",h.forEach(t=>{t(i)})}(r,e,n)}};d.push(r),l++,f=setTimeout(y,t.rotate),n(i,e,r.callback)}return"function"==typeof i&&h.push(i),setTimeout(y),function(){return{startTime:c,payload:e,status:u,queriesSent:l,queriesPending:d.length,subscribe:b,abort:g}}}function H(t){const e={...U,...t};let n=[];function i(){n=n.filter(t=>"pending"===t().status)}return{query:function(t,r,o){const s=D(e,t,r,(t,e)=>{i(),o&&o(t,e)});return n.push(s),s},find:function(t){return n.find(e=>t(e))||null},setIndex:t=>{e.index=t},getIndex:()=>e.index,cleanup:i}}function J(){}const $=Object.create(null);function B(t,e,n){let i,r;if("string"==typeof t){const e=S(t);if(!e)return n(void 0,424),J;r=e.send;const o=function(t){if(!$[t]){const e=Q(t);if(!e)return;$[t]={config:e,redundancy:H(e)}}return $[t]}(t);o&&(i=o.redundancy)}else{const e=L(t);if(e){i=H(e);const n=S(t.resources?t.resources[0]:"");n&&(r=n.send)}}return i&&r?i.query(e,r,n)().abort:(n(void 0,424),J)}function G(){}function V(t){t.iconsLoaderFlag||(t.iconsLoaderFlag=!0,setTimeout(()=>{t.iconsLoaderFlag=!1,function(t){t.pendingCallbacksFlag||(t.pendingCallbacksFlag=!0,setTimeout(()=>{t.pendingCallbacksFlag=!1;const e=t.loaderCallbacks?t.loaderCallbacks.slice(0):[];if(!e.length)return;let n=!1;const i=t.provider,r=t.prefix;e.forEach(e=>{const o=e.icons,s=o.pending.length;o.pending=o.pending.filter(e=>{if(e.prefix!==r)return!0;const s=e.name;if(t.icons[s])o.loaded.push({provider:i,prefix:r,name:s});else{if(!t.missing.has(s))return n=!0,!0;o.missing.push({provider:i,prefix:r,name:s})}return!1}),o.pending.length!==s&&(n||E([t],e.id),e.callback(o.loaded.slice(0),o.missing.slice(0),o.pending.slice(0),e.abort))})}))}(t)}))}function K(t,e,n){function i(){const n=t.pendingIcons;e.forEach(e=>{n&&n.delete(e),t.icons[e]||t.missing.add(e)})}if(n&&"object"==typeof n)try{if(!x(t,n).length)return void i()}catch(t){console.error(t)}i(),V(t)}function W(t,e){t instanceof Promise?t.then(t=>{e(t)}).catch(()=>{e(null)}):e(t)}function X(t,e){t.iconsToLoad?t.iconsToLoad=t.iconsToLoad.concat(e).sort():t.iconsToLoad=e,t.iconsQueueFlag||(t.iconsQueueFlag=!0,setTimeout(()=>{t.iconsQueueFlag=!1;const{provider:e,prefix:n}=t,i=t.iconsToLoad;if(delete t.iconsToLoad,!i||!i.length)return;const r=t.loadIcon;if(t.loadIcons&&(i.length>1||!r))return void W(t.loadIcons(i,n,e),e=>{K(t,i,e)});if(r)return void i.forEach(i=>{W(r(i,n,e),e=>{K(t,[i],e?{prefix:n,icons:{[i]:e}}:null)})});const{valid:o,invalid:s}=function(t){const e=[],n=[];return t.forEach(t=>{(t.match(u)?e:n).push(t)}),{valid:e,invalid:n}}(i);if(s.length&&K(t,s,null),!o.length)return;const c=n.match(u)?S(e):null;c?c.prepare(e,n,o).forEach(n=>{B(e,n,e=>{K(t,n.icons,e)})}):K(t,o,null)}))}const Y=(t,e)=>{const n=function(t){const e={loaded:[],missing:[],pending:[]},n=Object.create(null);t.sort((t,e)=>t.provider!==e.provider?t.provider.localeCompare(e.provider):t.prefix!==e.prefix?t.prefix.localeCompare(e.prefix):t.name.localeCompare(e.name));let i={provider:"",prefix:"",name:""};return t.forEach(t=>{if(i.name===t.name&&i.prefix===t.prefix&&i.provider===t.provider)return;i=t;const r=t.provider,o=t.prefix,s=t.name,c=n[r]||(n[r]=Object.create(null)),a=c[o]||(c[o]=y(r,o));let u;u=s in a.icons?e.loaded:""===o||a.missing.has(s)?e.missing:e.pending;const l={provider:r,prefix:o,name:s};u.push(l)}),e}(function(t,e=!0,n=!1){const i=[];return t.forEach(t=>{const r="string"==typeof t?l(t,e,n):t;r&&i.push(r)}),i}(t,!0,k()));if(!n.pending.length){let t=!0;return e&&setTimeout(()=>{t&&e(n.loaded,n.missing,n.pending,G)}),()=>{t=!1}}const i=Object.create(null),r=[];let o,s;return n.pending.forEach(t=>{const{provider:e,prefix:n}=t;if(n===s&&e===o)return;o=e,s=n,r.push(y(e,n));const c=i[e]||(i[e]=Object.create(null));c[n]||(c[n]=[])}),n.pending.forEach(t=>{const{provider:e,prefix:n,name:r}=t,o=y(e,n),s=o.pendingIcons||(o.pendingIcons=new Set);s.has(r)||(s.add(r),i[e][n].push(r))}),r.forEach(t=>{const e=i[t.provider][t.prefix];e.length&&X(t,e)}),e?function(t,e,n){const i=T++,r=E.bind(null,n,i);if(!e.pending.length)return r;const o={id:i,icons:e,callback:t,abort:r};return n.forEach(t=>{(t.loaderCallbacks||(t.loaderCallbacks=[])).push(o)}),r}(e,n,r):G},Z=t=>new Promise((e,i)=>{const r="string"==typeof t?l(t,!0):t;r?Y([r||t],o=>{if(o.length&&r){const t=A(r);if(t)return void e({...n,...t})}i(t)}):i(t)});function tt(t){try{const e="string"==typeof t?JSON.parse(t):t;if("string"==typeof e.body)return{...e}}catch(t){}}let et=!1;try{et=0===navigator.vendor.indexOf("Apple")}catch(t){}const nt=/(-?[0-9.]*[0-9]+[0-9.]*)/g,it=/^-?[0-9.]*[0-9]+[0-9.]*$/g;function rt(t,e,n){if(1===e)return t;if(n=n||100,"number"==typeof t)return Math.ceil(t*e*n)/n;if("string"!=typeof t)return t;const i=t.split(nt);if(null===i||!i.length)return t;const r=[];let o=i.shift(),s=it.test(o);for(;;){if(s){const t=parseFloat(o);isNaN(t)?r.push(o):r.push(Math.ceil(t*e*n)/n)}else r.push(o);if(o=i.shift(),void 0===o)return r.join("");s=!s}}function ot(t,e){const i={...n,...t},r={...o,...e},s={left:i.left,top:i.top,width:i.width,height:i.height};let c=i.body;[i,r].forEach(t=>{const e=[],n=t.hFlip,i=t.vFlip;let r,o=t.rotate;switch(n?i?o+=2:(e.push("translate("+(s.width+s.left).toString()+" "+(0-s.top).toString()+")"),e.push("scale(-1 1)"),s.top=s.left=0):i&&(e.push("translate("+(0-s.left).toString()+" "+(s.height+s.top).toString()+")"),e.push("scale(1 -1)"),s.top=s.left=0),o<0&&(o-=4*Math.floor(o/4)),o%=4,o){case 1:r=s.height/2+s.top,e.unshift("rotate(90 "+r.toString()+" "+r.toString()+")");break;case 2:e.unshift("rotate(180 "+(s.width/2+s.left).toString()+" "+(s.height/2+s.top).toString()+")");break;case 3:r=s.width/2+s.left,e.unshift("rotate(-90 "+r.toString()+" "+r.toString()+")")}o%2==1&&(s.left!==s.top&&(r=s.left,s.left=s.top,s.top=r),s.width!==s.height&&(r=s.width,s.width=s.height,s.height=r)),e.length&&(c=function(t,e,n){const i=function(t,e="defs"){let n="";const i=t.indexOf("<"+e);for(;i>=0;){const r=t.indexOf(">",i),o=t.indexOf("",o);if(-1===s)break;n+=t.slice(r+1,o).trim(),t=t.slice(0,i).trim()+t.slice(s+1)}return{defs:n,content:t}}(t);return r=i.defs,o=e+i.content+n,r?""+r+""+o:o;var r,o}(c,'',""))});const a=r.width,u=r.height,l=s.width,f=s.height;let d,h;null===a?(h=null===u?"1em":"auto"===u?f:u,d=rt(h,l/f)):(d="auto"===a?l:a,h=null===u?rt(d,f/l):"auto"===u?f:u);const p={},g=(t,e)=>{(t=>"unset"===t||"undefined"===t||"none"===t)(e)||(p[t]=e.toString())};g("width",d),g("height",h);const b=[s.left,s.top,l,f];return p.viewBox=b.join(" "),{attributes:p,viewBox:b,body:c}}function st(t,e){let n=-1===t.indexOf("xlink:")?"":' xmlns:xlink="http://www.w3.org/1999/xlink"';for(const t in e)n+=" "+t+'="'+e[t]+'"';return'"}function ct(t){return'url("'+function(t){return"data:image/svg+xml,"+function(t){return t.replace(/"/g,"'").replace(/%/g,"%25").replace(/#/g,"%23").replace(//g,"%3E").replace(/\s+/g," ")}(t)}(t)+'")'}let at=(()=>{let t;try{if(t=fetch,"function"==typeof t)return t}catch(t){}})();function ut(t){at=t}function lt(){return at}const ft={prepare:(t,e,n)=>{const i=[],r=function(t,e){const n=Q(t);if(!n)return 0;let i;if(n.maxURL){let t=0;n.resources.forEach(e=>{const n=e;t=Math.max(t,n.length)});const r=e+".json?icons=";i=n.maxURL-t-n.path.length-r.length}else i=0;return i}(t,e),o="icons";let s={type:o,provider:t,prefix:e,icons:[]},c=0;return n.forEach((n,a)=>{c+=n.length+1,c>=r&&a>0&&(i.push(s),s={type:o,provider:t,prefix:e,icons:[]},c=n.length),s.icons.push(n)}),i.push(s),i},send:(t,e,n)=>{if(!at)return void n("abort",424);let i=function(t){if("string"==typeof t){const e=Q(t);if(e)return e.path}return"/"}(e.provider);switch(e.type){case"icons":{const t=e.prefix,n=e.icons.join(",");i+=t+".json?"+new URLSearchParams({icons:n}).toString();break}case"custom":{const t=e.uri;i+="/"===t.slice(0,1)?t.slice(1):t;break}default:return void n("abort",400)}let r=503;at(t+i).then(t=>{const e=t.status;if(200===e)return r=501,t.json();setTimeout(()=>{n(function(t){return 404===t}(e)?"abort":"next",e)})}).then(t=>{"object"==typeof t&&null!==t?setTimeout(()=>{n("success",t)}):setTimeout(()=>{404===t?n("abort",t):n("next",r)})}).catch(()=>{n("next",r)})}};function dt(t,e,n){y(n||"",e).loadIcons=t}function ht(t,e,n){y(n||"",e).loadIcon=t}const pt="data-style";let gt="";function bt(t){gt=t}function vt(t,e){let n=Array.from(t.childNodes).find(t=>t.hasAttribute&&t.hasAttribute(pt));n||(n=document.createElement("style"),n.setAttribute(pt,pt),t.appendChild(n)),n.textContent=":host{display:inline-block;vertical-align:"+(e?"-0.125em":"0")+"}span,svg{display:block;margin:auto}"+gt}const mt={"background-color":"currentColor"},yt={"background-color":"transparent"},xt={image:"var(--svg)",repeat:"no-repeat",size:"100% 100%"},_t={"-webkit-mask":mt,mask:mt,background:yt};for(const t in _t){const e=_t[t];for(const n in xt)e[t+"-"+n]=xt[n]}function wt(t){return t?t+(t.match(/^[-0-9.]+$/)?"px":""):"inherit"}let kt;function At(t){return void 0===kt&&function(){try{kt=window.trustedTypes.createPolicy("iconify",{createHTML:t=>t})}catch(t){kt=null}}(),kt?kt.createHTML(t):t}function jt(t){return Array.from(t.childNodes).find(t=>{const e=t.tagName&&t.tagName.toUpperCase();return"SPAN"===e||"SVG"===e})}function Ot(t,e){const i=e.icon.data,r=e.customisations,o=ot(i,r);r.preserveAspectRatio&&(o.attributes.preserveAspectRatio=r.preserveAspectRatio);const s=e.renderedMode;let c;if("svg"===s)c=function(t){const e=document.createElement("span"),n=t.attributes;let i="";n.width||(i="width: inherit;"),n.height||(i+="height: inherit;"),i&&(n.style=i);const r=st(t.body,n);return e.innerHTML=At(r),e.firstChild}(o);else c=function(t,e,n){const i=document.createElement("span");let r=t.body;-1!==r.indexOf("{this._check()}))}_check(){if(!this._checkQueued)return;this._checkQueued=!1;const t=this._state,e=this.getAttribute("icon");if(e!==t.icon.value)return void this._iconChanged(e);if(!t.rendered||!this._visible)return;const n=this.getAttribute("mode"),i=a(this);t.attrMode===n&&!function(t,e){for(const n in c)if(t[n]!==e[n])return!0;return!1}(t.customisations,i)&&jt(this._shadowRoot)||this._renderIcon(t.icon,i,n)}_iconChanged(t){const e=function(t,e){if("object"==typeof t)return{data:tt(t),value:t};if("string"!=typeof t)return{value:t};if(t.includes("{")){const e=tt(t);if(e)return{data:e,value:t}}const n=l(t,!0,!0);if(!n)return{value:t};const i=A(n);if(void 0!==i||!n.prefix)return{value:t,name:n,data:i};const r=Y([n],()=>e(t,n,A(n)));return{value:t,name:n,loading:r}}(t,(t,e,n)=>{const i=this._state;if(i.rendered||this.getAttribute("icon")!==t)return;const r={value:t,name:e,data:n};r.data?this._gotIconData(r):i.icon=r});e.data?this._gotIconData(e):this._state=Ct(e,this._state.inline,this._state)}_forceRender(){if(!this._visible){const t=jt(this._shadowRoot);return void(t&&this._shadowRoot.removeChild(t))}this._queueCheck()}_gotIconData(t){this._checkQueued=!1,this._renderIcon(t,a(this),this.getAttribute("mode"))}_renderIcon(t,e,n){const i=function(t,e){switch(e){case"svg":case"bg":case"mask":return e}return"style"===e||!et&&-1!==t.indexOf("{const e=t.some(t=>t.isIntersecting);e!==this._visible&&(this._visible=e,this._forceRender())}),this._observer.observe(this)}catch(t){if(this._observer){try{this._observer.disconnect()}catch(t){}this._observer=null}}}stopObserver(){this._observer&&(this._observer.disconnect(),this._observer=null,this._visible=!0,this._connected&&this._forceRender())}};r.forEach(t=>{t in o.prototype||Object.defineProperty(o.prototype,t,{get:function(){return this.getAttribute(t)},set:function(e){null!==e?this.setAttribute(t,e):this.removeAttribute(t)}})});const s=function(){let t;R("",ft),k(!0);try{t=window}catch(t){}if(t){if(void 0!==t.IconifyPreload){const e=t.IconifyPreload,n="Invalid IconifyPreload syntax.";"object"==typeof e&&null!==e&&(e instanceof Array?e:[e]).forEach(t=>{try{("object"!=typeof t||null===t||t instanceof Array||"object"!=typeof t.icons||"string"!=typeof t.prefix||!O(t))&&console.error(n)}catch(t){console.error(n)}})}if(void 0!==t.IconifyProviders){const e=t.IconifyProviders;if("object"==typeof e&&null!==e)for(const t in e){const n="IconifyProviders["+t+"] is invalid.";try{const i=e[t];if("object"!=typeof i||!i||void 0===i.resources)continue;z(t,i)||console.error(n)}catch(t){console.error(n)}}}}return{iconLoaded:C,getIcon:I,listIcons:_,addIcon:j,addCollection:O,calculateSize:rt,buildIcon:ot,iconToHTML:st,svgToURL:ct,loadIcons:Y,loadIcon:Z,addAPIProvider:z,setCustomIconLoader:ht,setCustomIconsLoader:dt,appendCustomStyle:bt,_api:{getAPIConfig:Q,setAPIModule:R,sendAPIQuery:B,setFetch:ut,getFetch:lt,listAPIProviders:q}}}();for(const t in s)o[t]=o.prototype[t]=s[t];e.define(t,o)}()}();
diff --git a/docs/_extensions/mcanouil/iconify/iconify.lua b/docs/_extensions/mcanouil/iconify/iconify.lua
new file mode 100644
index 0000000..000c659
--- /dev/null
+++ b/docs/_extensions/mcanouil/iconify/iconify.lua
@@ -0,0 +1,478 @@
+--- @module iconify
+--- @license MIT
+--- @copyright 2026 Mickaël Canouil
+--- @author Mickaël Canouil
+
+--- Extension name constant
+local EXTENSION_NAME = "iconify"
+
+--- Load modules
+local str = require(quarto.utils.resolve_path('_modules/string.lua'):gsub('%.lua$', ''))
+local log = require(quarto.utils.resolve_path('_modules/logging.lua'):gsub('%.lua$', ''))
+local meta_mod = require(quarto.utils.resolve_path('_modules/metadata.lua'):gsub('%.lua$', ''))
+local typst = require(quarto.utils.resolve_path('_modules/typst.lua'):gsub('%.lua$', ''))
+
+--- Per-key deprecation warning tracker. Each deprecated metadata key warns
+--- at least once per render rather than once total. The companion filter
+--- (`iconify-filter.lua`) is responsible for any per-document state reset
+--- in batch renders; this shortcode keeps the tracker local to its own
+--- module instance.
+--- @type table
+local deprecation_warned_keys = {}
+
+--- Ensures the Typst SVG cache is pruned at most once per render. The cleanup
+--- runs from the shortcode (not the filter) because contributed filters run
+--- before shortcodes expand, so the cache does not yet exist at filter time.
+--- @type boolean
+local typst_cleanup_done = false
+
+--- Ensure Iconify HTML dependencies are included.
+--- @return nil
+local function ensure_html_deps()
+ quarto.doc.add_html_dependency({
+ name = 'iconify',
+ version = '3.0.0',
+ scripts = { 'iconify-icon.min.js' }
+ })
+end
+
+--- Ensure the fallback runtime stylesheet and script are loaded.
+--- The runtime monitors each `` and reveals an author-provided
+--- fallback span if the icon fails to load (e.g. unknown icon name, offline,
+--- or CDN unreachable).
+--- @return nil
+local function ensure_fallback_runtime()
+ quarto.doc.add_html_dependency({
+ name = 'iconify-fallback',
+ version = '1.0.0',
+ scripts = { 'iconify-fallback.js' },
+ stylesheets = { 'iconify-fallback.css' }
+ })
+end
+
+--- Check for deprecated top-level iconify configuration and emit a warning
+--- the first time each key is accessed during a render.
+--- @param meta table Document metadata table
+--- @param key string The configuration key being accessed
+--- @return string|nil The value from deprecated config, or nil if not found
+local function check_deprecated_config(meta, key)
+ --- @type boolean
+ local already_warned = deprecation_warned_keys[key] or false
+ local value, updated = meta_mod.check_deprecated_config(meta, 'iconify', key, already_warned)
+ deprecation_warned_keys[key] = updated
+ return value
+end
+
+--- @type table Known size keywords mapped to CSS font-size values
+local SIZE_KEYWORDS = {
+ ['tiny'] = '0.5em',
+ ['scriptsize'] = '0.7em',
+ ['footnotesize'] = '0.8em',
+ ['small'] = '0.9em',
+ ['normalsize'] = '1em',
+ ['large'] = '1.2em',
+ ['Large'] = '1.5em',
+ ['LARGE'] = '1.75em',
+ ['huge'] = '2em',
+ ['Huge'] = '2.5em',
+ ['1x'] = '1em',
+ ['2x'] = '2em',
+ ['3x'] = '3em',
+ ['4x'] = '4em',
+ ['5x'] = '5em',
+ ['6x'] = '6em',
+ ['7x'] = '7em',
+ ['8x'] = '8em',
+ ['9x'] = '9em',
+ ['10x'] = '10em',
+ ['2xs'] = '0.625em',
+ ['xs'] = '0.75em',
+ ['sm'] = '0.875em',
+ ['lg'] = '1.25em',
+ ['xl'] = '1.5em',
+ ['2xl'] = '2em'
+}
+
+--- Allowed CSS length units. `%` is included for completeness even though it
+--- is rarely meaningful for font-size.
+--- @type table
+local CSS_LENGTH_UNITS = {
+ px = true, em = true, rem = true, pt = true, pc = true, ex = true,
+ ch = true, cm = true, mm = true, ['in'] = true, vh = true, vw = true,
+ vmin = true, vmax = true, ['%'] = true
+}
+
+--- Check whether a size value is a syntactically valid CSS length.
+--- Accepts an optional leading sign, a number (integer or decimal), and a
+--- supported unit. Returns false for unknown units or malformed values.
+--- @param value string
+--- @return boolean
+local function is_css_length(value)
+ --- @type string|nil, string|nil
+ local number_part, unit = value:match('^([-+]?%d*%.?%d+)(.*)$')
+ if not number_part or number_part == '' or number_part == '.' then
+ return false
+ end
+ if unit == nil or unit == '' then
+ -- Bare numbers are not valid CSS lengths (except zero).
+ return value == '0'
+ end
+ return CSS_LENGTH_UNITS[unit] == true
+end
+
+--- Resolve a size value to a raw CSS length, mapping known keywords.
+--- Returns an empty string when the value is empty or invalid, after emitting
+--- a warning for the invalid case. This honours the README contract that
+--- "When the size is invalid, no size changes are made."
+--- @param size string|nil
+--- @return string
+local function resolve_size_value(size)
+ if str.is_empty(size) then
+ return ''
+ end
+ --- @type string|nil
+ local mapped = SIZE_KEYWORDS[size]
+ if mapped ~= nil then
+ return mapped
+ end
+ if is_css_length(size) then
+ return size
+ end
+ log.log_warning(
+ EXTENSION_NAME,
+ 'Ignoring invalid size value "' .. size .. '". ' ..
+ 'Use a CSS length (e.g. "1.5em", "32px"), a literal size like "2x", ' ..
+ 'or a LaTeX-style keyword like "Huge". Size left unchanged.'
+ )
+ return ''
+end
+
+--- Validate and convert a size value to a CSS font-size declaration.
+--- @param size string|nil
+--- @return string
+local function resolve_size(size)
+ --- @type string
+ local value = resolve_size_value(size)
+ if value == '' then
+ return ''
+ end
+ return 'font-size: ' .. value .. ';'
+end
+
+--- Validate an Iconify icon or set name.
+--- Matches the pattern enforced by the Iconify Web Component itself
+--- (`/^[a-z0-9]+(-[a-z0-9]+)*$/`): lowercase letters or digits separated
+--- by single hyphens, with no leading or trailing hyphen.
+--- @param value string
+--- @return boolean
+local function is_valid_iconify_name(value)
+ if value == nil or value == '' then return false end
+ if value:find('%-%-') then return false end
+ if value:sub(1, 1) == '-' or value:sub(-1) == '-' then return false end
+ return value:match('^[a-z0-9-]+$') ~= nil
+end
+
+--- Get an iconify option from arguments or metadata.
+--- Resolution order: positional/named kwargs first, then nested
+--- `extensions.iconify.`, then the deprecated top-level `iconify.`
+--- (with a per-key deprecation warning).
+--- @param x string The option name to retrieve
+--- @param arg table Arguments table containing options
+--- @param meta table Document metadata table
+--- @return string The option value as a string
+local function get_iconify_options(x, arg, meta)
+ --- @type string
+ local arg_value = str.stringify(arg[x])
+
+ if not str.is_empty(arg_value) then
+ return arg_value
+ end
+
+ local meta_value = meta_mod.get_metadata_value(meta, 'iconify', x)
+ if not str.is_empty(meta_value) then
+ return meta_value
+ end
+
+ local deprecated_value = check_deprecated_config(meta, x)
+ if deprecated_value then
+ return deprecated_value
+ end
+
+ return arg_value
+end
+
+--- Render an Iconify icon as a Typst `#image`, delegating retrieval and
+--- caching to the typst module. Geometric and colour transforms are baked
+--- into the fetched SVG via the Iconify API; size is applied as the Typst
+--- image height so it scales with the surrounding text.
+--- @param icon string Resolved icon name
+--- @param set string Resolved icon set
+--- @param default_label string Fallback accessibility label
+--- @param kwargs table Key-value options for the icon
+--- @param meta table Document metadata
+--- @return any Pandoc RawInline (Typst), Str (fallback) or Null
+local function render_typst(icon, set, default_label, kwargs, meta)
+ --- @type string
+ local size_raw = resolve_size_value(get_iconify_options('size', kwargs, meta))
+ --- @type string|nil
+ local size_value = typst.typst_length(size_raw)
+ if size_raw ~= '' and size_value == nil then
+ log.log_warning(
+ EXTENSION_NAME,
+ 'Size "' .. size_raw .. '" uses a unit Typst does not support; ' ..
+ 'falling back to 1em for Typst output. ' ..
+ 'Use em, pt, cm, mm, in or % for Typst sizing.'
+ )
+ end
+
+ --- Colour: explicit `color` option, otherwise parsed from a `style` value.
+ --- @type string
+ local colour = get_iconify_options('color', kwargs, meta)
+ if str.is_empty(colour) then
+ --- @type string
+ local style = get_iconify_options('style', kwargs, meta)
+ if not str.is_empty(style) then
+ colour = str.trim(style:match('color%s*:%s*([^;]+)') or '')
+ end
+ end
+
+ --- @type table
+ local params = {}
+ if not str.is_empty(colour) then params.color = colour end
+ --- @type string
+ local flip = get_iconify_options('flip', kwargs, meta)
+ if not str.is_empty(flip) then params.flip = flip end
+ --- @type string
+ local rotate = get_iconify_options('rotate', kwargs, meta)
+ if not str.is_empty(rotate) then params.rotate = rotate end
+
+ --- @type string
+ local alt = str.stringify(kwargs['label'])
+ if str.is_empty(alt) then alt = str.stringify(kwargs['title']) end
+ if str.is_empty(alt) then alt = default_label end
+
+ --- @type string
+ local inline = get_iconify_options('inline', kwargs, meta)
+
+ --- @type any
+ local result = typst.render({
+ set = set,
+ icon = icon,
+ query = typst.build_query(params),
+ size_value = size_value,
+ inline = str.is_empty(inline) or inline ~= 'false',
+ alt = alt,
+ fallback = get_iconify_options('fallback', kwargs, meta),
+ meta = meta
+ })
+
+ -- Prune the cache once per render, after at least one icon has populated it.
+ if not typst_cleanup_done then
+ typst_cleanup_done = true
+ typst.cleanup(meta)
+ end
+
+ return result
+end
+
+--- Render an Iconify icon as a Pandoc RawInline for HTML output.
+--- @param args table Icon arguments (icon set and name)
+--- @param kwargs table Key-value options for the icon
+--- @param meta table Document metadata
+--- @return any Pandoc RawInline for HTML or Pandoc Null for other formats
+local function iconify(args, kwargs, meta)
+ -- HTML (excluding epub which will not host the Web Component) renders the
+ -- Web Component; Typst renders a cached SVG. Every other format renders
+ -- nothing.
+ --- @type boolean
+ local is_html = quarto.doc.is_format('html:js')
+ --- @type boolean
+ local is_typst = quarto.doc.is_format('typst')
+ if not is_html and not is_typst then
+ return pandoc.Null()
+ end
+
+ --- @type string
+ local icon = str.stringify(args[1])
+ --- @type string
+ local set = 'octicon'
+
+ -- Resolve the default icon set, preferring the nested metadata structure.
+ local meta_set = meta_mod.get_metadata_value(meta, 'iconify', 'set')
+ if not str.is_empty(meta_set) then
+ set = meta_set
+ else
+ local deprecated_set = check_deprecated_config(meta, 'set')
+ if deprecated_set then
+ set = deprecated_set
+ end
+ end
+
+ if #args > 1 and string.find(str.stringify(args[2]), ':') then
+ log.log_warning(
+ EXTENSION_NAME,
+ 'Use "set:icon" or "set icon" syntax, not both! ' ..
+ 'Using "set:icon" syntax and discarding first argument!'
+ )
+ icon = str.stringify(args[2])
+ end
+
+ if string.find(icon, ':') then
+ set = string.sub(icon, 1, string.find(icon, ':') - 1)
+ icon = string.sub(icon, string.find(icon, ':') + 1)
+ elseif #args > 1 then
+ set = icon
+ icon = str.stringify(args[2])
+ end
+
+ -- Validate icon and set names. Invalid names still render so that authors
+ -- can see what went wrong in the output, but a warning is emitted.
+ if not is_valid_iconify_name(set) then
+ log.log_warning(
+ EXTENSION_NAME,
+ 'Icon set name "' .. set .. '" is invalid. ' ..
+ 'Use lowercase letters, digits and single hyphens (e.g. "fa6-brands"). ' ..
+ 'The icon will likely fail to load.'
+ )
+ end
+ if not is_valid_iconify_name(icon) then
+ log.log_warning(
+ EXTENSION_NAME,
+ 'Icon name "' .. icon .. '" is invalid. ' ..
+ 'Use lowercase letters, digits and single hyphens (e.g. "exploding-head"). ' ..
+ 'The icon will likely fail to load.'
+ )
+ end
+
+ --- @type string
+ local default_label = 'Icon ' .. icon .. ' from ' .. set .. ' Iconify.design set.'
+
+ if is_typst then
+ return render_typst(icon, set, default_label, kwargs, meta)
+ end
+
+ ensure_html_deps()
+
+ --- @type string
+ local attributes = ' icon="' .. set .. ':' .. icon .. '"'
+
+ --- @type string
+ local size = resolve_size(get_iconify_options('size', kwargs, meta))
+ --- @type string
+ local style = get_iconify_options('style', kwargs, meta)
+
+ if str.is_empty(style) and not str.is_empty(size) then
+ attributes = attributes .. ' style="' .. size .. '"'
+ elseif not str.is_empty(style) and not str.is_empty(size) then
+ attributes = attributes .. ' style="' .. style .. ';' .. size .. '"'
+ elseif not str.is_empty(style) then
+ attributes = attributes .. ' style="' .. style .. '"'
+ end
+
+ --- @type string
+ local aria_label = str.stringify(kwargs['label'])
+ if str.is_empty(aria_label) then
+ aria_label = ' aria-label="' .. default_label .. '"'
+ else
+ aria_label = ' aria-label="' .. aria_label .. '"'
+ end
+
+ --- @type string
+ local title = str.stringify(kwargs['title'])
+ if str.is_empty(title) then
+ title = ' title="' .. default_label .. '"'
+ else
+ title = ' title="' .. title .. '"'
+ end
+
+ attributes = attributes .. aria_label .. title
+
+ --- @type string
+ local width = get_iconify_options('width', kwargs, meta)
+ if not str.is_empty(width) and str.is_empty(size) then
+ attributes = attributes .. ' width="' .. width .. '"'
+ end
+ --- @type string
+ local height = get_iconify_options('height', kwargs, meta)
+ if not str.is_empty(height) and str.is_empty(size) then
+ attributes = attributes .. ' height="' .. height .. '"'
+ end
+ --- @type string
+ local flip = get_iconify_options('flip', kwargs, meta)
+ if not str.is_empty(flip) then
+ attributes = attributes .. ' flip="' .. flip .. '"'
+ end
+ --- @type string
+ local rotate = get_iconify_options('rotate', kwargs, meta)
+ if not str.is_empty(rotate) then
+ attributes = attributes .. ' rotate="' .. rotate .. '"'
+ end
+
+ --- @type string
+ local inline = get_iconify_options('inline', kwargs, meta)
+ if str.is_empty(inline) or inline ~= 'false' then
+ attributes = ' inline ' .. attributes
+ end
+
+ --- @type string
+ local mode = get_iconify_options('mode', kwargs, meta)
+ --- @type table
+ local valid_modes = { svg = true, style = true, bg = true, mask = true }
+ if not str.is_empty(mode) and valid_modes[mode] then
+ attributes = attributes .. ' mode="' .. mode .. '"'
+ end
+
+ --- @type string
+ local fallback = get_iconify_options('fallback', kwargs, meta)
+
+ if not str.is_empty(fallback) then
+ ensure_fallback_runtime()
+ return pandoc.RawInline(
+ 'html',
+ '' ..
+ '' ..
+ '' .. fallback .. '' ..
+ ''
+ )
+ end
+
+ return pandoc.RawInline(
+ 'html',
+ ''
+ )
+end
+
+--- Render Quarto icon using the iconify function with preset styling.
+--- @param args table Icon arguments (ignored as we're using a preset icon)
+--- @param kwargs table|nil Key-value options that might override default styling
+--- @param meta table Document metadata
+--- @return any Pandoc RawInline for HTML or Pandoc Null for other formats
+local function iconify_quarto(args, kwargs, meta)
+ --- @type table
+ local quarto_args = { 'simple-icons:quarto' }
+ --- @type table
+ local quarto_kwargs = kwargs or {}
+ quarto_kwargs['label'] = 'Quarto icon'
+ quarto_kwargs['title'] = 'Quarto icon'
+ --- @type string
+ local quarto_colour = 'color:#74aadb;'
+
+ if not str.is_empty(quarto_kwargs['style']) then
+ --- @type string
+ local style = str.stringify(quarto_kwargs['style'])
+ if string.match(style, 'color:[^;]+;') then
+ quarto_kwargs['style'] = string.gsub(style, 'color:[^;]+;', quarto_colour)
+ else
+ quarto_kwargs['style'] = quarto_colour .. style
+ end
+ else
+ quarto_kwargs['style'] = quarto_colour
+ end
+ return iconify(quarto_args, quarto_kwargs, meta)
+end
+
+--- @type table
+return {
+ ['iconify'] = iconify,
+ ['quarto'] = iconify_quarto
+}
diff --git a/docs/_extensions/mcanouil/pastel/LICENSE b/docs/_extensions/mcanouil/pastel/LICENSE
new file mode 100644
index 0000000..4b53bb8
--- /dev/null
+++ b/docs/_extensions/mcanouil/pastel/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mickaël Canouil
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/docs/_extensions/mcanouil/pastel/_extension.yml b/docs/_extensions/mcanouil/pastel/_extension.yml
new file mode 100644
index 0000000..4b5edc8
--- /dev/null
+++ b/docs/_extensions/mcanouil/pastel/_extension.yml
@@ -0,0 +1,10 @@
+title: Pastel
+author: Mickaël Canouil
+version: 0.1.0
+quarto-required: '>=1.10.18'
+source: mcanouil/quarto-pastel@0.1.0
+source-type: registry
+contributes:
+ metadata:
+ project:
+ brand: brand.yml
diff --git a/docs/_extensions/mcanouil/pastel/_schema.yml b/docs/_extensions/mcanouil/pastel/_schema.yml
new file mode 100644
index 0000000..b5db8f8
--- /dev/null
+++ b/docs/_extensions/mcanouil/pastel/_schema.yml
@@ -0,0 +1,14 @@
+# _schema.yml for the "pastel" brand extension.
+# Describes the extension for IDE tooling and runtime validation.
+
+$schema: https://m.canouil.dev/quarto-wizard/assets/schema/v2/extension-schema.json
+
+# The extension takes no YAML options. It is consumed as a brand file plus a
+# stylesheet, wired in through `brand:` and `format..theme`.
+#
+# The two knobs it does expose are Sass defaults, overridden by setting them in
+# a project stylesheet loaded before pastel.scss:
+#
+# $pastel-tint-alpha: 0.2; // strength of the pastel washes
+# $pastel-grain-opacity: 0; // 0 turns the paper tooth off
+options: {}
diff --git a/docs/_extensions/mcanouil/pastel/assets/grain.svg b/docs/_extensions/mcanouil/pastel/assets/grain.svg
new file mode 100644
index 0000000..b22e3ba
--- /dev/null
+++ b/docs/_extensions/mcanouil/pastel/assets/grain.svg
@@ -0,0 +1,25 @@
+
diff --git a/docs/_extensions/mcanouil/pastel/brand.yml b/docs/_extensions/mcanouil/pastel/brand.yml
new file mode 100644
index 0000000..fa68f86
--- /dev/null
+++ b/docs/_extensions/mcanouil/pastel/brand.yml
@@ -0,0 +1,129 @@
+# Pastel - Shared Brand For The Quarto Extension Documentation Websites
+# A box of soft pastels: colourful and playful, chalky and muted.
+#
+# @license MIT
+# @copyright 2026 Mickaël Canouil
+# @author Mickaël Canouil
+#
+# Six sticks rather than two or three, so the family reads as cheerful, but each
+# one is greyed back to roughly 20 to 33 percent saturation, so it reads as
+# chalk rather than as candy. That is what a real box of soft pastels looks
+# like: a wide, happy range of quiet colours.
+#
+# `coral-deep` is #A04238 rather than a lighter red: on the tinted table of
+# contents panel and the inline-code blush, #B04A40 fell to 4.54 and 4.45, so
+# inline code failed AA outright. Lightening those two surfaces instead was
+# rejected, because at the lightness required the inline surface disappears
+# against the paper.
+#
+# A pastel behaves differently depending on what it is drawn on, and the palette
+# uses both behaviours:
+#
+# - On light paper the pastel is a tint, and a deeper mix of the same hue
+# carries text and links.
+# - On the dark column and in dark mode the pastel is the ink.
+#
+# That makes the dark scheme the more colourful one, which is what gives the
+# family its look.
+#
+# Every pastel measures between 1.20 and 1.65 against the light paper, well
+# below even the 3:1 threshold for interface elements. They are decoration only
+# in the light scheme: fills and tints, never text, and never a border that has
+# to be seen for the page to work. Each has a `-deep` companion carrying text at
+# 4.5:1 or better, and a `-chalk` companion for the dark scheme.
+#
+# Palette names deliberately avoid a bare trailing -light or -dark: brand reads
+# those as its own colour-scheme keys, so a name such as `ink-dark` is mistaken
+# for a scheme selector, which silently swaps the two backgrounds.
+#
+# Fonts are deliberately absent. The sites inherit Quarto's defaults rather
+# than fetching a typeface from a third party.
+
+meta:
+ name:
+ full: Pastel
+ short: Pastel
+ link:
+ home: https://m.canouil.dev/quarto-pastel/
+
+color:
+ palette:
+ # Grounds. The paper is toned rather than white, so the page reads warm
+ # before any accent lands on it.
+ paper: "#F6F1E6"
+ ink: "#2B2A26"
+ night: "#191C1F"
+ mist: "#E7EAEC"
+
+ # Surfaces derived from the grounds and the sticks. Each sits between 1.05
+ # and 1.28 against its ground: visible as a panel without becoming a block
+ # of colour.
+ #
+ # The dark variants are suffixed -night, not -dark: brand reads a trailing
+ # -dark as its own colour-scheme key, as the note above records.
+ panel: "#ECECE6" # sky at 12% over paper, for the table of contents
+ panel-night: "#293036"
+ code-surface: "#EFEAE0"
+ code-surface-night: "#22262A"
+ blush: "#F3E7E2" # inline code
+ blush-night: "#2A2325"
+ header-tint: "#F3EBD6" # table header, lemon
+ header-tint-night: "#262521"
+
+ # The sticks. Each is a pastel for tints, a deep hue for light-scheme text,
+ # and a chalk variant for dark-scheme text.
+ mint: "#A9DCC9"
+ mint-deep: "#1C7059"
+ mint-chalk: "#9FD9C4"
+
+ sky: "#A6C9E2"
+ sky-deep: "#1D6790"
+ sky-chalk: "#9CC6E2"
+
+ lemon: "#EFDDA0"
+ lemon-deep: "#77620F"
+ lemon-chalk: "#E7D598"
+
+ coral: "#EDAFA8"
+ coral-deep: "#A04238"
+ coral-chalk: "#EBA9A1"
+
+ peach: "#EFC6A3"
+ peach-deep: "#8E5720"
+ peach-chalk: "#EAC09B"
+
+ sage: "#C3D3A8"
+ sage-deep: "#566B2E"
+ sage-chalk: "#BCCEA0"
+
+ background:
+ light: paper
+ dark: night
+ foreground:
+ light: ink
+ dark: mist
+
+ # Mint carries primary: it is the most distinctive of the six and, unlike
+ # coral or peach, a link drawn in it is never mistaken for a warning or an
+ # error in the extension output these sites exist to demonstrate.
+ primary:
+ light: mint-deep
+ dark: mint-chalk
+ secondary:
+ light: sky-deep
+ dark: sky-chalk
+ tertiary:
+ light: lemon-deep
+ dark: lemon-chalk
+ success:
+ light: sage-deep
+ dark: sage-chalk
+ info:
+ light: sky-deep
+ dark: sky-chalk
+ warning:
+ light: peach-deep
+ dark: peach-chalk
+ danger:
+ light: coral-deep
+ dark: coral-chalk
diff --git a/docs/_extensions/mcanouil/pastel/pastel.scss b/docs/_extensions/mcanouil/pastel/pastel.scss
new file mode 100644
index 0000000..8a265db
--- /dev/null
+++ b/docs/_extensions/mcanouil/pastel/pastel.scss
@@ -0,0 +1,337 @@
+/*-- scss:functions --*/
+
+// atelier defines the same helper, but a stylesheet cannot rely on another
+// bundle's functions being in scope, so it is redefined here. brand injects a
+// different $body-bg / $body-color into the light and dark compiles, so this
+// resolves to the correct per-scheme surface from one source of truth.
+@function pastel-mix($weight) {
+ @return mix($body-bg, $body-color, $weight);
+}
+
+/*-- scss:defaults --*/
+
+// The pastels are decoration only in the light scheme: they measure 1.25 to
+// 1.72 against the paper, below even the 3:1 threshold for interface
+// elements. Tints use them at low alpha; every edge is a pastel-mix() rule or
+// a deep-pigment line that is actually perceivable.
+$pastel-tint-alpha: 0.28 !default;
+
+// 0.07, not the 0.045 first tried: on toned paper the lower value is invisible.
+$pastel-grain-opacity: 0.07 !default;
+
+/*-- scss:rules --*/
+
+// ===========================================================================
+// SCHEME SELECTION
+// ===========================================================================
+// Quarto compiles this file twice, once per colour scheme, and brand injects a
+// different $body-bg into each. Comparing its lightness is therefore how a
+// single stylesheet picks the deep hue for light paper and the chalk hue for
+// the dark ground, at compile time, with no duplicated blocks.
+$pastel-light: lightness($body-bg) > 50%;
+
+@function pastel-ink($deep, $chalk) {
+ @return if($pastel-light, $deep, $chalk);
+}
+
+// A tint of a stick over the page background. The dark scheme takes a lighter
+// hand: mixing a pale pastel into a dark ground lifts far more than the same
+// weight does on paper, so an equal weight would make the dark surfaces shout.
+@function pastel-tint($stick, $light-weight, $dark-weight: null) {
+ $w: if($pastel-light, $light-weight, if($dark-weight, $dark-weight, $light-weight));
+ @return mix($stick, $body-bg, $w);
+}
+
+$pastel-h1: pastel-ink($brand-mint-deep, $brand-mint-chalk);
+$pastel-h2: pastel-ink($brand-sky-deep, $brand-sky-chalk);
+$pastel-h3: pastel-ink($brand-peach-deep, $brand-peach-chalk);
+$pastel-accent: pastel-ink($brand-coral-deep, $brand-coral-chalk);
+$pastel-link: pastel-ink($brand-mint-deep, $brand-mint-chalk);
+
+// The table of contents panel, a sky tint of the page in each scheme. It reads
+// as a panel without becoming a block of colour: 1.05 against the paper and
+// 1.30 against the night.
+$pastel-panel: pastel-tint($brand-sky, 12%);
+$pastel-blush: pastel-tint(pastel-ink($brand-coral, $brand-coral-chalk), 18%, 8%);
+$pastel-header: pastel-tint(pastel-ink($brand-lemon, $brand-lemon-chalk), 22%, 8%);
+
+// ===========================================================================
+// HEADINGS
+// ===========================================================================
+// Quarto leaves every heading the same colour as body text, so a page has no
+// visual hierarchy beyond size. Three of the six sticks carry it instead.
+h1, .h1, #title-block-header .title {
+ color: $pastel-h1;
+}
+
+h2, .h2 {
+ color: $pastel-h2;
+ border-bottom-color: pastel-mix(85%);
+}
+
+h3, .h3, h4, .h4 {
+ color: $pastel-h3;
+}
+
+h5, .h5, h6, .h6 {
+ color: pastel-mix(35%);
+}
+
+// ===========================================================================
+// LINKS
+// ===========================================================================
+// Quarto ships no hover treatment at all, so a link gives no feedback.
+a {
+ color: $pastel-link;
+
+ &:hover,
+ &:focus-visible {
+ color: $pastel-accent;
+ text-decoration-thickness: 2px;
+ text-underline-offset: 2px;
+ }
+}
+
+// `strong` inherits 0.6 alpha from the theme, which makes emphasis fainter
+// than the text it is meant to emphasise. Put it back at full strength.
+strong, b {
+ color: $body-color;
+ font-weight: 700;
+}
+
+// ===========================================================================
+// CODE
+// ===========================================================================
+// Code blocks are left alone. The `code-window` extension decorates them, and
+// atelier already gives them a scheme-correct surface, so a third treatment
+// here would only fight both. Only inline code is styled.
+//
+// Everything here is anchored on #quarto-document-content. Quarto loads its own
+// stylesheet after the theme bundle, and atelier's rules sit later in the bundle
+// than this file, so at equal specificity both win on order alone. An id
+// selector settles it outright, and scoping to the article is honest about
+// intent: these rules are for page content, not for chrome.
+#quarto-document-content {
+ // Inline code sits in running prose, so it takes the quietest tint of all
+ // and the accent hue, which keeps it distinct from a link.
+ code:not(.sourceCode) {
+ color: $pastel-accent;
+ background-color: $pastel-blush;
+ padding: 0.1em 0.35em;
+ border-radius: 0.25rem;
+ }
+
+ // Quarto styles code inside prose with its own, more specific selectors.
+ p code.sourceCode,
+ li code.sourceCode,
+ td code.sourceCode {
+ background-color: $pastel-blush;
+ }
+
+ // Bootstrap 5.3 paints every cell through var(--bs-table-bg), so the variable
+ // is re-pointed here rather than fighting `.table > :not(caption) > * > *`.
+ // Quarto then resets the header cell background to transparent further down
+ // its own stylesheet, so the colour is also set outright on the cell.
+ .table > thead {
+ --bs-table-bg: #{$pastel-header};
+
+ > tr > th {
+ background-color: $pastel-header;
+ }
+ }
+
+ .table > :not(caption) > * > * {
+ border-bottom-color: pastel-mix(85%);
+ }
+}
+
+// ===========================================================================
+// TABLE OF CONTENTS
+// ===========================================================================
+// The active entry was previously identical to every other entry, so the panel
+// never showed where the reader was.
+//
+// The contents render inside #quarto-margin-sidebar, which carries Quarto's
+// `sidebar` class and so inherits $sidebar-fg. atelier sets that per colour
+// scheme, so the entries are already the right ink for the page and the panel
+// is a tint of the page like every other surface here.
+//
+// One id is enough for the panel and the rail: Quarto's competing rule carries
+// two classes and three elements, which an id outranks. The hovered and active
+// entries are pinned with !important, which no amount of specificity beats, so
+// those two declarations match it.
+#quarto-margin-sidebar {
+ nav[role="doc-toc"] {
+ background-color: $pastel-panel;
+ border-radius: $border-radius;
+ padding: 0.75rem 0.5rem;
+ }
+
+ // `.toc-actions` (Edit this page, Report an issue) sits inside this same nav,
+ // so it is excluded: those are Quarto's own controls, not contents entries,
+ // and they keep their own styling.
+ //
+ // Colour and the rail only. Quarto indents each level of the contents through
+ // a ladder of descendant selectors, from
+ // `nav[role=doc-toc] ul>li>ul>li>a` at 1.2em down to 6em, and the id above
+ // outranks every rung of it. Setting `padding-left` here therefore flattens
+ // the whole tree to one indent, so the padding is left alone.
+ nav[role="doc-toc"] a:not(.toc-action) {
+ opacity: 0.8;
+ border-left: 2px solid $pastel-link;
+
+ &:hover {
+ opacity: 1;
+ color: $pastel-link !important;
+ }
+
+ &.active {
+ opacity: 1;
+ color: $pastel-accent !important;
+ border-left-color: $pastel-accent;
+ font-weight: 600;
+ }
+ }
+}
+
+// ===========================================================================
+// THE CHROME
+// ===========================================================================
+// Nothing. From atelier 0.9.0 the navbar, the page footer, and a docked sidebar
+// are one chrome derived from the brand: a tint of the page in each scheme,
+// with the brand primary as its accent, both inks lifted by theme-contrast()
+// if they fall under AA. That is already this palette.
+//
+// Before 0.9.0 the chrome was pinned dark in both schemes and this file carried
+// fourteen --atelier-navbar-* and --atelier-sidebar-* declarations to re-point
+// it. Overriding the tokens is the wrong lever anyway: Quarto bakes the chrome
+// foreground into the reader-mode and collapsed-navbar glyphs and contrasts the
+// sidebar link colours against $sidebar-bg, none of which CSS can reach. Set
+// $atelier-chrome and the pinned palettes in a defaults block if a repository
+// ever needs to pin the bars again.
+
+// ===========================================================================
+// PAPER TOOTH
+// ===========================================================================
+// A fixed overlay rather than a background-image on `body`: it then does not
+// scroll with the content, does not repaint on every scroll step, and cannot
+// be painted over by a child that sets its own background.
+//
+// The texture is inlined as a data URI rather than referenced from
+// assets/grain.svg. Quarto resolves a url() in a theme file against the project
+// that consumes it, not against the extension that ships it, so a relative path
+// is looked for in the site's own assets/ and the render fails. Inlining also
+// costs no extra request, and the source stays readable in assets/grain.svg.
+//
+// Fractal noise with `stitchTiles` gives real paper tooth with a seam-free
+// tile; the colour matrix drops it to grey and the transfer function flattens
+// it to a low-alpha darkening, so one texture serves both colour schemes.
+body::before {
+ content: "";
+ position: fixed;
+ inset: 0;
+ z-index: -1;
+ pointer-events: none;
+ opacity: $pastel-grain-opacity;
+ background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='160' height='160' viewBox='0 0 160 160'%3E%3Cfilter id='t' x='0' y='0' width='100%25' height='100%25'%3E%3CfeTurbulence type='fractalNoise' baseFrequency='0.9' numOctaves='4' stitchTiles='stitch' result='n'/%3E%3CfeColorMatrix in='n' type='saturate' values='0' result='g'/%3E%3CfeComponentTransfer in='g'%3E%3CfeFuncA type='linear' slope='0.55' intercept='-0.18'/%3E%3C/feComponentTransfer%3E%3C/filter%3E%3Crect width='160' height='160' filter='url%28%23t%29'/%3E%3C/svg%3E");
+ background-repeat: repeat;
+ background-size: 160px 160px;
+}
+
+// The texture is decorative, and a reader who has asked for less motion and
+// less visual noise should not have to see it.
+@media (prefers-reduced-transparency: reduce) {
+ body::before {
+ display: none;
+ }
+}
+
+// ===========================================================================
+// TINTS
+// ===========================================================================
+// Callouts keep Quarto's own left edge, which carries the deep pigment, and
+// gain a pastel wash behind the body. The wash is never the only signal.
+$pastel-callouts:
+ ("note", $brand-sky, $brand-sky-deep),
+ ("tip", $brand-mint, $brand-mint-deep),
+ ("important", $brand-coral, $brand-coral-deep),
+ ("caution", $brand-lemon, $brand-lemon-deep),
+ ("warning", $brand-peach, $brand-peach-deep);
+
+// The header wash sits on top of the body wash, so the two compound, and the
+// same multiplier lifts a dark ground far more than a light one: at 1.4 the
+// lemon header resolved to rgb(145, 137, 104), leaving mist text at 2.92
+// against it. The dark scheme therefore takes a lighter hand here too, which
+// puts the worst of the five at 4.81.
+$pastel-callout-header-alpha: if(
+ $pastel-light,
+ $pastel-tint-alpha * 1.4,
+ $pastel-tint-alpha * 0.5
+);
+
+@each $name, $pastel, $deep in $pastel-callouts {
+ .callout.callout-style-default.callout-#{$name} {
+ background-color: rgba($pastel, $pastel-tint-alpha);
+ border-left-color: $deep;
+
+ .callout-header {
+ background-color: rgba($pastel, $pastel-callout-header-alpha);
+ }
+ }
+}
+
+// Striped tables take the lightest possible mint wash. The rule between rows
+// stays a pastel-mix() edge, so the table is still readable if the tint is not.
+//
+// Bootstrap 5.3 resolves the stripe through --bs-table-striped-bg, which
+// .table-striped then assigns to --bs-table-bg-type. Setting the older
+// --bs-table-accent-bg has no effect and the stripe silently stays transparent.
+.table.table-striped {
+ --bs-table-striped-bg: #{rgba($brand-mint, 0.16)};
+ --bs-table-striped-color: inherit;
+}
+
+.table > :not(caption) > * > * {
+ border-bottom-color: pastel-mix(85%);
+}
+
+// Tabset panels sit on the same wash as a note callout, so a page that mixes
+// the two does not look like it uses two different surfaces.
+.panel-tabset > .tab-content {
+ background-color: rgba($brand-sky, $pastel-tint-alpha * 0.5);
+}
+
+// ===========================================================================
+// CHALK EDGES
+// ===========================================================================
+// A pastel line alone is invisible on the light paper, so shapes keep a
+// pastel-mix() edge and the colour goes into the fill instead.
+.callout.callout-style-default,
+.panel-tabset > .tab-content {
+ border-radius: $border-radius;
+}
+
+blockquote.blockquote {
+ border-left: 3px solid $brand-mint;
+ background-color: rgba($brand-mint, $pastel-tint-alpha * 0.45);
+ padding: 0.6rem 1rem;
+ border-radius: 0 $border-radius $border-radius 0;
+}
+
+// Horizontal rules are the one place a pure chalk stroke works, because
+// nothing depends on seeing them, so the rule sweeps the whole box of sticks.
+hr:not(.sidebar-divider) {
+ border: 0;
+ height: 2px;
+ background: linear-gradient(
+ 90deg,
+ transparent,
+ rgba($brand-mint, 0.7) 12%,
+ rgba($brand-sky, 0.7) 30%,
+ rgba($brand-lemon, 0.7) 50%,
+ rgba($brand-peach, 0.7) 70%,
+ rgba($brand-coral, 0.7) 88%,
+ transparent
+ );
+ opacity: 0.9;
+}
diff --git a/docs/_quarto.yml b/docs/_quarto.yml
new file mode 100644
index 0000000..b586862
--- /dev/null
+++ b/docs/_quarto.yml
@@ -0,0 +1,130 @@
+project:
+ type: atelier
+ # Generates changelog.qmd from CHANGELOG.md and removes it afterwards. The
+ # leading ./ is required; a bare name fails to spawn. The scripts live in
+ # _scripts/, whose leading underscore keeps Quarto from treating it as
+ # content.
+ #
+ # The code-window extension itself cannot be staged here. Quarto builds its
+ # extension registry while reading this file, before any pre-render script
+ # runs, and does not follow symlinks, so a shortcode from a linked or
+ # pre-render-copied extension is reported as not found.
+ # ./_scripts/sync-extension.sh copies it from the repository root beforehand
+ # instead: run that script before previewing locally, and note that the
+ # Pages workflow runs it before every render. See
+ # _extensions/README.md.
+ pre-render: ./_scripts/pre-render.sh
+ post-render: ./_scripts/post-render.sh
+
+website:
+ title: "Code Window"
+ description: "A Quarto filter that dresses code blocks as application windows, with a filename, traffic lights, and optional folding."
+ # No trailing slash: Quarto builds the social image URL by concatenating this
+ # with a leading-slash image path, without normalising.
+ site-url: &site-url https://m.canouil.dev/quarto-code-window
+ repo-url: https://github.com/mcanouil/quarto-code-window
+ # The Quarto project root is `docs/`, so without this every edit and issue
+ # link points at a path one level up from the page it was built for.
+ repo-subdir: docs
+ page-navigation: true
+ # atelier defaults search to an overlay button in the navbar. With no navbar
+ # the search belongs in the sidebar, as a field rather than a button.
+ search:
+ location: sidebar
+ type: textbox
+ # Book-like layout: a docked sidebar carries the navigation and the search,
+ # and there is no navbar. The gitlink widget replaces the sidebar tool
+ # pointing at #gitlink-widget, and atelier themes the docked sidebar from the
+ # same tokens as the navbar it replaces.
+ navbar: false
+ sidebar:
+ # `background` and `foreground` are left out: atelier repaints a docked
+ # sidebar from the chrome palette, so neither has any effect on it.
+ style: docked
+ search: true
+ pinned: true
+ align: center
+ collapse-level: 2
+ tools:
+ - href: "#gitlink-widget"
+ text: "GitHub"
+ icon: github
+ # Plain labels, no icons: Quarto expands no shortcode in a sidebar item's
+ # text, and the raw web component leaks out of the sidebar into the
+ # breadcrumbs, which reuse the same string.
+ contents:
+ - href: index.qmd
+ text: "Home"
+ - href: reference.qmd
+ text: "Reference"
+ - href: examples.qmd
+ text: "Examples"
+ - text: "---"
+ - href: changelog.qmd
+ text: "Changelog"
+ page-footer:
+ left: |
+ Powered by [{{< iconify simple-icons:quarto title="Quarto" label="Quarto" >}} Quarto](https://quarto.org).
+ center: |
+ © []{#current-year} [Mickaël Canouil](https://mickael.canouil.fr). [{{< iconify octicon:heart-fill-16 title="Heart" label="Heart" >}} Sponsor](https://github.com/sponsors/mcanouil?o=esb).
+ right: |
+ Licence: [MIT](https://github.com/mcanouil/quarto-code-window?tab=MIT-1-ov-file#readme).
+
+brand: _extensions/mcanouil/pastel/brand.yml
+
+format:
+ # Configure the extension format by name. Declaring `html` would replace
+ # `atelier-html` rather than configure it, silently dropping the theme, the
+ # bundled scripts, and the social-metadata filter.
+ atelier-html:
+ theme:
+ light:
+ - brand
+ - _extensions/mcanouil/pastel/pastel.scss
+ - assets/theme.scss
+ dark:
+ - brand
+ - _extensions/mcanouil/pastel/pastel.scss
+ - assets/theme.scss
+
+filters:
+ # Resolved from the copy sync-extension.sh takes from the repository root,
+ # not from a committed dependency: this repository publishes code-window, so
+ # the site runs the version being released.
+ - at: pre-quarto
+ path: code-window
+ - at: post-quarto
+ path: gitlink
+
+extensions:
+ # Quarto keeps the `website` block out of the metadata it hands to Lua
+ # filters, so the social-metadata filter cannot read `website.site-url` to
+ # build `og:url` and the canonical link. The anchor above republishes the same
+ # scalar here, without a second copy of the string.
+ atelier:
+ site-url: *site-url
+ gitlink:
+ # Widget only: the platform and repository come from `website.repo-url`, and
+ # in-text reference rewriting stays off so prose is left alone.
+ enabled: false
+ widget:
+ enabled: true
+ extra-links:
+ - text: "Ideas / Feature Requests"
+ href: "/discussions/categories/ideas"
+ icon: discussion
+ - text: "Q&A"
+ href: "/discussions/categories/q-a"
+ icon: question
+ sponsor: "mcanouil"
+ # There is no navbar; the widget sits in the docked sidebar instead, so
+ # there are no navbar tools to restyle.
+ style-navbar-tools: false
+ code-window:
+ style: "macos"
+ # Blocks here are configuration to copy rather than files to save, so a
+ # filename derived from the language would only add noise.
+ #
+ # Quoted deliberately. A bare `false` is read as unset and reverts to the
+ # default, because the option lookup treats a Lua `false` as absent.
+ auto-filename: "false"
diff --git a/docs/_scripts/post-render.sh b/docs/_scripts/post-render.sh
new file mode 100755
index 0000000..9a6bacc
--- /dev/null
+++ b/docs/_scripts/post-render.sh
@@ -0,0 +1,17 @@
+#!/usr/bin/env bash
+#
+# Documentation Post-render Script
+# Removes the transient files generated by pre-render.sh.
+#
+# @license MIT License
+# @copyright 2026 Mickaël Canouil
+# @author Mickaël Canouil
+#
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+DOCS_DIR="$(dirname "${SCRIPT_DIR}")"
+
+rm -f "${DOCS_DIR}/changelog.qmd" "${DOCS_DIR}/_variables.yml"
+printf '[post-render] Removed changelog.qmd and _variables.yml\n'
diff --git a/docs/_scripts/pre-render.sh b/docs/_scripts/pre-render.sh
new file mode 100755
index 0000000..879c454
--- /dev/null
+++ b/docs/_scripts/pre-render.sh
@@ -0,0 +1,204 @@
+#!/usr/bin/env bash
+#
+# Documentation Pre-render Script
+# Generates the project variables and the changelog page.
+#
+# @license MIT License
+# @copyright 2026 Mickaël Canouil
+# @author Mickaël Canouil
+#
+# Both generated files, _variables.yml and changelog.qmd, are ignored by Git and
+# removed by post-render.sh. The extension itself cannot be staged here, because
+# Quarto resolves extensions before pre-render runs; see sync-extension.sh.
+#
+# _variables.yml carries the reference a reader should install, so the pages can
+# write `quarto add {{< var extension.reference >}}` rather than a slug that
+# resolves to the default branch. The version is read from the extension
+# manifest, which the release workflow bumps, and the site is rendered from the
+# release tag, so the page names the version it documents. Quarto re-reads the
+# project configuration after pre-render, which is what makes a generated
+# variables file work at all.
+#
+# Version headings are restructured into a three-level hierarchy:
+#
+# ## X.Y.Z (date) (in CHANGELOG.md)
+#
+# becomes:
+#
+# ## X {#version-X}
+# ### X.Y {#version-X-Y}
+# #### X.Y.Z (date) {#version-X-Y-Z}
+#
+# A version heading is promoted by two levels, so every heading nested under it
+# shifts by the same two: "### New Features" becomes "##### New Features".
+# Without the shift a subsection closes the version it belongs to, and the
+# document outline stops matching the page.
+#
+# The "Unreleased" section is omitted, so the page describes released versions
+# only.
+#
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+DOCS_DIR="$(dirname "${SCRIPT_DIR}")"
+ROOT_DIR="$(dirname "${DOCS_DIR}")"
+
+# The extension the site documents, named by the directory that holds it, which
+# is the name its shortcodes and filters are registered under. Deriving it keeps
+# this script identical in every repository. A repository with no extension
+# still gets a page, named after itself, rather than a failed render.
+EXTENSION_NAME=""
+for extension_dir in "${ROOT_DIR}"/_extensions/*/; do
+ [[ -f "${extension_dir}_extension.yml" ]] || continue
+ EXTENSION_NAME="$(basename "${extension_dir}")"
+ break
+done
+if [[ -z "${EXTENSION_NAME}" ]]; then
+ EXTENSION_NAME="$(basename "${ROOT_DIR}")"
+ printf '[pre-render] No extension under _extensions/; naming the page after %s\n' \
+ "${EXTENSION_NAME}"
+fi
+
+# The repository the extension is published from. Taken from the website
+# configuration rather than the Git remote, so a fork documents the repository
+# it publishes as, and a checkout with no remote still renders.
+REPO_SLUG="$(sed -n \
+ 's|^[[:space:]]*repo-url:[[:space:]]*https://github.com/\([^[:space:]]*\)|\1|p' \
+ "${DOCS_DIR}/_quarto.yml" | head -n 1)"
+REPO_SLUG="${REPO_SLUG%/}"
+if [[ -z "${REPO_SLUG}" ]]; then
+ REPO_SLUG="$(git -C "${ROOT_DIR}" remote get-url origin 2>/dev/null |
+ sed -n 's|.*github\.com[:/]\(.*\)|\1|p' | sed 's|\.git$||')"
+fi
+if [[ -z "${REPO_SLUG}" ]]; then
+ printf '[pre-render] No repo-url in _quarto.yml and no origin remote\n' >&2
+ exit 1
+fi
+
+MANIFEST="${ROOT_DIR}/_extensions/${EXTENSION_NAME}/_extension.yml"
+VERSION=""
+if [[ -f "${MANIFEST}" ]]; then
+ VERSION="$(sed -n \
+ 's/^version:[[:space:]]*["'\'']\{0,1\}\([^"'\''[:space:]]*\).*/\1/p' \
+ "${MANIFEST}" | head -n 1)"
+ if [[ -z "${VERSION}" ]]; then
+ printf '[pre-render] No version in %s\n' "${MANIFEST}" >&2
+ exit 1
+ fi
+fi
+
+{
+ printf '# Generated by _scripts/pre-render.sh. Do not edit.\n'
+ printf 'extension:\n'
+ printf ' name: "%s"\n' "${EXTENSION_NAME}"
+ printf ' repo: "%s"\n' "${REPO_SLUG}"
+ if [[ -n "${VERSION}" ]]; then
+ printf ' version: "%s"\n' "${VERSION}"
+ printf ' reference: "%s@%s"\n' "${REPO_SLUG}" "${VERSION}"
+ # The same reference, encoded for the repo query parameter of a Quarto
+ # Wizard URI.
+ printf ' wizard-reference: "%s%%40%s"\n' "${REPO_SLUG//\//%2F}" "${VERSION}"
+ fi
+} >"${DOCS_DIR}/_variables.yml"
+
+if [[ -z "${VERSION}" ]]; then
+ printf '[pre-render] No %s; the pages have no version to install\n' \
+ "${MANIFEST}" >&2
+elif ! git -C "${ROOT_DIR}" rev-parse -q --verify "refs/tags/${VERSION}" >/dev/null; then
+ # Expected before a first release, and a warning rather than an error: the
+ # workflow renders from a tag, so this only fires on a local preview.
+ printf '[pre-render] warning: %s is not tagged; the install commands name an unreleased version\n' \
+ "${VERSION}" >&2
+fi
+
+printf '[pre-render] _extension.yml -> _variables.yml (%s@%s)\n' \
+ "${REPO_SLUG}" "${VERSION}"
+
+if [[ ! -f "${ROOT_DIR}/CHANGELOG.md" ]]; then
+ cat >"${DOCS_DIR}/changelog.qmd" <<'EOF'
+---
+title: "Changelog"
+description: "No changelog is available for this extension."
+---
+
+No changelog available.
+EOF
+ printf '[pre-render] No CHANGELOG.md; wrote a placeholder changelog.qmd\n'
+ exit 0
+fi
+
+awk -v name="${EXTENSION_NAME}" '
+BEGIN {
+ in_unreleased = 0
+ in_version = 0
+ cur_major = -1
+ cur_minor = -1
+ prev_blank = 1
+ printf "---\ntitle: \"Changelog\"\nsubtitle: \"What changed, and when.\"\n"
+ printf "description: \"Every released version of the %s extension, and what each one changed.\"\n---\n\n", name
+}
+
+# Emit a line, collapsing consecutive blank lines and suppressing leading ones.
+function emit(line, is_blank) {
+ is_blank = (line == "")
+ if (is_blank) {
+ if (!prev_blank) { print ""; prev_blank = 1 }
+ } else {
+ print line
+ prev_blank = 0
+ }
+}
+
+/^# / { next }
+/^## Unreleased$/ { in_unreleased = 1; next }
+
+# Inside the Unreleased block: skip content, stop on next versioned heading.
+in_unreleased && !/^## [0-9]/ { next }
+in_unreleased { in_unreleased = 0 }
+
+/^## [0-9]+\.[0-9]+\.[0-9]+ \(/ {
+ # Fields: $1="##" $2="X.Y.Z" $3="(date)"
+ ver = $2
+ date = substr($3, 2, length($3) - 2) # strip surrounding parens
+ split(ver, v, ".")
+ major = int(v[1])
+ minor = int(v[2])
+ patch = int(v[3])
+
+ if (major != cur_major) {
+ emit("")
+ emit("## " major " {#version-" major "}")
+ emit("")
+ cur_major = major
+ cur_minor = -1
+ }
+
+ if (minor != cur_minor) {
+ emit("### " major "." minor " {#version-" major "-" minor "}")
+ emit("")
+ cur_minor = minor
+ }
+
+ emit("#### " major "." minor "." patch " (" date ") " \
+ "{#version-" major "-" minor "-" patch "}")
+ in_version = 1
+ next
+}
+
+# Headings nested under a version follow it down by two levels, so they stay
+# inside the version they document.
+in_version && /^#+ / {
+ if (length($1) + 2 > 6) {
+ printf "[pre-render] heading too deep to nest: %s\n", $0 > "/dev/stderr"
+ emit($0)
+ } else {
+ emit("##" $0)
+ }
+ next
+}
+
+{ emit($0) }
+' "${ROOT_DIR}/CHANGELOG.md" >"${DOCS_DIR}/changelog.qmd"
+
+printf '[pre-render] CHANGELOG.md -> changelog.qmd\n'
diff --git a/docs/_scripts/sync-extension.sh b/docs/_scripts/sync-extension.sh
new file mode 100755
index 0000000..398293a
--- /dev/null
+++ b/docs/_scripts/sync-extension.sh
@@ -0,0 +1,44 @@
+#!/usr/bin/env bash
+#
+# Documentation Extension Sync
+# Mirrors the repository's own extension into the documentation project.
+#
+# @license %%license%%
+# @copyright %%year%% %%author%%
+# @author %%author%%
+#
+# The website demonstrates the extension it documents, so the extension has to
+# be resolvable from docs/. Quarto builds its extension registry while reading
+# _quarto.yml, before any pre-render script runs and without following symlinks,
+# so a staged or linked copy is not found: shortcodes report "not found" and the
+# page renders empty. The copy therefore has to exist on disk before Quarto
+# starts.
+#
+# The repository root stays the single source of truth, so the copy is ignored
+# by Git rather than committed. Run this script before previewing locally; the
+# Pages workflow runs it before every render.
+#
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+DOCS_DIR="$(dirname "${SCRIPT_DIR}")"
+ROOT_DIR="$(dirname "${DOCS_DIR}")"
+# Under a `local` owner directory: the copy is generated from this repository
+# rather than installed from anywhere, and saying so in the path keeps it
+# distinct from the vendored dependencies. It also avoids a collision when the
+# extension is named after its owner.
+TARGET_DIR="${DOCS_DIR}/_extensions/local"
+
+for extension_dir in "${ROOT_DIR}"/_extensions/*/; do
+ [[ -f "${extension_dir}_extension.yml" ]] || continue
+ extension_name="$(basename "${extension_dir}")"
+ target="${TARGET_DIR}/${extension_name}"
+ # Remove first: copying onto an existing directory nests the new copy inside
+ # the old one.
+ rm -rf "${target}"
+ mkdir -p "${TARGET_DIR}"
+ cp -R "${extension_dir%/}" "${target}"
+ printf '[sync] _extensions/%s -> docs/_extensions/local/%s\n' \
+ "${extension_name}" "${extension_name}"
+done
diff --git a/docs/assets/theme.scss b/docs/assets/theme.scss
new file mode 100644
index 0000000..ba53804
--- /dev/null
+++ b/docs/assets/theme.scss
@@ -0,0 +1,5 @@
+/*-- scss:rules --*/
+
+// Per-repository overrides only. The palette comes from the shared pastel
+// extension, which is applied just before this file, so anything set here wins
+// the cascade.
diff --git a/docs/examples.qmd b/docs/examples.qmd
new file mode 100644
index 0000000..a6d4afb
--- /dev/null
+++ b/docs/examples.qmd
@@ -0,0 +1,111 @@
+---
+title: "Examples"
+subtitle: "Every style, and the folding."
+description: "Code blocks framed by the extension, one per style and option, with the source alongside."
+---
+
+Every named block on this site is framed by the extension, so this page is its own demonstration.
+The site sets:
+
+```{.yaml filename="_quarto.yml"}
+extensions:
+ code-window:
+ style: macos
+ auto-filename: "false"
+```
+
+## Naming the window
+
+Quarto's `filename` attribute names it:
+
+````markdown
+```{.yaml filename="_quarto.yml"}
+project:
+ type: website
+```
+````
+
+```{.yaml filename="_quarto.yml"}
+project:
+ type: website
+```
+
+A block with no `filename` is left alone in HTML, whatever `auto-filename` says.
+Under Typst that same block is framed and labelled with its language.
+
+## The three styles
+
+````markdown
+```{.r filename="analysis.R" code-window-style="macos"}
+```
+````
+
+```{.r filename="analysis.R" code-window-style="macos"}
+summary(cars)
+```
+
+```{.r filename="analysis.R" code-window-style="windows"}
+summary(cars)
+```
+
+```{.r filename="analysis.R" code-window-style="default"}
+summary(cars)
+```
+
+Traffic lights, title-bar buttons, and a plain filename.
+
+## Folding
+
+````markdown
+```{.python filename="long.py" code-window-collapse="closed"}
+```
+````
+
+```{.python filename="long.py" code-window-collapse="closed"}
+for i in range(100):
+ print(i)
+```
+
+```{.python filename="short.py" code-window-collapse="open"}
+print("expanded by default")
+```
+
+`closed` and `open` differ only in the initial state.
+The `` element is built at page load by the script the extension injects, so the fold needs JavaScript; without it the block renders open and unframed.
+
+Set `collapse` under `extensions.code-window` to fold every block, and `code-window-collapse="false"` to opt one out.
+
+## Highlighted lines
+
+A block that highlights lines gets a chip beside its filename:
+
+````markdown
+```{.r filename="steps.R" code-line-numbers="2-3"}
+```
+````
+
+```{.r filename="steps.R" code-line-numbers="2-3"}
+x <- seq_len(10)
+y <- x^2
+z <- sum(y)
+z
+```
+
+`code-window-lines` sets the chip independently of the highlighting, and `lines-label: false` turns the chip off.
+
+## Leaving a block alone
+
+````markdown
+```{.bash code-window-enabled="false"}
+```
+````
+
+```{.bash code-window-enabled="false"}
+echo "no chrome on this one"
+```
+
+Annotations still render on a block with the chrome turned off.
+
+## Source
+
+The repository ships a short, standalone starting point you can copy: [`example.qmd`](https://github.com/mcanouil/quarto-code-window/blob/main/example.qmd).
diff --git a/docs/index.qmd b/docs/index.qmd
new file mode 100644
index 0000000..6fb2883
--- /dev/null
+++ b/docs/index.qmd
@@ -0,0 +1,74 @@
+---
+title: "Code Window"
+subtitle: "Code blocks dressed as application windows."
+description: "What the code-window extension does, how to enable it, and the chrome it puts on a block."
+authors:
+ - name: "Mickaël CANOUIL, _Ph.D._"
+ orcid: "0000-0002-3396-4549"
+ url: "https://mickael.canouil.fr"
+---
+
+A page of code blocks is a page of grey rectangles.
+Which file is which, which one is a shell command and which a configuration file, has to be worked out from the contents.
+
+`code-window` frames each block as a window: a title bar with the filename, traffic lights or title-bar buttons, and, where it helps, a fold.
+
+Every named code block on this site is drawn by it, including this one:
+
+```{.yaml filename="_quarto.yml"}
+filters:
+ - path: code-window
+ at: pre-quarto
+```
+
+## Installation
+
+```bash
+quarto add {{< var extension.reference >}}
+```
+
+This will install the extension under the `_extensions` subdirectory.
+If you are using version control, you will want to check in this directory.
+
+Or install it from your editor with [Quarto Wizard](https://m.canouil.dev/quarto-wizard):
+
+::: {.btn-group role="group" aria-label="Quarto Wizard installer options"}
+
+[Visual Studio Code](vscode://mcanouil.quarto-wizard/install?repo={{< var extension.wizard-reference >}}){.btn .btn-outline-primary title="Install {{< var extension.reference >}} in Visual Studio Code using the Quarto Wizard extension."}
+[Positron](positron://mcanouil.quarto-wizard/install?repo={{< var extension.wizard-reference >}}){.btn .btn-outline-primary title="Install {{< var extension.reference >}} in Positron using the Quarto Wizard extension."}
+[VSCodium](vscodium://mcanouil.quarto-wizard/install?repo={{< var extension.wizard-reference >}}){.btn .btn-outline-primary title="Install {{< var extension.reference >}} in VSCodium using the Quarto Wizard extension."}
+
+:::
+
+## Quick start
+
+```yaml
+filters:
+ - path: code-window
+ at: pre-quarto
+```
+
+Name the file, and the block is framed with it:
+
+````markdown
+```{.yaml filename="_quarto.yml"}
+project:
+ type: website
+```
+````
+
+See the [Reference](reference.qmd) for every option, and the [Examples](examples.qmd) for each style and the folding.
+
+## Where it works
+
+HTML formats, and Typst.
+
+In HTML the chrome is assembled at page load by a script the extension injects, so the frame needs JavaScript.
+Under Typst the chrome is drawn by a wrapper function, and the extension carries hot-fixes for a few Quarto behaviours that Typst output still needs; the [Reference](reference.qmd#hot-fixes) lists them and when they switch themselves off.
+
+## Links
+
+- [Reference](reference.qmd) for every option and attribute.
+- [Examples](examples.qmd) for the styles, the folding, and the line chips.
+- [Changelog](changelog.qmd) for what each release changed.
+- [Source and issues](https://github.com/mcanouil/quarto-code-window) on GitHub.
diff --git a/docs/reference.qmd b/docs/reference.qmd
new file mode 100644
index 0000000..4223ee5
--- /dev/null
+++ b/docs/reference.qmd
@@ -0,0 +1,108 @@
+---
+title: "Reference"
+subtitle: "Every option the code-window extension accepts."
+description: "The complete code-window configuration: the document options, the per-block attributes, the window styles, and the Typst hot-fixes."
+---
+
+## Enabling the filter
+
+```yaml
+filters:
+ - path: code-window
+ at: pre-quarto
+```
+
+## Options
+
+```yaml
+extensions:
+ code-window:
+ style: macos
+ auto-filename: true
+ collapse: false
+ lines-label: true
+```
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `enabled` | boolean | `true` | Whether the filter runs at all. |
+| `style` | string | `macos` | The window chrome: `macos` for traffic lights, `windows` for title-bar buttons, `default` for a plain filename. |
+| `auto-filename` | boolean | `true` | Use the block's language as the filename when none is given. |
+| `collapse` | boolean or string | `false` | Wrap every block in a ``. `open` renders it expanded, `closed` or `true` collapsed. HTML only. |
+| `lines-label` | boolean | `true` | Show a chip beside the filename with the highlighted-line spec. |
+| `wrapper` | string | `code-window` | The Typst function used to draw the chrome. |
+| `hotfix` | object | all on | The Typst hot-fixes below. |
+
+: Document and project options. {.striped .hover tbl-colwidths="[18,16,12,54]"}
+
+## Per-block attributes
+
+````markdown
+```{.yaml filename="_quarto.yml" code-window-style="windows"}
+```
+````
+
+| Attribute | Type | Description |
+| --- | --- | --- |
+| `code-window-enabled` | boolean | Whether this block gets chrome. Annotations still render when it does not. |
+| `code-window-no-auto-filename` | boolean | Suppress the derived filename for this block alone. |
+| `code-window-style` | string | Override the style for this block: `macos`, `windows`, `default`. |
+| `code-window-collapse` | boolean or string | Fold this block: `open`, `closed`, `true`, or `false`. HTML only. |
+| `code-window-lines` | string | The line spec shown in the chip, such as `1,3-5`. Defaults to Quarto's `code-line-numbers`. |
+
+: Attributes accepted on a code block. {.striped .hover tbl-colwidths="[30,14,56]"}
+
+Quarto's own `filename` attribute names the window.
+
+::: {.callout-important}
+In HTML output only a block with an author-set `filename` is framed.
+Quarto builds the wrapper the chrome attaches to before this filter runs, so a filename derived by `auto-filename` arrives too late: the block keeps its language as a `data-filename` attribute and renders without a window.
+Typst is unaffected, and frames derived and author-set filenames alike.
+:::
+
+## How the chrome is applied
+
+In HTML the extension marks blocks and injects a stylesheet and a script.
+The script runs at page load and builds the title bar, the fold, and the line chip from those marks, so all three need JavaScript.
+
+In Typst the chrome is a call to the `wrapper` function, emitted into the document, and needs nothing at read time.
+
+## Hot-fixes
+
+Typst output needs a few corrections that Quarto does not yet make itself.
+Each is on by default and each can be given a version at which it switches itself off, so an upgrade retires it without a code change.
+
+| Hot-fix | What it corrects |
+| --- | --- |
+| `code-annotations` | Code annotations in Typst output. |
+| `skylighting` | Block styling and inline code backgrounds in Typst output. |
+| `typst-title` | Theorem title strings, evaluated as markup. |
+
+: The Typst hot-fixes. {.striped .hover tbl-colwidths="[26,74]"}
+
+```yaml
+extensions:
+ code-window:
+ hotfix:
+ skylighting:
+ enabled: true
+ quarto-version: "1.9.0"
+```
+
+They exist for [quarto-dev/quarto-cli#14170](https://github.com/quarto-dev/quarto-cli/issues/14170) and will be removed once Quarto covers the same ground.
+
+## Interactions
+
+::: {.callout-caution}
+This filter claims code blocks at `pre-quarto`, which puts it ahead of anything else that wants them.
+
+Two extensions in this family are affected: [`typst-render`](https://m.canouil.dev/quarto-typst-render) never sees its ```` ```{typst} ```` blocks when this one runs, so no figure is produced; and [`language-cell-decorator`](https://m.canouil.dev/quarto-language-cell-decorator), which this extension supersedes, decorates the same blocks a second time.
+:::
+
+## Limitations
+
+- HTML formats and Typst. Elsewhere the code block is left as it is.
+- Folding is HTML only; Typst has no equivalent.
+- The HTML chrome is built by script at page load, so a reader with JavaScript off sees plain code blocks.
+- `auto-filename` frames nothing in HTML; give a block an explicit `filename` there.
+- A boolean option written as `false` under `extensions.code-window` is read as unset and reverts to its default. Write `"false"` in quotes until this is fixed.