Loom

Documenting Fieldwork: Photos, Video, and Embedded Media

2026-03-05T00:00:00+00:00

Field science generates a lot of media: photographs from the ablation zone, video of calving events, timelapse sequences, and drone footage. This post documents how to embed all of it in a Loom post, and covers the four callout block types along the way.

Photo galleries

Use the gallery include with an array of images in front matter. Each image takes a src path, an alt description (required for accessibility), and an optional caption shown in the lightbox.

gallery:
  - src: /assets/images/matterhorn.jpg
    alt: "Matterhorn from Gornergrat"
    caption: "Gornergrat, 3089 m. September 2019."
  - src: /assets/images/matterhorn.jpg
    alt: "Gorner Glacier confluence"
    caption: "The confluence of the Gorner and Grenzgletscher."

Then in the post body:

{% include gallery.html %}

The result is a three-column responsive grid. Click any image to open the lightbox. Navigate with the arrow keys or on-screen buttons; close with Esc.

💡

Image sizing: Thumbnails are cropped to a 4:3 aspect ratio using object-fit: cover. The lightbox shows images at their natural size, constrained to the viewport. A good target is 1600 × 1200 px for lightbox quality.

Photo carousels

When you want to show a sequence of images one at a time rather than a grid, use the carousel include. The format is identical to the gallery.

{% include carousel.html %}

Or pass an explicit array:

{% include carousel.html images=page.demo_carousel %}

Matterhorn from Gornergrat station. The Gorner Glacier fills the valley below.

Confluence of the Gorner and Grenzgletscher, showing medial moraine.

Surface channels and cryoconite holes in the ablation zone.

The proglacial lake at the Gorner terminus, expanding since the 1980s.

Navigate with the on-screen prev/next buttons or the dot indicators below the image. The carousel does not open a lightbox — it is designed for curated sequential storytelling rather than a browsable collection. Use a gallery when readers need to scan all images at once; use a carousel when order and pacing matter.

Native video

Self-hosted video files use the video include. The player is a styled native HTML5 element — no third-party player required.

{% include video.html
   src="/assets/video/gorner-timelapse.mp4"
   poster="/assets/images/gorner-poster.jpg"
   caption="Gorner Glacier timelapse, summer 2019. 48 frames over 6 weeks." %}

⚠️

File size: Video files can be large. Compress to H.264 at 1080p before committing. A 60-second timelapse should compress to under 10 MB. For longer videos, use YouTube or Vimeo instead and embed with the embed include below.

Parameters

Parameter	Required	Description
`src`	Yes	Path to the `.mp4` file
`poster`	No	Thumbnail shown before playback
`caption`	No	Caption below the player
`loop`	No	Repeat continuously (`loop="true"`)
`autoplay`	No	Start immediately — forces mute

YouTube and Vimeo embeds

The embed include wraps any YouTube or Vimeo URL in a responsive 16:9 container. YouTube URLs are automatically rewritten to youtube-nocookie.com.

{% include embed.html
   url="https://www.youtube.com/embed/x1SgmFa0r04?si=mCkXoLDafmHUzAMk"
   caption="NASA Scientific Visualization: a year of Earth's CO₂ flux." %}

NASA Scientific Visualization Studio: a year of Earth's CO₂ flux. Public domain.

Vimeo works identically:

{% include embed.html url="https://vimeo.com/123456789" caption="Caption" %}

📖

Privacy mode: YouTube embeds use youtube-nocookie.com rather than youtube.com. No cookies are set on the visitor's browser until they press play — an important distinction under ePrivacy rules.

Callout blocks

Loom has four callout variants for drawing attention to different types of information.

Note — tips, clarifications, supplementary context:

 class="callout callout-note">
   class="callout-icon">💡
   class="callout-body">
    Your note content here.

Warning — things that can go wrong, caveats, destructive actions:

 class="callout callout-warning">
   class="callout-icon">⚠️
   class="callout-body">
    Your warning content here.

Definition — terminology, acronyms, key concepts:

 class="callout callout-definition">
   class="callout-icon">📖
   class="callout-body">
    Term: Definition text.

Takeaway — the key point to remember from a section:

 class="callout callout-takeaway">
   class="callout-icon">✓
   class="callout-body">
    The key takeaway from this section.

✓

For images and short clips: use the gallery and video includes, self-hosted. For longer video: use YouTube or Vimeo with the embed include. Callout blocks are raw HTML — paste the snippet and fill in the content.

Co-authorship

This post is co-authored, which demonstrates the multi-author system. In front matter, pass an array of author slugs:

author: [paul-hobson, sophie-marchand]

Both names render as links in the byline and author card. Each author’s profile page at /author/their-slug/ will include this post in their listing. Author data lives in _data/authors.yml.

Glaciers I Have Known

2026-03-02T00:00:00+00:00

These are places I have walked on, drilled into, and watched retreat. Findelen and Gornergletscher above Zermatt. Mer de Glace above Chamonix. Peyto Glacier and the Columbia Icefield in the Canadian Rockies. Each one is a different chapter of the same story: the post-industrial drawdown of ice that had been accumulating since the Little Ice Age maximum of roughly 1850.

The maps below use Mapbox GL terrain — actual elevation data rendered in 3D — with satellite imagery to show current ice extent. The white you see is real. What is not white used to be.

The Swiss Alps: two glaciers above Zermatt

The valley above Zermatt holds two of the most studied glacier systems in the Alps, separated by the ridge of the Rothorn. Both drain the Monte Rosa massif, the largest glaciated area in the Alps outside the main ice divide.

The Zermatt valley from the south. Gornergletscher occupies the left fork; Findelen glacier drains the right. The Matterhorn (4478 m) is the pyramid at centre-left.

Findelen glacier

