Skip to main content
Handhold courses are narrated, animated presentations where every visual change is synchronized to spoken words. You write lessons in Markdown using a specialized DSL that controls timing, visuals, and narration.

​
What You’ll Create

A Handhold course consists of:
  • Lessons: Narrated presentations with synchronized code, data structures, diagrams, and animations
  • Labs: Hands-on coding exercises with real editors, tests, and services
  • Course Arc: A carefully designed progression from problem to solution
Courses alternate between teaching (lessons) and doing (labs). This rhythm builds understanding through immediate application.

​
Core Principles

​
The Mirror Principle

What is spoken is what is shown. Always. The screen reflects the narration at word-level granularity. If you mention “the loop,” the loop is already focused. 
{{focus: loop}} The loop processes one character at a time.
The {{focus: loop}} trigger fires before the narration, ensuring the visual and verbal are synchronized.

​
Problem First

Every lesson opens with a problem the learner can feel. Not a definition. A situation where the gap in knowledge creates tension. Good opening:
You have a list of a million names and you need to find one. Starting at the front and checking each entry could take a million steps. Hash maps do it in one.
Bad opening:
Hash maps are a fundamental data structure that provide O(1) average-case lookup time using a hash function to compute array indices.

​
One Change Per Beat

Each trigger changes one thing on screen. Each paragraph advances one idea. Compound changes use multiple triggers, not one overloaded trigger. 
{{show: hash-fn}} Here's our hash function.

{{focus: signature}} It takes a string and returns a number.

{{focus: loop}} The loop processes one character at a time.

​
Dense Choreography

Every sentence has at least one trigger. Many have two or three. The screen is never static while narration plays. A paragraph with no triggers is a bug. 
{{focus: pick}} {{zoom: 1.2x}} {{annotate: pick "Greedy choice"}} Pick the unvisited node with the smallest known distance.

​
The Authoring DSL

Handhold uses a specialized Markdown syntax with three key elements:

​
Triggers

Inline commands using double-brace syntax: {{verb: arguments}}. They fire at the word position where they appear.

​
Visualization Blocks

Code fences that define what the audience sees: code, data structures, diagrams, math, charts, or HTML/React previews. 
```code:hash-fn lang=ts
function hash(key: string): number {
  let h = 0
  for (const ch of key) {
    h = (h * 31 + ch.charCodeAt(0)) | 0
  }
  return h
}
---
signature: 1
init: 2
loop: 3-5
return-val: 7
```

​
Regions

Named sub-elements within blocks that triggers can reference. Defined in a footer section below a --- separator.
Region names should be semantic (describing the concept), not positional. Use signature, loop-body, hash-step — never line-3, top-part.

​
Lesson Structure

A lesson is a single Markdown file with:
1

Frontmatter

YAML metadata containing the title
---
title: How Hash Maps Work
---
2

Steps

H1 headings (# Step Name) that divide the lesson into scenes. Each step teaches one core idea.
# The problem

Narration and code blocks...

# The solution

More narration and blocks...
3

Content

Narration paragraphs and visualization blocks, interleaved within each step. Triggers in narration control when and how blocks appear.

​
Writing for TTS

Narration is read aloud by text-to-speech. This imposes specific constraints:

​
Read Everything Aloud

Before committing a paragraph, read it out loud. If it sounds stilted or robotic, rewrite it.

​
Use Contractions

“That’s the idea” beats “That is the idea.” TTS handles contractions naturally.

​
Short Sentences

Long compound sentences with multiple clauses are hard for listeners to parse. Break them up. Bad:
The function takes the key, computes a hash value using the polynomial rolling hash algorithm, and then applies the modulo operator to map the result into the valid index range.
Good:
The function takes a key. It computes a hash value. Then it maps that value to an array index using modulo.

​
Spell Out Math and Code

WrittenTTS SaysWrite Instead
O(n)”oh en""O of n” or “linear time”
2^6”two caret six""two to the sixth power”
&&”ampersand ampersand""and”
===”equals equals equals""strict equality”

​
Workflow

The recommended authoring process:
1

Research

Find 3-5 sources, extract “aha moments”, build a concept dependency graph
2

Architecture

Plan the lesson-lab rhythm, step names, and overall arc pattern (sandwich, build-up, comparison, or reveal)
3

Block Planning

List every visualization block per step, name them, define regions
4

Storyboard

Sketch the scene sequence before writing narration
5

Narration

Write for TTS, place triggers at exact word positions
6

Polish

Read aloud, verify mirror principle, check choreography density
7

Verify

Run parser validation, QA checklist, scan for common mistakes

​
Common Mistakes

​
Next Steps

Course Architecture

Learn how to structure courses, design arcs, and plan steps

Writing Lessons

Master the DSL, triggers, blocks, and narration craft

Creating Labs

Design hands-on coding exercises with tests and services

Build docs developers (and LLMs) love

Get started for freeTalk to us