Guide

Story mode

story: (1.9.4) turns an article into a reading companion and a fullscreen presentation. Its slides are the same ones the post's Web Story uses.

  • Reading bar: the time left to read, at the top or the bottom of the page.
  • Photo stage: beside the text, it shows the photograph for the paragraph being read. On a narrow screen it becomes a thumbnail in the corner.
  • Widgets: tips, numbers and quotes appear while a given passage is read. The recipe card ticks off ingredients and counts steps.
  • Presentation: fullscreen slides with a title card and a closing card, a header (logo) and a footer (promotions or an ad). It has autoplay, gestures like phone stories (tap left or right, hold to pause, swipe down to close) and five transitions.
  • Narrator: the browser's voice reads the article and highlights the paragraph it is reading, with subtitles in the presentation. The reader picks the voice and the speed. Pronunciation rules turn "250g" into "250 grams".
  • Music: a track chosen by date window, for example carols in December. It gets quieter while the narrator speaks.
  • Share: the system share sheet on phones, a menu elsewhere. A link to the Web Story. #story=3 deep links open the presentation at a slide.
  • Analytics and media keys: the presentation sends events to dataLayer, and Media Session puts play, pause and next on the lock screen.

Everything runs in the page's own scripts, written once to /assets/ssg-story/. Nothing is loaded from a third party.

Turning it on

1story: true            # every post, default settings
1story:
2  sections: [posts/recipes]       # posts (default), pages, or a content directory
3  narrator: { rate: 1, duck: 0.3 }
4  slideshow:
5    header: { logo: /media/logo.png, text: My Site, link: / }

A mapping turns story on unless it says enabled: false.

Where a page's settings come from

Each layer is laid over the one before it:

  1. the site's story:;
  2. every story.rules entry whose when matches the page, in order;
  3. the file <name>.story.yaml beside the post's source (with or without a top-level story: key);
  4. the post's own story: front matter.

Mappings merge key by key. slides, widgets, figure_skip and hide add up across layers, so a post can add one slide without repeating the site's. Any other list replaces the one before it. story: false in front matter keeps a post out.

1story:
2  rules:
3    - when: { category: recipes }          # also: tags, section, contains
4      set: { slideshow: { interval: 6s } }
5    - when: { contains: "Ingredients" }
6      set: { widgets: [{ type: recipe }] }

