How to Create Guided Stories in Archify Viewer: A Complete Implementation Guide

To create guided stories in Archify viewer, set guidedPlayback: true in your view metadata, include the UI template from guide-template.html, and instantiate the viewer with the guided: true option.

A guided story is an interactive, step-by-step walkthrough of a visual document built from beats—individual view states stored in the document's metadata. The Archify viewer renders these beats through dedicated UI controls defined in the source code, enabling audiences to navigate a curated narrative.

Prerequisites: Understanding Guided Story Architecture

Guided stories in tt-a1i/archify rely on three integrated components:

• Metadata flags that mark views as story beats
• HTML/CSS templates that render the story controls
• JavaScript initialization that activates story mode

The viewer reads story data from your document's JSON metadata (typically under data.story) and automatically wires navigation logic when the guided option is enabled.

Step 1: Flag Views for Story Inclusion

First, annotate each view that belongs to your guided story by setting guidedPlayback: true in the view definition. The build script in scripts/build-gallery.mjs evaluates this flag during gallery generation.

According to the source code around line 308, the script automatically assigns guidedPlayback based on view count:

// archify/scripts/build-gallery.mjs (line 308)
guidedPlayback: entry.viewCount > 0,

For manual control, explicitly define the flag in your view JSON:

{
  "id": "view-01",
  "title": "Introduction",
  "guidedPlayback": true,
  "content": { }
}

Step 2: Include the Story UI Template

The guided story interface is defined in scripts/guide-template.html. This file contains the toolbar markup and CSS that the viewer toggles during story playback.

Key CSS Classes in guide-template.html

Class	Purpose
.guided-view-play	Play/pause button state
.guided-view-stop	Navigation buttons with data-story-link attributes
.guided-story-caption	Caption area for beat titles and descriptions
.guided-view-progress	Visual progress indicator

The source CSS implements arrow indicators and styling states:

/* archify/scripts/guide-template.html – UI styles */
.guided-view-play[aria-pressed="true"] { 
  background: var(--toolbar-hover); 
}

.guided-view-stop[data-story-link="forward"]::after { 
  content: '\2192'; 
}

.guided-story-caption strong { 
  color: var(--toolbar-text); 
  font-size: .6875rem; 
}

Copy this markup into your page (the viewer will unhide and populate it):

<div class="guided-views" hidden>
  <button id="guided-view-prev" class="guided-view-stop" 
          data-story-link="reverse">Prev</button>
  <button id="guided-view-play" class="guided-view-play" 
          aria-pressed="false">Play</button>
  <button id="guided-view-next" class="guided-view-stop" 
          data-story-link="forward">Next</button>

  <div class="guided-view-progress"><span></span></div>
  <div class="guided-story-caption">
    <strong id="guided-caption-title"></strong>
    <small id="guided-caption-subtitle"></small>
  </div>
</div>

The data-story-link attribute accepts three values: "forward", "reverse", and "multiple" for different navigation behaviors.

Step 3: Instantiate the Viewer with Story Mode

Initialize ArchifyViewer from archify/archify.js and enable guided story mode:

// Example: initialise Archify viewer with a guided story
import { ArchifyViewer } from 'archify';

const viewer = new ArchifyViewer('#archify-container', {
  // Path to the compiled document (JSON/HTML bundle)
  src: './my-project/archified.json',
  // Enable guided-story mode (automatically reads `guidedPlayback`)
  guided: true,
});

// Optionally start the story programmatically
viewer.startGuidedStory();   // plays the first beat

The guided: true option triggers the viewer to scan for guidedPlayback flags and activate the story navigation system.

Auto-Start on Document Load

For immediate playback when the document is ready:

<script type="module">
  import { ArchifyViewer } from './archify/archify.js';

  const viewer = new ArchifyViewer('#viewer', {
    src: 'demo/archified.json',
    guided: true          // tells the viewer to look for guided stories
  });

  // Auto-start the story when the document loads
  viewer.on('ready', () => viewer.startGuidedStory());
</script>

Complete Working Example

This implementation combines all three steps in a single HTML page:

<!DOCTYPE html>
<html>
<head>
  <title>Archify Guided Story</title>
  <link rel="stylesheet" href="./archify/archify.css">
</head>
<body>
  <div id="viewer"></div>

  <!-- Story UI template (from guide-template.html) -->
  <div class="guided-views" hidden>
    <button id="guided-view-prev" class="guided-view-stop" 
            data-story-link="reverse">Prev</button>
    <button id="guided-view-play" class="guided-view-play" 
            aria-pressed="false">Play</button>
    <button id="guided-view-next" class="guided-view-stop" 
            data-story-link="forward">Next</button>

    <div class="guided-view-progress"><span></span></div>
    <div class="guided-story-caption">
      <strong id="guided-caption-title"></strong>
      <small id="guided-caption-subtitle"></small>
    </div>
  </div>

  <script type="module">
    import { ArchifyViewer } from './archify/archify.js';

    const viewer = new ArchifyViewer('#viewer', {
      src: 'demo/archified.json',
      guided: true
    });

    viewer.on('ready', () => viewer.startGuidedStory());
  </script>
</body>
</html>

Key Source Files Reference

File	Function	Line Reference
scripts/build-gallery.mjs	Assigns guidedPlayback during gallery build	Line 308
scripts/guide-template.html	Defines story UI markup and styles	Full file
archify/archify.js	Core viewer that reads guided flag and drives story logic	Full file
examples/web-app.html	Complete demo implementation	Full file

Summary

• Metadata: Set guidedPlayback: true on views to include them as story beats
• Template: Include the HTML/CSS from guide-template.html for navigation controls
• Initialization: Pass guided: true to ArchifyViewer and call startGuidedStory() to begin playback
• Navigation: The viewer automatically wires .guided-view-stop buttons with data-story-link attributes to step through beats

Frequently Asked Questions

What triggers the guided story UI to appear?

The presence of guided: true in the viewer configuration and at least one view with guidedPlayback: true in the document metadata. When both conditions are met, the viewer unhides the .guided-views container and populates it with beat data from data.story.

Can I customize the story navigation buttons?

Yes. The data-story-link attribute supports three values: "forward" and "reverse" for sequential navigation, and "multiple" for jump-to-point behavior. You can restyle buttons using the CSS custom properties defined in guide-template.html (e.g., --toolbar-hover, --toolbar-text).

How do I add captions to each story beat?

The viewer populates #guided-caption-title and #guided-caption-subtitle from the title and description fields of each view's metadata. Ensure your beats include these fields in the JSON definition, and the .guided-story-caption element will display them automatically.

Does the viewer support programmatic story control?

Yes. Beyond startGuidedStory(), the ArchifyViewer instance exposes methods to pause, resume, and jump to specific beats. These integrate with the .guided-view-play button state (tracked via aria-pressed) and the .guided-view-progress bar visualization.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}