How to write a workshop in Markdown
A Workshopy workshop is one Markdown document. Every top-level `#` heading starts a new step and becomes its title; everything until the next `#` is that step's body. Text before the first `#` is the workshop description. That is the entire structural convention — everything else is ordinary GitHub-Flavored Markdown, which means you can write a workshop by hand, generate one with an AI, or import a document you already have.
Last updated
The one rule: `#` starts a step
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.`#` inside a code block is ignored
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"
```What you can put in a step
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
- `##`–`######` headings for structure inside a step
Import and export
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 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 two markers on this page.
Editing during a live session
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.
Frequently asked questions
Does Workshopy use a custom Markdown dialect?
Almost none. It is GitHub-Flavored Markdown plus exactly two conventions: a top-level `#` heading starts a step, and `#[quiz]` marks a step as a quiz. Everything else is standard, which is why an ordinary Markdown file imports cleanly.
How do I add images?
Upload them to your media library and reference them with standard Markdown image syntax. Uploads are stored privately, per account, and served to session participants through signed URLs rather than public links.
Can I keep my workshops in Git?
Yes — a template exports as a single `.md` file, so it version-controls like any other document. There is no two-way sync with a repository today; export and import are manual.
What happens to text before the first heading?
It becomes the workshop's description rather than a step. If you want that text to be visible to participants, give it a `#` heading of its own.
Keep reading
How to add a quiz to your workshop
Write graded quizzes in plain Markdown with #[quiz], ## questions and - [x] answers — and see how correct answers stay hidden.
How to run your first live session
From a Markdown file to a running session: starting it, how participants join with a 6-character code, and pacing the room.
How to track participant progress in real time
How the per-step status model works — in progress, done and stuck — and how the dashboard turns it into a live view of who needs help.
Run your next workshop with the room visible.
Set up your first workshop in minutes — free, no credit card.