East of Zermatt, Findelen is fed from the Strahlhorn (4190 m), Rimpfischhorn (4198 m), and Adlerhorn (3988 m). It is a relatively simple valley glacier — elongated, well-defined, draining northwest into the Vispa system. ETH Zürich has maintained a mass balance programme here since the 1960s.

The dark moraine ridges flanking the glacier record its Little Ice Age maximum. The terminus has retreated roughly 2 km up-valley since 1900 and currently sits at approximately 2580 m. At current retreat rates the glacier will lose contact with its accumulation zone before 2100.

Gornergletscher

The Gorner system is the second largest glacier complex in the Alps by area — roughly 57 km² — comprising the Gornergletscher, Grenzgletscher, Monte Rosa Gletscher, and six tributary glaciers draining from the Monte Rosa massif (4634 m) and the Swiss-Italian border ridge.

The glaciological signature of the Gorner is the annual formation and drainage of the Gornersee — a proglacial lake that forms each spring at the confluence of the Gorner and Grenz glaciers and drains catastrophically each June in a subglacial outburst flood (jökulhlaup). The drainage, which can release up to 10 million m³ in a few days, has been used to study subglacial hydrology and ice-bed coupling. It is becoming less reliable as the glacier thins and the ice dam that forms the lake margin weakens.

France: Mer de Glace

The Mer de Glace is the largest glacier in France: 40 km² and approximately 400 m thick at the Géant icefall, where ice from the Mont Blanc plateau cascades 1000 m into the main glacier tongue.

The Montenvers railway, opened in 1908, was one of Europe’s first glacier tourism enterprises. The station sits at 1913 m; a ladder system originally allowed visitors to walk down to the ice surface. That ladder has been extended nine times as the glacier surface has dropped more than 150 m since the railway opened. The current ladder system — visible in satellite imagery as a thin line on the exposed bedrock face — is more than 500 m long. It is a precise vertical record of loss.

The ice visible here in satellite imagery will not be here in 2100 under any current emissions scenario.

Canada: the Rockies

The Canadian Rocky Mountain glaciers are among the most accessible in the world and among the most intensively monitored. They are also retreating faster than their European counterparts in absolute area terms.

Peyto Glacier

Peyto drains the Wapta Icefield southward into Peyto Lake — famous for its turquoise colour, caused by glacial flour suspended in the meltwater. The glacier’s wolf-head silhouette from the Bow Summit viewpoint has made it one of the most-photographed glaciers in North America.

Since systematic photography began in 1896, Peyto has retreated more than 2.5 km and lost approximately 70% of its volume. The lake it feeds has grown substantially as the terminus has withdrawn. At its current rate of volume loss, Peyto will be unrecognisable within a generation.

Athabasca Glacier and the Columbia Icefield

The Columbia Icefield straddles the hydrological apex of the continent. Meltwater from the icefield drains to three oceans: to the Pacific via the Columbia River, to the Atlantic via the North Saskatchewan and Saskatchewan rivers, and to the Arctic via the Athabasca and Mackenzie rivers. It is one of very few places in North America with this property.

The Athabasca Glacier — the most accessible outlet of the Columbia Icefield — has retreated 1.5 km since 1844. Marker posts along the Icefields Parkway mark its historical terminus positions; driving past them is one of the more visceral ways to understand glacier retreat because the distance between posts is human-scaled. The most recent post (2021) is a 15-minute walk from the current terminus.

The scroll tour

The map below connects all five sites in sequence. It uses Mapbox GL terrain with satellite imagery and a pitched camera — the same data you have been looking at above, but as a single continuous journey.

Two continents, five glaciers. The sites in this post span roughly 8,500 km — from the Monte Rosa massif in the central Alps to the Columbia Icefield in the Canadian Rockies. They share a climate signal, a measurement history, and a trajectory.

Zermatt, Switzerland. The valley above Zermatt holds two of the Alps' most studied glacier systems: Findelen to the east and Gornergletscher to the south. The Monte Rosa massif (4634 m) anchors the ice. Both glaciers have been in continuous retreat since the end of the Little Ice Age around 1860.

Findelen Glacier. Fed from three high peaks above 4000 m, Findelen is a textbook valley glacier — well-defined accumulation zone, clean equilibrium line, straightforward mass balance signal. The dark lateral moraines mark its Little Ice Age extent. It has retreated roughly 2 km since 1900.

Gornergletscher. The Gorner complex — 57 km², six tributary glaciers — is the dominant feature of the Monte Rosa drainage. Each June, the Gornersee (a 10-million m³ ice-dammed lake) drains in a subglacial flood lasting days. As the glacier thins, the ice dam is becoming structurally unreliable. The flood events are changing character.

Mer de Glace, Chamonix. The largest glacier in France, flowing northwest from the Géant icefall at the foot of the Mont Blanc plateau. The surface has dropped more than 150 m since the Montenvers railway opened in 1908. The ladder system to the ice has been extended nine times. The exposed grey bedrock you can see was under ice within living memory.

Crossing the Atlantic. From the Alps to the Canadian Rockies — the same post-industrial warming signal playing out in a different mountain range, at a different scale. The Rockies glaciers are more continental, more seasonal, draining watersheds that supply drinking water to millions on the prairies.

Peyto Glacier, Banff. The Wapta Icefield drains south into Peyto Lake, its turquoise colour fed by glacial flour. The glacier has lost more than 70% of its volume since systematic measurement began in 1896. The wolf-head silhouette visible from Bow Summit is now a shadow of the form that appeared on early photographs.

Columbia Icefield. Meltwater here drains to three oceans — Pacific, Atlantic, and Arctic. The Athabasca Glacier has retreated 1.5 km since 1844. The Icefields Parkway marker posts make the recession human-scaled: each one represents a decade of loss, spaced along a walking path from the current terminus back to where the ice once stood.