Keys may be written snake_case (ssg's style) or camelCase; the page script receives camelCase. With webp: true (or image_formats), a path may name the .webp the build will write. check_links accepts it when the source .jpg or .png is there, because the link check runs before the conversion. The keys inside pronounce, labels and theme are data and are passed as written. Paths such as /media/logo.png are site paths.

Options

Key What it does
content, column CSS selectors for the article text (default article) and the column that moves aside for the stage
trigger the reading line, as a fraction of the viewport (default 0.45)
safe_top space kept free under a sticky site header (96px)
transition, transition_time crossfade, slide, zoom, blur or kenburns, and its length
figures, figure_skip, figure_min_width photos in the article join the slides. true (default) takes <figure>s and paragraphs holding only a photo; all also takes a photo inside a paragraph of text or on its own, as Markdown and WordPress write them, captioned by the <em> right after it or its alt text. Then come selectors to skip and the smallest width that counts. The Presentation button appears only on a page with at least one slide
theme each key becomes --story-<key> (accent, accent_text, accent_on_dark, ink, paper, font, title_font, radius). accent_text is the accent used as text on the paper. Its default is the accent mixed half with black, which keeps a bright brand colour at 4.5:1 or better. accent_on_dark is the accent over a photo's caption and on the cards. Its default is the accent mixed 35% with white, which keeps a dark brand colour readable there (1.9.7)
progress bar, position (top or bottom), time_left, words_per_minute
stage side, width, min_width (below it: a thumbnail), hide_figures
slides {image, at, caption, alt, duration}. at is a CSS selector or text:…, the first block containing that text
widgets {at, type, stat, title, text, until}. Types: card (default), stat, quote, recipe
audio one track or a list; the first whose window holds today plays (see below)
music_volume the music's level from 0 to 1 when a track sets no volume (default 0.4)
narrator voice, rate, pitch, duck, subtitles, title, pronounce, pronounce_defaults
slideshow title, header, footer, end, autoplay, interval, loop, fit, gestures, return_to_text. The title card's image: auto takes og:image. On another host than the site's domain (staging, ssg --http) it loads from the host the page is on, and falls back to the first slide if it fails. byline: auto takes the <time> in the theme's .post-meta when there is one
share networks (facebook, x, whatsapp, telegram, linkedin, pinterest, email, copy), native
analytics prefix of the dataLayer events (default story_)
labels every text on screen: left, done, present, listen, stop, share, music…

Music by date

1story:
2  audio:
3    - { from: "12-01", to: "01-06", playlist: [/music/carol-1.mp3, /music/carol-2.mp3] }
4    - { dates: [{ from: "2026-03-22", to: "2026-04-12" }], src: /music/easter.mp3 }   # moving feasts
5    - { src: /music/ambient.mp3, volume: 0.3, loop: true }                          # the rest of the year

A window is MM-DD (and may wrap the new year) or YYYY-MM-DD. A playlist plays in random order.

Volume. A track's volume (0 to 1) sets how loud it plays, and music_volume is the level for tracks that set none (default 0.4). The reader can change it with the Music volume slider in the settings panel (the gear button). That level is remembered in their browser and wins over the configured one. While the narrator speaks, the music drops to narrator.duck of the current level (default 30%). Browsers start sound only after a click, so music begins with the presentation or the reader's Sound button. ssg ships no music. Use tracks you hold the rights to.

Pronunciation

Text is written for the eye, and a voice reading "100g" or "180°C" reads it badly. ssg ships a set of rules per language (Polish and British English for now) and uses the one matching the page's language. narrator.pronounce adds rules on top of it, or turns one off with null. narrator.pronounce_defaults: false leaves out the whole built-in set.

1story:
2  narrator:
3    pronounce:
4      "{num} blaszka|blaszki|blaszek": "{num:jedna|dwie} {word}"
5      "np.": null
In a pattern Means
{num} a number: 100, 1,5, 0.25
a space a space or none: "{num} g" matches 100g and 100 g
a|b|c any of these words

Patterns match whole words only ("{num} l" leaves "5 lat" alone), and the longest pattern wins.

In what is said Means
{num} the number as written
{num:jedna|dwie} the number in words, with 1 and a final 2 in this gender: 1 → jedna, 22 → dwadzieścia dwie (Polish only)
{word} the word the pattern's a|b|c matched, as written
a|b|c|d the form that agrees with the number before it. Polish: 1, 2–4, 5+, fractions. English: 1, other

Only the spoken text changes; the page and the subtitles keep what is written. Abbreviations the rules know (e.g., np., łyż.) do not end a sentence. The built-in sets live in internal/generator/assets/story/pronounce/. Every set's examples are tests that the browser's engine (make test-story) and the Go engine (go test ./internal/generator) must both pass.

Accessibility

  • One named region: everything story mode adds to the page (stage, widgets, reading bar, buttons, the presentation) sits in a single region named by labels.tools (default "Story").
  • Named stage: the stage is an image named after the photograph on show, or labels.stage before the first one.
  • Widgets are notes, not landmarks. They take the widget's ink colour whatever colours the site's theme gives p and h3.
  • Phone layout: below 700px the buttons show only their icons, keep their names for screen readers, and wrap inside the gutters.
  • Browsers without a voice: in a browser without a working voice (no voices installed), the narrator gives up after its first utterance fails or never starts. The presentation then keeps to its own timer and stops starting the narrator. The narrator event carries failed: true.

Events

The script dispatches ssg-story events on document. detail.type is one of:

  • open
  • slide (with index, total, kind, label and by, where by is user, narrator, timer or open)
  • complete
  • close
  • narrator
  • sound
  • share

With analytics:, each event is also pushed to dataLayer as story_<type>, and clicks on the footer's links as story_ad_click.

With Web Stories

When web_stories: also makes a story for the post, the article's Share menu links it. The AMP story then takes from the post's story: settings what AMP, which allows no script, can show. See WEB_STORIES.

Not included

  • 9:16 share pictures of each slide.
  • Music files.

The prototype made the share pictures in a headless browser; ssg does not run one.