How to Create Guided Stories with Chapters in Archify: A Complete Guide

Archify provides a built-in guided story system that walks users through sequential chapters using a JSON data structure and the viewer/guided-views.js module.

The tt-a1i/archify repository includes a guided views feature that transforms static diagrams into interactive, chapter-based narratives. By embedding a specific JSON payload and loading the viewer scripts, you can create focused presentations that highlight specific nodes and guide users through complex architectures step by step.

Understanding the Guided Story Data Structure

The foundation of every guided story is a JSON array embedded directly in your HTML page.

The JSON Schema for Chapters

Place a <script> element with the ID archify-guided-views-data anywhere inside the <body> tag. This script contains an array of chapter objects, each supporting the following fields:

• id – A unique string identifier for the chapter.
• label – The short title displayed in the chapter navigation list.
• note – Optional descriptive text shown in the caption bar during playback.
• focus – An array of node IDs that the viewer will highlight and center when the chapter activates.
• route – Optional custom navigation text for the caption bar.

The viewer/guided-views.js file parses this JSON automatically on page load and initializes the Archify.guidedViews controller.

<script id="archify-guided-views-data" type="application/json">
[
  {
    "id": "intro",
    "label": "Introduction",
    "note": "Overview of the system architecture",
    "focus": ["node-1", "node-2"]
  },
  {
    "id": "data-flow",
    "label": "Data Flow",
    "note": "How data moves between services",
    "focus": ["node-3", "node-4", "node-5"]
  },
  {
    "id": "deployment",
    "label": "Deployment",
    "note": "Deployment pipeline steps",
    "focus": ["node-6", "node-7"]
  }
]
</script>

Implementing the Guided Story Interface

Once the data is embedded, the viewer module handles all UI rendering and interaction logic.

Core Implementation in viewer/guided-views.js

The viewer/guided-views.js file contains the Archify.guidedViews class, which manages the entire guided story lifecycle. According to the source code in tt-a1i/archify, this module:

1. Queries the DOM for the archify-guided-views-data script element and parses the JSON payload.
2. Generates navigation controls with specific element IDs including guided-view-prev, guided-view-next, guided-view-play, and guided-view-chapters.
3. Renders the progress bar (guided-view-progress-bar) and caption container (guided-story-caption).

When a user selects a chapter, the module calls viewer.focus(view.focus) to execute the camera transition and updates the caption bar using internal state variables like storyCaption and storyCaptionIndex.

UI Components and State Management

The guided story operates through a finite state machine defined in the same file. The possible states include pending, playing, complete, interrupted, pinned, and reduced-motion. These states control the progress bar animation, button availability, and automatic playback timing.

The caption bar can be customized via i18n keys referenced in viewer/guided-views.js, such as viewer.guided.caption.start for the initial display text.

Step-by-Step Integration Guide

To add a guided story to your Archify diagram, follow these integration steps:

1. Embed the JSON payload – Add the <script id="archify-guided-views-data"> element to your HTML page with your chapter definitions.

2. Load required scripts – Include both the camera controller and the guided views module in your HTML head or body:

<script src="viewer/viewer-camera.js"></script>
<script src="viewer/guided-views.js"></script>

3. Verify container structure – Ensure your page includes container elements where the viewer can inject UI controls. The module creates elements with IDs like guided-view-chapters automatically, but the parent container must exist in the DOM.

4. Customize captions (optional) – Override the default i18n keys used in viewer/guided-views.js if you need localized or custom caption text.

Once loaded, the chapter navigation UI appears in the top-right corner of the diagram viewer, and users can step through chapters manually or press the play button for automatic progression.

Programmatic Control of Guided Stories

For advanced integrations, the Archify.guidedViews API exposes methods to control playback programmatically.

// Check if guided views are initialized
if (Archify.guidedViews) {
  // Jump to a specific chapter by ID
  Archify.guidedViews.selectChapter('data-flow');
  
  // Start automatic playback
  Archify.guidedViews.play();
  
  // Pause current playback
  Archify.guidedViews.pause();
}

The selectChapter method triggers the same focus logic as manual navigation, calling the internal viewer.focus() method with the chapter's node array. The play method initiates the state machine transition to playing, which advances chapters automatically according to the built-in timing configuration.

Summary

• Guided stories in Archify require a JSON payload embedded in a <script id="archify-guided-views-data"> element.
• The viewer/guided-views.js file parses this data and manages theUI controls, state machine, and camera focus transitions.
• Each chapter object must include an id, label, and focus array; optional note and route fields enhance the presentation.
• Programmatic control is available through the Archify.guidedViews API, which exposes selectChapter() and play() methods.
• Reference the scripts/guide-template.html file in the repository for a complete implementation example.

Frequently Asked Questions

What file contains the main guided story logic in Archify?

The main implementation lives in viewer/guided-views.js within the tt-a1i/archify repository. This file defines the Archify.guidedViews controller, manages the state machine, and creates the DOM elements for chapter navigation, progress indication, and caption display.

How does Archify know which nodes to highlight for each chapter?

Each chapter object in the JSON payload includes a focus array containing node ID strings. When a chapter activates, the viewer/guided-views.js module calls viewer.focus(view.focus), passing this array to the camera controller (viewer/viewer-camera.js) to execute the highlight and zoom transition.

Can I customize the text shown in the guided story caption bar?

Yes, the caption bar supports customization through internationalization keys referenced in viewer/guided-views.js. You can override keys like viewer.guided.caption.start or provide custom note fields in your chapter JSON objects, which the module renders into the guided-story-caption element during playback.

Is it possible to programmatically skip to a specific chapter without user interaction?

Yes, the Archify.guidedViews.selectChapter(chapterId) method allows direct navigation. Pass the string ID of your target chapter (as defined in the JSON id field), and the viewer immediately transitions focus to those nodes and updates the UI state accordingly.

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