Skip to content
Herald Docs

Demo GIF Workflow

Demo GIFs are recorded from synthetic data so documentation and project media can be refreshed without touching a real mailbox. Most canonical tapes use VHS’s Builtin Solarized Dark theme, while selected showcase tapes use Dark Pastel, Red Alert, and Builtin Pastel Dark to show Herald under different terminal profiles.

Prerequisites

Section titled “Prerequisites”
Terminal window
brew install vhs ffmpeg

Regenerate All GIFs

Section titled “Regenerate All GIFs”
Terminal window
make docs-media


# GIF-only refresh:
HERALD_DOC_MEDIA_ONLY=demo-gifs make docs-media

Demo tapes live in demos/*.tape. Canonical GIFs are written to assets/demo/*.gif, docs-facing copies are written to docs/public/demo/*.gif, and still screenshots are written to docs/public/screenshots/*.png. Run media generation from the repository root because the tapes reference ./bin/herald. Showcase tapes use ./bin/herald --demo --demo-keys so viewers can see shortcuts such as S, ?, 2, 3, G, Settings Sync & Cleanup launchers, Calendar navigation, invitation import, preview selection, horizontal preview movement, and full-screen preview. The image-preview tape forces -image-protocol=kitty against Step 5: View inline images in full screen so the generated media can exercise the Kitty/Ghostty rendering path once the capture stack can render raster blocks.

Current Story Set

Section titled “Current Story Set”

The v0.7 docs front door now leads with chat, AI settings, range selection, and Compose screenshots while the existing v0.6 demo GIFs continue to cover Calendar and preview workflows. Each tape should remain short enough to understand without narration.

  • overview.tape shows Timeline, cleanup grouping, Contacts, and Calendar.
  • calendar-workspace.tape shows Week, Day, 3-Day, Agenda, Search, Detail, and Event Edit.
  • calendar-invitation.tape shows importing an .ics mail invitation into Calendar with duplicate handling.
  • preview-selection-images.tape shows linked image reveal, full-screen preview, and rich preview selection/copy.
  • compose-preserved-reply.tape shows reply Compose with preserved original context and Markdown preview.
  • guided-tour-dark-pastel.tape, cleanup-rules-red-alert.tape, and focused AI/search/MCP tapes keep older headline flows visible.

Theme gallery screenshots are regenerated separately because they need one --demo -theme <name> launch per built-in palette:

Terminal window
scripts/regenerate-theme-screenshots.sh

Themed Herald guided tour

VHS demo tape generation command

Recording Guidance

Section titled “Recording Guidance”
  • Keep tapes focused and under 30 seconds.
  • Use ./bin/herald --demo unless the demo explicitly needs live provider behavior.
  • Use Builtin Solarized Dark for broad documentation tapes. Use Dark Pastel, Red Alert, or Builtin Pastel Dark only for focused showcase media where theme comparison is the point.
  • Add --demo-keys to presentation tapes that need the viewer to see shortcut input; leave it off for normal documentation screenshots.
  • Prefer terminal sizes that match documentation screenshot states, such as 120x40, 80x24, and 50x15.
  • For inline image demos, use the Creative Commons sampler fixture and force -image-protocol=kitty; reject captures that show raw protocol text or hide the image area.
  • If the installed VHS/ttyd stack cannot render Kitty or iTerm2 raster blocks, keep the tape as key-flow coverage and record native Ghostty/Kitty evidence separately instead of committing a blank raster capture. Default make docs-media skips raster image-preview media; set HERALD_DOC_MEDIA_INCLUDE_RASTER=1 only after confirming the local capture stack paints the embedded image.
  • After changing a visible feature, regenerate the relevant tape.
  • After changing theme roles, Timeline chrome, or preview header/body colors, run scripts/regenerate-theme-screenshots.sh; use HERALD_THEME_SCREENSHOT_VIEW=timeline or HERALD_THEME_SCREENSHOT_VIEW=preview only when refreshing a single gallery lane.
Section titled “Related Pages”