The same story, twice. These are not isolated case studies. The mass balance record from every glacier in this tour correlates with the same Northern Hemisphere temperature signal. The Alps and the Rockies are running the same experiment. Both are getting the same result.

A note on the maps

These maps use Mapbox GL terrain — the mapbox-terrain-dem-v1 digital elevation model at 512-pixel tiles, rendered in WebGL with 1.5× vertical exaggeration. The satellite imagery is Maxar. The ice visible is real and current to within a few years. The grey and brown that was once white is real too.

The data-terrain attribute in Loom’s Mapbox adapter triggers this automatically:

 data-map="findelen"
     data-pitch="55"
     data-bearing="155"
     data-terrain="1.5"
     data-style="mapbox://styles/mapbox/satellite-streets-v12"
     style="height:420px;">

For scrollytelling, pitch and bearing are first-class parameters in data-update — the camera tilts and rotates smoothly between sites on each scroll step.

Interactive Maps with Mapbox GL JS

2026-03-01T00:00:00+00:00

Loom includes two map adapters: Leaflet for token-free raster tile maps, and Mapbox GL JS for vector maps with custom styles, smooth camera transitions, and 3D terrain. Use Leaflet when you need a quick map with no credentials. Use Mapbox when you need style control, high-zoom fidelity, or scroll-driven storytelling with cinematic camera moves.

Standalone maps

A single data-map attribute is all that is required. The adapter reads the access token from window.MAPBOX_TOKEN, which is injected by head.html from mapbox_token: in _config.yml.

Preset locations resolve center and zoom automatically:

 data-map="world" style="height:380px;">

Available presets: world, calgary, edmonton, vancouver, toronto.

Vancouver — the Strait of Georgia meets the Coast Mountains:

Custom centre and zoom — use data-center (longitude, latitude) and data-zoom:

 data-map="custom" style="height:380px;"
     data-center="-125.0,54.5"
     data-zoom="5">

Note the Mapbox convention: longitude first, then latitude. This is the reverse of Leaflet’s [lat, lng] order.

Style overrides

The default style is outdoors-v12 — terrain shading, land cover, contours, and waterways. It works at any zoom level and in any page context. Override with data-style when you need something different:

 data-map="calgary" data-style="mapbox://styles/mapbox/satellite-streets-v12"
     style="height:400px;">

Scrolly story: a tour of the BC coast

The scrollytelling pattern is identical to Leaflet — a .story-section containing a .story-sticky graphic and .story-steps prose, with data-update JSON on each step. For Mapbox, the update payload uses center: [lng, lat] and zoom.

British Columbia. The province spans 945,000 km² — larger than France and Germany combined. Its western edge is a 27,000 km coastline of fjords, islands, and inlets carved by glaciation over the past two million years.

Vancouver. Built on a river delta between the Coast Mountains and the Salish Sea. The city sits on unceded Musqueam, Squamish, and Tsleil-Waututh territory. At zoom 11 the False Creek inlet and Stanley Park peninsula define the downtown core.

Victoria. On the southern tip of Vancouver Island, Victoria receives less than half Vancouver's annual rainfall — sheltered by the Olympic Mountains to the south. The Inner Harbour has been the island's commercial gateway since the 1850s.

Whistler. 120 km north of Vancouver, the Whistler-Blackcomb ski area sits in a north-south valley between the Coast and Fitzsimmons ranges. Annual snowfall exceeds 10 m. The valley was glaciated as recently as 12,000 years ago.

The whole coast. Pulling back to the provincial view — the density of inlets, islands, and river deltas along this coastline hosts some of the most productive salmon habitat on Earth. Five species of Pacific salmon spawn in BC rivers, supporting both coastal ecosystems and Indigenous communities.

The data-update format for Mapbox:

 class="story-step"
     data-update='{"bc-map": {"center": [-123.12, 49.28], "zoom": 11}}'>

center is [longitude, latitude]. When Scrollama fires a step, core.js routes the payload to updateMap(), which calls map.flyTo({ center, zoom, duration: 1500 }).

How the token flows

_config.yml           mapbox_token: "pk.eyJ..."
      ↓
_includes/head.html   
      ↓
assets/js/viz/mapbox.js   const token = el.dataset.token || window.MAPBOX_TOKEN
      ↓
mapboxgl.accessToken = token

To keep the token out of source control entirely, remove it from _config.yml and set it as a GitHub Actions secret. See §17 of HOWTO.md for the workflow snippet.

Style overrides

Any valid Mapbox style URL works in data-style:

 data-map="vancouver" style="height:400px;"
     data-style="mapbox://styles/mapbox/satellite-streets-v12">

 data-map="calgary" style="height:400px;"
     data-style="mapbox://styles/mapbox/streets-v12">




 data-map="custom" style="height:400px;"
     data-center="-114.07,51.04" data-zoom="10"
     data-style="mapbox://styles/your-username/your-style-id">

Introducing Loom

2026-02-28T00:00:00+00:00

Introducing Loom

LoomCollective — 2026

What is Loom?

A Jekyll theme built for technical publishing.

Clean typography by default
Progressive visualisation layer (ECharts, D3, Leaflet, Mapbox)
Dark mode throughout
Full-text search via Pagefind

The Stack

Layer	Technology
Static site	Jekyll 4.3
CSS	Tailwind + custom tokens
JS	Alpine.js + ES modules
Build	Vite 6
Deploy	GitHub Actions

Visualisation Runtime

assets/js/core.js scans each page and loads only what it needs:

// Only ECharts loads on pages that use [data-viz]
if (document.querySelector('[data-viz]')) {
  loadECharts();
}

No JavaScript tax on simple posts.

Dark Mode

Stored in localStorage as loom-dark.

Applied synchronously in — no flash on load.

