# How the Web-Video-Presentation Skill Converts Articles into Interactive Presentations

> Discover how the web-video-presentation skill converts markdown articles into interactive presentations. Learn how it generates scripts, builds code, and produces engaging click-driven content.

- Repository: [ConardLi/garden-skills](https://github.com/ConardLi/garden-skills)
- Tags: how-to-guide
- Published: 2026-09-02

---

**The web-video-presentation skill transforms markdown articles into 16:9 interactive web applications through a four-phase pipeline that generates voice-over scripts, scaffolds a Vite+React codebase, and produces click-driven presentations with optional synthesized audio.**

The web-video-presentation skill in the ConardLi/garden-skills repository provides a declarative, checkpoint-driven workflow for converting static content into dynamic visual narratives. This open-source tool treats each article as a blueprint for a self-contained web application that behaves like a video, advancing step-by-step through user interactions or automated playback. The entire process is iterative, with hard checkpoints that ensure alignment between the original content and the final presentation before any code is generated.

## Phase 1: Content Generation

The pipeline begins by analyzing the source material—either a raw [`article.md`](https://github.com/ConardLi/garden-skills/blob/main/article.md) or an existing script—and producing two critical artifacts in a single reasoning pass.

- **[`script.md`](https://github.com/ConardLi/garden-skills/blob/main/script.md)**: A platform-agnostic voice-over script that preserves the original language while following strict style contracts defined in [[`SCRIPT-STYLE.md`](https://github.com/ConardLi/garden-skills/blob/main/SCRIPT-STYLE.md)](https://github.com/ConardLi/garden-skills/blob/main/skills/web-video-presentation/references/SCRIPT-STYLE.md).
- **[`outline.md`](https://github.com/ConardLi/garden-skills/blob/main/outline.md)**: A development plan that segments content into chapters, steps, and information pools, formatted according to [[`OUTLINE-FORMAT.md`](https://github.com/ConardLi/garden-skills/blob/main/OUTLINE-FORMAT.md)](https://github.com/ConardLi/garden-skills/blob/main/skills/web-video-presentation/references/OUTLINE-FORMAT.md).

These documents serve as the single source of truth for timing, with each step representing one beat of the voice-over that drives the entire presentation flow.

## Checkpoint Validation Before Code Generation

Before generating any code, the skill enforces a **checkpoint plan** that requires user confirmation of five elements:

1. The generated script
2. The development outline
3. The visual theme selection
4. Required asset inventory
5. Development mode preferences

This validation ensures downstream scaffolding operates on a stable foundation, preventing costly refactoring later in the pipeline.

## Phase 2: Web Scaffold and Chapter Development

### Project Initialization with scaffold.sh

The [`scripts/scaffold.sh`](https://github.com/ConardLi/garden-skills/blob/main/scripts/scaffold.sh) script generates a fresh Vite, React, and TypeScript project under the `presentation/` directory using the selected theme via the `--theme=<id>` flag. The scaffold includes a demo chapter (`01-example`) that developers must remove before implementing real content.

```bash

# Scaffold a new presentation with the modern theme

bash /path/to/web-video-presentation/scripts/scaffold.sh ./presentation --theme=modern

# Remove the demo chapter and its registry entry

rm -rf presentation/src/chapters/01-example

# Edit presentation/src/registry/chapters.ts to remove EXAMPLE_CHAPTER

```

### Chapter Architecture and Step Logic

Each chapter resides in `presentation/src/chapters/<NN>-<id>/` and contains three files:

- A `.tsx` view component
- A `.css` stylesheet
- A [`narrations.ts`](https://github.com/ConardLi/garden-skills/blob/main/narrations.ts) file (the single source of truth for step count and voice text)

The **global step counter** (`useStepper` in [`templates/src/hooks/useStepper.ts`](https://github.com/ConardLi/garden-skills/blob/main/templates/src/hooks/useStepper.ts)) drives the UI deterministically. The rendering logic follows a simple conditional pattern:

```typescript
if (step === N) return <FullScene />;

```

Users advance through steps via click interactions, creating a controlled, pace-driven experience. The implementation adheres to the **CHAPTER-CRAFT** principles outlined in [[`CHAPTER-CRAFT.md`](https://github.com/ConardLi/garden-skills/blob/main/CHAPTER-CRAFT.md)](https://github.com/ConardLi/garden-skills/blob/main/skills/web-video-presentation/references/CHAPTER-CRAFT.md), including:

- The "one-item = one-step" reveal rule
- The "double-source" principle (synchronizing script, article, and visual elements)
- Ten design constraints, including fixed 16:9 stage ratio, hidden controls, and content-driven animations

## Phase 3: Audio Synthesis Pipeline

The skill includes a provider-agnostic text-to-speech (TTS) system for generating voice-overs. The process involves two npm scripts:

- **`npm run extract-narrations`**: Scans all [`narrations.ts`](https://github.com/ConardLi/garden-skills/blob/main/narrations.ts) files and generates [`audio-segments.json`](https://github.com/ConardLi/garden-skills/blob/main/audio-segments.json)
- **`npm run synthesize-audio`**: Executes the TTS pipeline

By default, the system uses **MiniMax** (`mmx-cli`), but developers can switch to OpenAI TTS by setting an environment variable:

```bash

# Default MiniMax synthesis

npm run synthesize-audio

# Alternative OpenAI TTS provider

PRESENTATION_TTS=openai npm run synthesize-audio

```

Synthesized MP3 files are stored under `public/audio/<id>/<N>.mp3` and played via the `useAudioPlayer` hook. Additional providers are documented in [`templates/scripts/tts-providers/README.md`](https://github.com/ConardLi/garden-skills/blob/main/templates/scripts/tts-providers/README.md).

## Phase 4: Recording and Post-Production

The generated web application supports two capture modes for final video production:

- **Auto mode**: Accessing `localhost:5173/?auto=1` automatically advances through the entire step sequence, enabling one-click screen capture for smooth, continuous video output.
- **Manual mode**: Users click through steps at their preferred pace, allowing for natural pauses and emphasis that can be refined in post-production with any video editor.

## Core Architecture and Key Files

The web-video-presentation skill relies on a specific file structure and hook architecture:

| File | Function |
|------|----------|
| [[`SKILL.md`](https://github.com/ConardLi/garden-skills/blob/main/SKILL.md)](https://github.com/ConardLi/garden-skills/blob/main/skills/web-video-presentation/SKILL.md) | High-level workflow overview and hard rules |
| [`templates/src/hooks/useStepper.ts`](https://github.com/ConardLi/garden-skills/blob/main/templates/src/hooks/useStepper.ts) | Global step counter with persistent storage |
| [`templates/src/hooks/useAudioPlayer.ts`](https://github.com/ConardLi/garden-skills/blob/main/templates/src/hooks/useAudioPlayer.ts) | Per-step audio playback management |
| [`templates/src/registry/chapters.ts`](https://github.com/ConardLi/garden-skills/blob/main/templates/src/registry/chapters.ts) | Registry wiring chapter modules into the application |
| [`templates/scripts/extract-narrations.ts`](https://github.com/ConardLi/garden-skills/blob/main/templates/scripts/extract-narrations.ts) | CLI tool building [`audio-segments.json`](https://github.com/ConardLi/garden-skills/blob/main/audio-segments.json) |
| [`scripts/scaffold.sh`](https://github.com/ConardLi/garden-skills/blob/main/scripts/scaffold.sh) | One-click project scaffolder |

To run the development server and preview chapters:

```bash
cd presentation
npm run dev  # → http://localhost:5173

```

## Summary

- The **web-video-presentation skill** converts [`article.md`](https://github.com/ConardLi/garden-skills/blob/main/article.md) into interactive 16:9 web applications through a four-phase pipeline.
- **Content Generation** produces [`script.md`](https://github.com/ConardLi/garden-skills/blob/main/script.md) and [`outline.md`](https://github.com/ConardLi/garden-skills/blob/main/outline.md) as the single source of truth for timing and structure.
- **Checkpoint validation** requires user confirmation of five elements before code generation begins.
- **Chapter Development** uses [`scaffold.sh`](https://github.com/ConardLi/garden-skills/blob/main/scaffold.sh) to create Vite+React projects where [`narrations.ts`](https://github.com/ConardLi/garden-skills/blob/main/narrations.ts) controls step logic via `useStepper`.
- **Audio Synthesis** supports MiniMax (default) and OpenAI TTS through configurable npm scripts.
- **Recording modes** include automatic playback (`?auto=1`) for hands-free capture or manual clicking for controlled pacing.

## Frequently Asked Questions

### What input format does the web-video-presentation skill require?

The skill accepts a markdown article file ([`article.md`](https://github.com/ConardLi/garden-skills/blob/main/article.md)) or an existing voice-over script. During Phase 1, it processes this input to generate [`script.md`](https://github.com/ConardLi/garden-skills/blob/main/script.md) and [`outline.md`](https://github.com/ConardLi/garden-skills/blob/main/outline.md) according to the style contracts in [`SCRIPT-STYLE.md`](https://github.com/ConardLi/garden-skills/blob/main/SCRIPT-STYLE.md) and [`OUTLINE-FORMAT.md`](https://github.com/ConardLi/garden-skills/blob/main/OUTLINE-FORMAT.md), ensuring the content follows a specific narrative structure before development begins.

### How does the stepper system control presentation flow?

The `useStepper` hook (located in [`templates/src/hooks/useStepper.ts`](https://github.com/ConardLi/garden-skills/blob/main/templates/src/hooks/useStepper.ts)) maintains a global step counter that determines which scene renders based on the current step number. Each chapter's [`narrations.ts`](https://github.com/ConardLi/garden-skills/blob/main/narrations.ts) file defines the total step count and corresponding voice text, creating a deterministic sequence where `if (step === N) return <FullScene/>` logic governs visual reveals.

### Can I use different text-to-speech providers?

Yes. While the default configuration uses MiniMax (`mmx-cli`), you can switch to OpenAI TTS by setting the `PRESENTATION_TTS=openai` environment variable before running `npm run synthesize-audio`. The architecture in `templates/scripts/tts-providers/` supports additional provider extensions through a standardized interface.

### What is the "one-item = one-step" principle?

This principle, defined in [`CHAPTER-CRAFT.md`](https://github.com/ConardLi/garden-skills/blob/main/CHAPTER-CRAFT.md), mandates that each visual element or content item corresponds to exactly one step in the narration sequence. This rule ensures tight synchronization between the voice-over and visual reveals, preventing cognitive overload and maintaining the presentation's rhythmic pacing as users click through the stepper.