# How to Create Guided Stories and Views in Archify: A Complete Tutorial

> Learn to create guided stories and views in Archify with this tutorial. Discover how Archify transforms static diagrams into interactive narratives using JSON data and runtime UI.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: tutorial
- Published: 2026-08-06

---

**Archify converts static diagrams into interactive, step-by-step guided stories using a JSON data definition, build scripts that inject that data into HTML templates, and a runtime UI that renders navigation controls.**

The guided stories feature in the **tt-a1i/archify** repository lets you transform any diagram or collection of views into a narrative experience. Viewers can click through beats, see captions and progress indicators, and copy view metadata. This article walks through the three-layer architecture: data definition, build-time generation, and runtime rendering.

---

## What Are Guided Stories in Archify?

A **guided story** is a sequential presentation of diagram views. Each "beat" in the story displays a specific view, shows a title and optional note, and provides navigation controls. The system supports both standalone guide pages and embedded playback within galleries.

The implementation spans four key source files:

- [`scripts/guide-template.html`](https://github.com/tt-a1i/archify/blob/main/scripts/guide-template.html) — HTML scaffold with placeholders
- `scripts/build-guide.mjs` — CLI tool for standalone guides
- `scripts/build-gallery.mjs` — CLI tool for gallery integration
- [`experiments/mco-showcase/mco-runtime.html`](https://github.com/tt-a1i/archify/blob/main/experiments/mco-showcase/mco-runtime.html) — runtime CSS and JavaScript

---

## Step 1: Define the Story Data

Create a JSON structure where each entry represents one story beat. The required fields are:

| Field | Purpose |
|-------|---------|
| `viewId` | Unique identifier for the view |
| `title` | Short caption displayed in the UI |
| `note` | Optional description or instruction |
| `viewCount` | Number of times this view appears (enables playback detection) |

Example entry:

```json
{
  "viewId": "v1",
  "title": "Introduce the core component",
  "note": "Highlight its responsibilities",
  "viewCount": 1
}

```

Archify provides a helper that extracts this metadata from recipe files. The `publicGuideData()` function (referenced in the build scripts) collects view information automatically.

---

## Step 2: Build the Guided Story Page

Archify ships two CLI scripts for generating guided story outputs.

### `scripts/build-guide.mjs`

This script creates a standalone guide page. It:

1. Reads JSON data from your recipe
2. Substitutes it into [`scripts/guide-template.html`](https://github.com/tt-a1i/archify/blob/main/scripts/guide-template.html)
3. Writes the result to [`docs/guide.html`](https://github.com/tt-a1i/archify/blob/main/docs/guide.html)

The substitution happens at a specific placeholder. In `scripts/build-guide.mjs` at line 14, the script replaces `[[GUIDE_JSON]]` with actual data:

```javascript
// scripts/build-guide.mjs (line 14 context)
// Injects guideData into the template placeholder

```

The template contains this injection point at line 201:

```html
<!-- scripts/guide-template.html#L201 -->
<script id="guide-data" type="application/json">[[GUIDE_JSON]]</script>

```

At runtime, the page parses this element. Line 205 of the template shows the parsing logic:

```javascript
var recipes = JSON.parse(document.getElementById('guide-data').textContent);

```

Run the builder from your repository root:

```bash
node scripts/build-guide.mjs

```

### `scripts/build-gallery.mjs`

For gallery integration, this script adds a `guidedPlayback` flag when a view has `viewCount > 0`. The flag is set at line 308 of `scripts/build-gallery.mjs`:

```javascript
// scripts/build-gallery.mjs#L308
// Adds guidedPlayback: true when viewCount is non-zero

```

Usage:

```bash
node scripts/build-gallery.mjs path/to/your/recipe.json

```

The gallery automatically enables playable guided stories for any diagram with valid story data.

---

## Step 3: Runtime UI Rendering

When the generated page loads, Archify's front-end transforms the JSON into interactive controls. The runtime code resides in [`experiments/mco-showcase/mco-runtime.html`](https://github.com/tt-a1i/archify/blob/main/experiments/mco-showcase/mco-runtime.html).

### Navigation Controls

The UI includes:

- **Toolbar buttons** — play/pause, next, previous, and stop controls per story beat
- **Progress bar** — visual indicator of current position (`.guided-view-progress`)
- **Captions** — title and note display (`.guided-story-caption`)
- **Metadata area** — copy-able view IDs and notes

### CSS Architecture

The `.guided-views` family of CSS classes controls visibility and styling. Key implementation points from [`mco-runtime.html`](https://github.com/tt-a1i/archify/blob/main/mco-runtime.html):

- **Container definition** — line 2204 introduces the guided views container
- **Button styling** — begins at line 916 with hover and active states
- **Blueprint preset** — line 2229 shows preset-specific customization: `html[data-preset="blueprint"] .guided-views button`

### State Behaviors

| Behavior | Implementation |
|----------|---------------|
| Play story | `data-playing="true"` attribute added to `.guided-views` reveals controls |
| Motion pause | `html[data-motion="still"]` selector keeps UI visible (line 823) |
| Caption toggle | `[hidden]` attribute controlled by story state (line 2310) |

---

## Complete Workflow Example

Follow these steps to create and view a guided story:

**1. Add metadata to your recipe:**

```json
{
  "views": [
    {"viewId":"v1","title":"Introduce the core component","note":"Highlight its responsibilities","viewCount":1},
    {"viewId":"v2","title":"Show data flow","note":"Arrow from A to B","viewCount":1}
  ]
}

```

**2. Generate the guide:**

```bash
node scripts/build-guide.mjs

```

**3. Open [`docs/guide.html`](https://github.com/tt-a1i/archify/blob/main/docs/guide.html) in a browser.** Click the play button to step through views.

**4. Optional: embed in a gallery:**

```bash
node scripts/build-gallery.mjs my-recipe.json

```

---

## Key Source Files Reference

| File | Purpose | Line Markers |
|------|---------|--------------|
| [`scripts/guide-template.html`](https://github.com/tt-a1i/archify/blob/main/scripts/guide-template.html) | HTML scaffold with `[[GUIDE_JSON]]` placeholder | L201, L205 |
| `scripts/build-guide.mjs` | CLI injection script | L14 |
| `scripts/build-gallery.mjs` | Gallery integration with `guidedPlayback` flag | L308 |
| [`experiments/mco-showcase/mco-runtime.html`](https://github.com/tt-a1i/archify/blob/main/experiments/mco-showcase/mco-runtime.html) | Runtime UI (CSS/JS) | L2204, L916, L823, L2229, L2310 |
| [`docs/guide.html`](https://github.com/tt-a1i/archify/blob/main/docs/guide.html) | Generated output file | — |

---

## Summary

- **Data layer** — JSON with `viewId`, `title`, `note`, and `viewCount` fields defines each story beat
- **Build layer** — `build-guide.mjs` (standalone) and `build-gallery.mjs` (gallery) inject data into templates
- **Runtime layer** — CSS classes (`.guided-views`) and JavaScript in [`mco-runtime.html`](https://github.com/tt-a1i/archify/blob/main/mco-runtime.html) render interactive controls
- **Integration** — gallery builds automatically detect stories via the `guidedPlayback` flag when `viewCount` exceeds zero

The `[[GUIDE_JSON]]` placeholder system in [`scripts/guide-template.html`](https://github.com/tt-a1i/archify/blob/main/scripts/guide-template.html) provides a clean separation between data and presentation, letting you author stories without touching HTML directly.

---

## Frequently Asked Questions

### How do I enable guided playback in a gallery?

Run `scripts/build-gallery.mjs` with your recipe path. The script automatically sets `guidedPlayback: true` (line 308) for any view where `viewCount > 0`. The gallery UI then displays play controls for those diagrams.

### Can I customize the appearance of guided story controls?

Yes. The runtime CSS in [`experiments/mco-showcase/mco-runtime.html`](https://github.com/tt-a1i/archify/blob/main/experiments/mco-showcase/mco-runtime.html) supports preset-based styling. For example, the "blueprint" preset customizes button radius and colors via `html[data-preset="blueprint"] .guided-views button` (line 2229). Modify these rules or add your own preset selectors.

### What happens if a view has `viewCount` set to zero?

Views with `viewCount: 0` or no `viewCount` field are excluded from guided story generation. The `build-gallery.mjs` script only activates `guidedPlayback` when `viewCount` is non-zero, following the logic at line 308 of the source code.

### Where is the story data actually stored in the generated HTML?

The JSON is embedded in a `<script>` element with `id="guide-data"` and `type="application/json"`. The `build-guide.mjs` script replaces the `[[GUIDE_JSON]]` placeholder at line 201 of [`scripts/guide-template.html`](https://github.com/tt-a1i/archify/blob/main/scripts/guide-template.html). The runtime parses this element at line 205 using `JSON.parse(document.getElementById('guide-data').textContent)`.