The accent colour #F0177A works in both modes.

Speaker Notes

Press S to open the speaker view.

Thank you

→ loomcollective.github.io

Scrollytelling with Maps and Charts

2026-02-27T00:00:00+00:00

Scroll-driven stories pin a visualisation on screen while the reader scrolls through prose. Each “step” in the story can trigger an update — flying a map to a new location, updating chart data, or changing the state of any registered visualisation.

This essay demonstrates two scrolly patterns: a Leaflet map that flies between cities, and a D3 bar chart that updates as the story progresses.

Standalone Leaflet map

Before the scrolly examples, here is a basic Leaflet map with the CartoDB light tile layer. No JavaScript is required in the post — just a data-leaflet element.

The data-markers attribute accepts a JSON array of {lat, lng, label} objects. Clicking a marker opens a popup.

Available tile presets: osm (default OpenStreetMap), carto (CartoDB Positron light), carto-dark, stadia.

Scrolly story: map flyTo

The pattern requires a .story-section containing a .story-sticky (the pinned graphic) and .story-steps (the scrollable prose). Give the viz element an id, then add data-update JSON to each step targeting that id.

London. The Thames cuts through 32 boroughs. At zoom level 11 the full extent of inner London sits comfortably in frame — from Heathrow in the west to the Isle of Dogs in the east.

Paris. Scroll down and the map flies south-east to the French capital. The périphérique ring road defines the boundary of the city proper. Zoom level 12 shows the arrondissement grid.

Berlin. Reunified in 1990, Berlin covers 892 km² — nine times the area of Paris. The Spree and Havel rivers wind through the city. Zoom 12 shows the inner Ringbahn.

Barcelona. Ildefons Cerdà's 1860 Eixample grid is visible at zoom 13 — perfect octagonal blocks, each 113 m per side, designed to equalise light and air for all residents.

Each step’s data-update value is a JSON object keyed by element id. When Scrollama fires story:step for a step, core.js reads the data-update, looks up each referenced element in its instance store, and calls the matching adapter’s update() function. For Leaflet that calls map.flyTo() with a 1.5-second animation.

Scrolly story: D3 bar chart

The same data-update pattern works with D3 charts. The data key replaces the chart’s dataset with a smooth transition.

2010 global electricity generation (%). Gas and coal together supply roughly a third of the world's electricity. Renewables are barely visible at this scale — solar is a rounding error.

2015. Solar and wind have both grown meaningfully. Coal is still rising in absolute terms as global demand grows faster than clean capacity is added. The energy transition is underway but not dominant.

2020. Solar and wind together now rival nuclear. Coal peaks in share terms. The cost curves for solar have crossed every optimistic projection made a decade earlier.

2024. Solar overtakes coal in new capacity additions for the first time. The transition is now an economic story, not just an environmental one — solar is the cheapest electricity source ever built.

How the wiring works

narrative.js
  │  Scrollama fires onStepEnter
  │  → sets data-active on step element
  │  → dispatches story:step(bubbles: true, detail: { element, index, step })
  ▼
core.js  (document-level listener)
  │  reads detail.element.dataset.update  → JSON
  │  for each { id: data } entry:
  │    instances.get(id) → { entry, el, instance }
  │    entry.update(el, data, instance)
  ▼
Adapter update functions
  Leaflet → map.flyTo([lat, lng], zoom, { duration: 1.5 })
  D3      → chart.update(data)  (built-in transition: 600ms)
  ECharts → instance.setOption(data, false)  (merge mode)

Adding update support to a custom D3 chart

When you register a custom chart type, return an update method from the factory:

registerD3Chart('timeline', (el, data, options) => {
  // … render initial state …

  return {
    update(newData) {
      // Apply newData with transitions
    }
  };
});

Then core.js will route data-update JSON to chart.update() automatically.

Interactive Charts with ECharts and D3

2026-02-26T00:00:00+00:00

Two charting libraries are available out of the box: Apache ECharts for high-level declarative charts, and D3 for fully custom visualisations. Both are loaded on demand — only when [data-viz] or [data-d3] elements appear in the post.

ECharts

Use data-viz="echarts" with a data-options JSON attribute to embed any ECharts chart. The full ECharts option schema is supported.

Bar chart

Line chart

How it works

The renderEChart adapter:

Registers the loom theme (palette + text styles matching the site’s CSS variables)
Calls echarts.init(el, 'loom')
Attaches a ResizeObserver so charts resize with their container
Returns the chart instance for potential scrolly updates

The full ECharts options object is passed directly to chart.setOption(), so anything from the ECharts docs works without any wrapper configuration.

D3

Use data-d3="type" with a data-options JSON attribute containing a data array.

Built-in: bar chart

Built-in: line chart

Built-in: force graph

The force graph above shows the dependency structure of the theme’s visualization system.

Adding custom chart types

Register a new D3 chart type from a post HTML block or a separate JS file. The factory receives the container element, the data array, and the remaining options, and must return an object with an update(newData) method.

import { registerD3Chart } from '/assets/js/viz/d3.js';

registerD3Chart('scatter', (el, data, options) => {
  const d3 = window.d3;
  const { width, height } = el.getBoundingClientRect();

  const svg = d3.select(el)
    .append('svg')
    .attr('width', width).attr('height', height);

  // … draw circles …

  return {
    update(newData) {
      // re-render with newData
    }
  };
});

Then use it in the post:

 data-d3="scatter" style="height:320px"
     data-options='{"data":[{"x":1,"y":2},{"x":3,"y":4}]}'>

The factory pattern means each chart type is entirely self-contained — it owns its own scales, axes, and update logic. The registry just dispatches to the right factory at render time, and stores the returned instance for scrolly updates.

HOWTO

2026-02-25T00:00:00+00:00

Loom — Theme Reference

