Example 23: Counter Source

The Same Gallery, a Different Way

The Basic Demo renders photo cards using a counter step. This page renders the same photos using include templates — one template token expands to all cards automatically.

The data is restructured from flat numbered keys to named TOML sections, which suits the template approach better.

Desert

Sand dunes at midday

Forest

Misty morning in the woods

Mountain

Snow-capped peaks at dawn

Ocean

Pacific coast waves

Sunset

Golden hour at the beach

How This Was Built

The counter approach in Basic Demo uses gallery.toml with flat numbered keys (title1, title2, …) and a counter step to number each block expansion. Three 🪹photo-card tokens in the page expand to three cards; the counter fills in the numbers; the data step resolves them.

This page uses gallery-named.toml with named sections — one TOML section per photo ([sunset], [ocean], etc.) — and a template rendering step. A single 🖼️named-photo-card token expands automatically to one card per section in the TOML file. The page template never needs to know how many items there are.

The data restructuring is the only real difference between the two approaches. The output is identical; only the mechanism changes.

When to Use Each Approach

Counter source Include templates
Page author controls the number of instances — you place the block N times Data controls the number of instances — one token, N results
Items can be mixed with other blocks or text between repetitions All items expand from a single token placement
Data is flat: title1, title2, title3 Data is structured: named sections [sunset], [ocean]
Adding an item means editing the page and the data Adding an item means editing only the data file
Works well when number of items is fixed by the page design Works well when number of items is driven by the data

Neither approach is always better. Counter source gives explicit control to the page author. Include templates delegate that control to the data file.

See Example 11: Include Templates for a full exploration of the template rendering approach.