How to write a workshop in Markdown

A top-level ATX heading — a single # followed by a space — begins a new step. The heading text is the step title. Everything from that line until the next # is the step body.

## and deeper are ordinary headings inside the step, not step boundaries. Text before the first # becomes the workshop's description rather than a step.

A short intro to this workshop. This text becomes the
description — it is not a step.

# Set up your environment

Install the dependencies:

```bash
npm install
```

## Troubleshooting

This is a heading *inside* the step, not a new step.

# Write your first component

Now create `src/App.tsx` and export a component.

The parser tracks fenced code blocks (three or more backticks or tildes), so a shell comment or a Markdown example inside a fence never splits a step by accident. This matters more than it sounds: a workshop about Git or Bash is full of lines starting with #.

# Configure Git

Run this — the `#` below is a comment, not a new step:

```bash
# set your identity
git config --global user.name "Ada"
```

Step bodies are standard GitHub-Flavored Markdown, rendered the same way in your editor preview and in the live session — what you preview is what participants see.

• Paragraphs, bold, italic, inline code and links
• Fenced code blocks with syntax highlighting
• Ordered and unordered lists, and task lists
• Tables, block quotes and horizontal rules
• Images, including files you upload to your media library
• Interactive animations: a fenced block tagged interactive holds HTML, CSS and JavaScript that every participant plays with, sealed off from the internet and the rest of the page
• ##–###### headings for structure inside a step

Because a workshop is one file, moving it in and out is a single action. Import an existing .md and its # headings become steps. Export a template and you get the same single document back — the round trip is lossless, including quiz and practice steps.

This is also what makes AI drafting practical: ask any model for a workshop in this format, paste the result, and it becomes a running session. There is no proprietary structure to teach it beyond the markers on this page.

Starting a session snapshots the content, so editing a template never disturbs a session already running. Inside a live session the host can still edit a step's title and body, insert a step anywhere, hide a step reversibly, or delete one — and every participant's view updates without a restart.

One guard: you cannot hide or delete the step the session is currently on, so nobody can be stranded on a step that no longer exists.