A complete reference for building, configuring, and writing content for the Loom Jekyll theme.

1. Prerequisites

Tool	Required version	Check
Ruby	3.3	`ruby -v`
Bundler	any recent	`bundler -v`
Node.js	20	`node -v`
npm	bundled with Node 20	`npm -v`

Install Ruby gems:

bundle install

Install Node packages:

npm install

2. Local development

Two processes run in parallel during development.

Terminal 1 — build CSS and JavaScript (Vite):

npm run dev

Vite watches src/main.css and src/main.js, rebuilds to assets/built/ on change.

Terminal 2 — run Jekyll:

bundle exec jekyll serve --livereload

Site is available at http://localhost:4000.

Note on search: Pagefind requires a completed _site/ directory to index. Search will return no results in local development unless you run the indexer manually after a full build:
npm run build && bundle exec jekyll build && npx pagefind --site _site
Then start the Jekyll server pointing at the already-built _site/:
bundle exec jekyll serve --skip-initial-build

3. Configuration

All site-wide settings live in _config.yml.

Core identity

title: LoomCollective
description: Clean typography, dark mode, computational essays.
url: "https://loomcollective.ai"   # Full URL including scheme, no trailing slash
baseurl: ""                        # Empty for apex domains; "/path" for subpaths
author: Your Name
lang: en

Permalink and pagination

permalink: /:title/                # Post URLs: /my-post-slug/
future: true                       # Publish posts with future dates

pagination:
  enabled: true
  per_page: 12
  permalink: "/page/:num/"
  title: ":title — page :num"
  trail:
    before: 2
    after: 2

# Header — main nav links
navigation:
  - title: Home
    url: /
  - title: Topics
    url: /topics/
  - title: Archive
    url: /archive/

# Footer — secondary links (About, RSS, etc.)
secondary_navigation:
  - title: About
    url: /about/
  - title: RSS
    url: /feed.xml

twitter: your_handle      # X/Twitter username only, no @
facebook: your_page       # Facebook page name

Both are optional — remove the key or leave blank to hide the icon in the footer.

Analytics

analytics_token: ""       # Cloudflare Web Analytics token

See §10 Analytics for setup.

Comments

giscus:
  repo: ""                # Owner/repo — e.g., pauldhobson/loomcollective
  repo_id: ""             # From giscus.app
  category: "Announcements"
  category_id: ""         # From giscus.app

See §9 Comments for setup.

Archive pages

jekyll-archives:
  enabled:
    - categories          # Generates /topic/:name/ pages
    - tags                # Generates /tag/:name/ pages
  layouts:
    category: topic
    tag: tag
  permalinks:
    category: /topic/:name/
    tag: /tag/:name/

Default front matter

defaults:
  - scope:
      path: "_posts"
    values:
      layout: post
      image: /assets/images/og-default.webp   # Fallback OG image
  - scope:
      path: "_pages"
    values:
      layout: default

4. Writing posts

File naming

Create files in _posts/ following the date-slug convention:

_posts/2026-03-01-my-post-title.md

Front matter reference

---
layout: post                        # Required

# Content
title: "Post title"                 # Required
date: 2026-03-01                    # Required — matches filename date
excerpt: "One or two sentences."    # Optional — used in cards and meta description

# Taxonomy
categories: [Energy]                # Optional — one category recommended; used for /topic/ archive
tags: [solar, policy, net-zero]     # Optional — multiple tags; used for /tag/ archive

# Authorship
author: paul-hobson                 # Optional — slug from _data/authors.yml; falls back to site.author

# Images
image: /assets/images/feature.jpg   # Optional — feature image at top of post
image_alt: "Panel arrays at dusk"   # Optional — alt text for accessibility
image_caption: "Photo: Jane Doe"    # Optional — caption below image

# Display options
featured: true                      # Optional — shows in Featured section on home page
updated: 2026-03-15                 # Optional — shows "Updated" date in post header

# Series (see §11)
series: "Series Name"               # Optional — must match exactly across posts
series_order: 1                     # Optional — integer, ascending

# Features
comments: true                      # Optional — enables Giscus comments widget

# Viz library flags (see §6)
# These add body classes that trigger CDN loading.
# All are auto-detected from content too — flags just guarantee loading.
math: true
diagram: true
viz: true
d3: true
leaflet: true
geo: true
---

Post content

Posts are written in standard Markdown (Kramdown). Use any standard Markdown elements:

## Heading (auto-linked anchor)

Regular paragraph. **Bold.** _Italic._ `Inline code`.

> Blockquote text.

- Unordered list
- Item two

1. Ordered list
2. Item two

[Link text](https://example.com)

![Alt text](/assets/images/figure.jpg)

Code blocks

Language-tagged code blocks get syntax highlighting (Rouge) and a copy button automatically:

```python
def ricker(r, x):
    return r * x * (1 - x)
```

Every post automatically gets:

Tags as clickable chips
Share buttons (X/Twitter, LinkedIn, copy link)
Subscribe CTA
Giscus comments (if comments: true)
Related posts (if tag/category matches exist)
Previous / next post navigation

5. Computational essays

Essays use a three-column layout: sticky table of contents (left), content (centre), sidenotes (right). The layout collapses responsively to two columns on tablets and one column on mobile.

Front matter

---
layout: essay       # Required — enables 3-column layout, TOC, sidenotes, progress bar
title: "Essay title"
date: 2026-03-01
excerpt: "Summary."
categories: [Mathematics]
tags: [ecology, population-dynamics]
image: /assets/images/essay-hero.jpg
image_alt: "Description"
image_caption: "Caption"
series: "Series Name"
series_order: 2
comments: true
updated: 2026-03-15

# Viz flags — set all that apply
math: true
viz: true
story: true         # Loads Scrollama for scrollytelling sections
---

Built automatically from all ## h2 and ### h3 headings in the content. No markup required.

To exclude a heading from the TOC:

 data-notoc>This heading is excluded

Sidenotes

Tufte-style margin notes. On desktop they appear in the right column; on mobile they appear inline.


  The Ricker model class="sidenote-anchor" data-sn="1"> was originally
  developed for salmon population studies.

 class="sidenote" data-sn="1">
  Ricker, W.E. (1954). Stock and Recruitment. J. Fish. Res. Board Can. 11(5):559–623.

The data-sn attribute links anchor to note — use the same integer for both. Numbers are displayed automatically.

Endnotes / references

Inline elements are collected and rendered as a numbered reference list at the end of the essay.


  This was described by Lorenz data-cite="Lorenz, E.N. (1963). Deterministic nonperiodic flow.">
  as sensitive dependence on initial conditions.

If the data-cite value starts with http:// or https://, it renders as a hyperlink.

Callouts

 class="callout callout-note">
   class="callout-icon">💡
   class="callout-body">
    Key insight or tip.



 class="callout callout-warning">
   class="callout-icon">⚠️
   class="callout-body">
    Something to watch out for.
  


 class="callout callout-definition">
   class="callout-icon">📖
   class="callout-body">
    Term: Definition text.
  


 class="callout callout-takeaway">
   class="callout-icon">✓
   class="callout-body">
    Key takeaway from this section.

Scrollytelling

Requires story: true in front matter.

A story section pins a visualisation in the viewport while narrative steps scroll past. Each step can update the pinned visualisation.

 class="story-section">
   class="story-sticky">
     class="story-graphic">
      
       data-leaflet id="city-map" style="height:100%"
           data-lat="51.505" data-lng="-0.09" data-zoom="10">

    


  

   class="story-steps">
    
     class="story-step" data-step="0"
         data-update='{"city-map": {"lat": 51.505, "lng": -0.09, "zoom": 10}}'>
      London. Population 9 million.
    

     class="story-step" data-step="1"
         data-update='{"city-map": {"lat": 48.856, "lng": 2.352, "zoom": 12}}'>
      Paris. Population 11 million.

The data-update JSON maps element IDs to update payloads. Keys are element IDs; values are adapter-specific (see each visualisation type below).

Arrow keys navigate between steps.

Reading progress bar

Added automatically to essay pages. A 2px accent-coloured bar at the top of the viewport fills as you scroll. Respects prefers-reduced-motion.

6. Visualisations

The viz runtime (assets/js/core.js) scans the page after load, detects which libraries are needed, fetches them from CDN, and mounts each visualisation. Nothing loads on pages that don’t use it.

Detection is automatic via element selectors ([data-viz], [data-d3], etc.) or body-class flags set by front matter. Use the front matter flags when you want to guarantee a library loads even if detection would otherwise miss it (e.g. math in a post with no $ signs but with ).

Mathematics — KaTeX

Front matter flag: math: true Auto-detection: $ signs in content, .math, .math-inline, .math-display elements.

Inline:

The logistic map is $x_{n+1} = r x_n (1 - x_n)$.

Display (centred block):

$$
x_{n+1} = r x_n (1 - x_n)
$$

LaTeX delimiters also supported:

Inline: \( \sigma = \sqrt{\text{Var}(X)} \)

Display: \[ E[X] = \mu \]

Code blocks are excluded from rendering — KaTeX never processes content inside ` or ``` fences.

Diagrams — Mermaid

Front matter flag: diagram: true Auto-detection: .mermaid elements, code.language-mermaid blocks.

Use a fenced code block with the mermaid language tag:

```mermaid
graph TD
    A[Raw data] --> B[Preprocessing]
    B --> C{Valid?}
    C -->|Yes| D[Model]
    C -->|No| E[Reject]
    D --> F[Output]
```

Other supported Mermaid diagram types:

```mermaid
sequenceDiagram
    User->>Server: POST /api/data
    Server-->>User: 200 OK
```

```mermaid
gantt
    title Project Timeline
    dateFormat YYYY-MM-DD
    section Research
    Literature review  :a1, 2026-01-01, 30d
    section Writing
    First draft        :after a1, 20d
```

The theme is automatically set to Mermaid’s dark or default based on the current colour scheme.

Charts — ECharts

Front matter flag: viz: true Auto-detection: [data-viz] elements.

Pass the full ECharts option object as JSON in data-options. The loom theme is pre-registered with accent colours matching the site palette.

Bar chart:

 data-viz="echarts" style="height:320px" data-options='{
  "tooltip": {"trigger": "axis"},
  "xAxis": {"type": "category", "data": ["Coal", "Gas", "Solar", "Wind"]},
  "yAxis": {"type": "value", "name": "GW"},
  "series": [{"type": "bar", "data": [102, 87, 230, 116]}]
}'>

Line chart:

 data-viz="echarts" style="height:300px" data-options='{
  "tooltip": {"trigger": "axis"},
  "xAxis": {"type": "category", "data": ["2020", "2021", "2022", "2023", "2024"]},
  "yAxis": {"type": "value"},
  "series": [{"type": "line", "smooth": true, "data": [1.2, 1.8, 2.6, 3.9, 5.1]}]
}'>

Scrolly update:

Give the element an id, then reference it in each story step’s data-update:

 data-viz="echarts" id="energy-chart" style="height:300px" data-options='{
  "xAxis": {"type": "category", "data": ["Coal", "Gas", "Solar"]},
  "yAxis": {"type": "value"},
  "series": [{"type": "bar", "data": [102, 87, 12]}]
}'>



 class="story-step" data-step="1"
     data-update='{"energy-chart": {"series": [{"data": [80, 60, 230]}]}}'>
  By 2030, solar overtook both fossil fuels.

The data-update value is passed directly to ECharts setOption(), so any partial update supported by ECharts works here.

Charts — D3

Front matter flag: d3: true Auto-detection: [data-d3] elements.

D3 loads a selective ~120 KB bundle (selection, scale, axis, array, shape, force, drag, transition) via dynamic import — only on pages that use it.

Three built-in chart types:

Horizontal bar chart:

 data-d3="bar" style="height:300px" data-options='{
  "data": [
    {"label": "Solar", "value": 230},
    {"label": "Wind",  "value": 116},
    {"label": "Hydro", "value": 37}
  ]
}'>

Optional: "color": "#F0177A" in options overrides bar colour.

Line chart:

 data-d3="line" style="height:260px" data-options='{
  "data": [
    {"x": 2000, "value": 1.2},
    {"x": 2010, "value": 3.9},
    {"x": 2020, "value": 9.4}
  ]
}'>

Force-directed graph:

 data-d3="force" style="height:360px" data-options='{
  "data": {
    "nodes": [{"id": "A"}, {"id": "B"}, {"id": "C"}],
    "links": [{"source": "A", "target": "B"}, {"source": "B", "target": "C"}]
  }
}'>

Nodes are draggable.

Custom chart types:

 data-d3="scatter" style="height:300px"
     data-options='{"data": [{"x": 1, "y": 2}, {"x": 3, "y": 1}]}'>

Scrolly update:

 data-d3="bar" id="pop-chart" style="height:280px" data-options='{
  "data": [{"label": "1970", "value": 3.7}]
}'>



 class="story-step" data-step="1"
     data-update='{"pop-chart": {"data": [
       {"label": "1970", "value": 3.7},
       {"label": "2024", "value": 8.1}
     ]}}'>
  Population doubled in fifty years.

Ricker population model

An interactive widget with sliders for growth rate r, initial value x₀, and iterations n. Includes a time-series chart and a phase plot.

Requires: viz: true in front matter (needs ECharts).

Static widget with sliders:

 data-viz="ricker" style="height:360px;">

Scrollytelling variant (no sliders, updates from story steps):

 data-viz="ricker-scrolly">

Maps — Leaflet (no API key required)

Front matter flag: leaflet: true Auto-detection: [data-leaflet] elements.

 data-leaflet style="height:400px"
     data-lat="51.505"
     data-lng="-0.09"
     data-zoom="13">

Tile presets (data-tiles attribute):

Value	Tiles
`osm` (default)	OpenStreetMap
`carto`	CartoDB Positron (light, minimal)
`carto-dark`	CartoDB Dark Matter
`stadia`	Stadia Alidade Smooth

Dark mode automatically swaps the tile layer to carto-dark.

Markers:

 data-leaflet style="height:400px"
     data-lat="51.505" data-lng="-0.09" data-zoom="12"
     data-tiles="carto"
     data-markers='[
       {"lat": 51.505, "lng": -0.09, "label": "London"},
       {"lat": 51.524, "lng": -0.13, "label": "King's Cross"}
     ]'>

Scrolly update (fly to new position):

 data-leaflet id="city-map" style="height:100%"
     data-lat="51.505" data-lng="-0.09" data-zoom="10">



 class="story-step" data-step="0"
     data-update='{"city-map": {"lat": 51.505, "lng": -0.09, "zoom": 10}}'>
  Greater London.


 class="story-step" data-step="1"
     data-update='{"city-map": {"lat": 48.856, "lng": 2.352, "zoom": 12, "animate": true}}'>
  Paris.

animate: true (default) smoothly flies to the new position. Set false for an instant jump.

Maps — Mapbox GL (requires API token)

Front matter flag: geo: true Auto-detection: [data-map] elements.

Token setup — add your public token to _config.yml:

mapbox_token: "pk.eyJ..."

This is injected as window.MAPBOX_TOKEN automatically by _includes/head.html on every page. For a token you don’t want in source control, use a GitHub Actions secret instead (see §17).

Or pass per-element to override the global token:

 data-map="calgary" data-token="pk.eyJ..." style="height:500px;">

Preset locations:

 data-map="calgary"   style="height:400px;">

 data-map="edmonton"  style="height:400px;">


 data-map="vancouver" style="height:400px;">
 data-map="toronto"   style="height:400px;">
 data-map="world"     style="height:400px;">

Custom centre and zoom:

 data-map="custom" style="height:400px;"
     data-center="-113.5,51.0"
     data-zoom="10">

data-center is longitude,latitude (note order — Mapbox convention).

For token-free interactive maps, prefer Leaflet above.

7. Search

Search is powered by Pagefind, which indexes the built _site/ directory at CI time and ships the index as static files alongside the site. No server is required.

How it works

Jekyll builds the site to _site/
npx pagefind --site _site crawls the HTML and writes _site/pagefind/
The deploy artifact includes the Pagefind index
At runtime, the search component dynamically imports /pagefind/pagefind.js on first open
Searches run entirely client-side against the local index

UI

Search button in the header (magnifying glass icon)
Keyboard shortcut: ⌘K (Mac) or Ctrl+K (Windows / Linux)
Close: ESC key or click outside the panel
Results show title + highlighted excerpt
Matched terms are highlighted in pink (the accent colour)

Using search locally

After a full jekyll build, run Pagefind and then serve the already-built site:

npm run build
bundle exec jekyll build
npx pagefind --site _site
bundle exec jekyll serve --skip-initial-build

Browse to http://localhost:4000 and search will work.

Running jekyll serve (without --skip-initial-build) overwrites _site/ and removes the Pagefind index. Always build first, then serve.

Excluding content from the index

Pagefind indexes all HTML by default. To exclude a section:

 data-pagefind-ignore>
  This content will not appear in search results.

To exclude an entire page, add to its front matter:

---
exclude_from_search: true
---

Then add a hook in _plugins/ or a Pagefind config file — see Pagefind docs.

CI integration

The npx pagefind --site _site step in .github/workflows/deploy.yml runs automatically after jekyll build. No additional configuration is needed for deployment.

Defined in _config.yml under navigation:. Active state is applied automatically when page.url matches the item URL.

navigation:
  - title: Home
    url: /
  - title: Topics
    url: /topics/
  - title: Archive
    url: /archive/
  - title: About
    url: /about/

Defined in _config.yml under secondary_navigation::

secondary_navigation:
  - title: About
    url: /about/
  - title: Privacy
    url: /privacy/
  - title: RSS
    url: /feed.xml

The footer Topics column is populated automatically from the six most-used categories.

The header collapses to a hamburger on small screens. The drawer opens/closes with the hamburger button and also closes on ESC or clicking outside.

9. Comments

Comments use Giscus, backed by GitHub Discussions. Comments are stored in your repo’s Discussions tab — no third-party database.

Setup

Enable Discussions on your GitHub repo (Settings → General → Features → Discussions).
Install the Giscus app and grant it access to your repo.
Go to giscus.app, enter your repo, select a discussion category, and copy the generated values.

Configuration

Add the values to _config.yml:

giscus:
  repo: "pauldhobson/loomcollective"    # owner/repo
  repo_id: "R_kgDOJ5..."                # from giscus.app
  category: "Announcements"
  category_id: "DIC_kwDOJ5..."          # from giscus.app

Enabling per post

Add comments: true to any post or essay front matter:

---
layout: post
title: "My Post"
comments: true
---

Comments will not appear on posts without comments: true, even if Giscus is configured.

Dark mode

The Giscus widget automatically follows the site’s colour scheme. When you toggle dark mode, a postMessage is sent to the Giscus iframe to update its theme in real time.

10. Analytics

The theme is wired for Cloudflare Web Analytics, which is privacy-respecting and free on Cloudflare’s free plan.

Setup

Create a Cloudflare account if you don’t have one.
Go to Websites → add your domain (or use Cloudflare Pages hosting).
Go to Analytics & Logs → Web Analytics → add your site.
Copy the analytics token (a long hex string).

Configuration

Paste the token into _config.yml:

analytics_token: "abc123def456..."

The script tag is only injected when the token is non-empty, so leaving it blank disables analytics entirely for local development.

11. Series

The series system groups related posts with a numbered navigation box that appears at the top of each post in the series.

Setup

Add series and series_order to each post’s front matter. The series name must match exactly across all posts (case-sensitive):

# Post 1
---
series: "Building Loom"
series_order: 1
---

# Post 2
---
series: "Building Loom"
series_order: 2
---

The navigation box appears automatically when at least two posts share the same series value. The current post is highlighted with a pink number; other posts are links.

Notes

series_order must be an integer.
Posts do not need to be numbered consecutively — gaps are fine.
A post can only belong to one series.

Both are included automatically on every post and essay page.

Shows up to three posts below the content. Scoring algorithm:

+1 point for each matching tag
+1 point if the post shares the same primary category

Posts with the highest score appear first. If no related posts exist (score = 0 for all), the section is hidden.

To improve related post quality: use consistent, specific tags. A post tagged [solar, policy, net-zero] will relate well to other posts with any of those tags.

A horizontal bar with a short description and an RSS link. The description is hardcoded in _includes/subscribe-cta.html — edit that file to change the copy.

13. RSS and sitemap

Both are generated automatically by Jekyll plugins — no configuration required beyond having the plugins in Gemfile (they are already there).

Output	URL	Plugin
Atom feed	`/feed.xml`	`jekyll-feed`
XML sitemap	`/sitemap.xml`	`jekyll-sitemap`

The sitemap includes all posts, pages, and archive pages. The feed includes the 10 most recent posts with full content.

14. Dark mode

How it works

Dark mode is stored in localStorage under the key loom-dark ('1' = dark, '0' = light). On first visit with no saved preference, the browser’s system preference (prefers-color-scheme) is used.

An inline

Loom

Documenting Fieldwork: Photos, Video, and Embedded Media

Photo galleries

Photo carousels

Native video

Parameters

YouTube and Vimeo embeds

Callout blocks

Co-authorship

Glaciers I Have Known

The Swiss Alps: two glaciers above Zermatt

Findelen glacier

Gornergletscher

France: Mer de Glace

Canada: the Rockies

Peyto Glacier

Athabasca Glacier and the Columbia Icefield

The scroll tour

A note on the maps

Interactive Maps with Mapbox GL JS

Standalone maps

Style overrides

Scrolly story: a tour of the BC coast

How the token flows

Style overrides

Introducing Loom

Introducing Loom

What is Loom?

The Stack

Visualisation Runtime

Dark Mode

Speaker Notes

Thank you

Scrollytelling with Maps and Charts

Standalone Leaflet map

Scrolly story: map flyTo

Scrolly story: D3 bar chart

How the wiring works

Adding update support to a custom D3 chart

Interactive Charts with ECharts and D3

ECharts

Bar chart

Line chart

How it works

D3

Built-in: bar chart

Built-in: line chart

Built-in: force graph

Adding custom chart types

HOWTO

Loom — Theme Reference

1. Prerequisites

2. Local development

3. Configuration

Core identity

Permalink and pagination

Navigation menus

Social links

Analytics

Comments

Archive pages

Default front matter

4. Writing posts

File naming

Front matter reference

Post content

Code blocks

Post footer

5. Computational essays

Front matter

Table of contents

Sidenotes

Endnotes / references

Callouts

Scrollytelling

Reading progress bar

6. Visualisations

Mathematics — KaTeX

Diagrams — Mermaid

Charts — ECharts