How to build tutorial slides from markdown
- Step 1Write the workshop in Markdown — Put each step under a
##heading with the command in a fenced block and a short explanation beneath. - Step 2Break steps with `---` — Separate major steps with a line of only
---. Headings do not split — the separator does. - Step 3Stack a multi-part exercise with `----` — For a single exercise with several parts, separate the parts with
----so the room steps through them vertically. - Step 4Load one Markdown file — Paste the text or drop a single
.mdfile. One file is converted per run. - Step 5Preview for legibility — Use the iframe preview to confirm commands fit on a slide and are readable on a projector from the back of the room.
- Step 6Download and run the workshop — Save the
-slides.html, open it in a browser, and present; navigate with arrow keys and use Esc for the overview to jump between exercises.
Workshop feature support
What renders for hands-on training and what does not.
| Need | Supported? | Notes |
|---|---|---|
| Fenced command blocks | Yes | Verbatim <pre><code>; whitespace preserved |
| Syntax highlighting | No | Plain monospaced — no highlight.js bundled |
| Numbered step lists | Yes | Standard Markdown ordered lists render |
| GFM tables | Yes | Good for option/flag reference slides |
| Speaker notes | No | No Note: transform |
| Offline presenting | No | Reveal.js loads from CDN |
Slide markers
The two structural controls.
| Marker | Creates | Workshop use |
|---|---|---|
--- | Horizontal slide | Next step or section |
---- | Vertical sub-slide | Parts of one multi-step exercise |
## Heading | Title on current slide | Step name — does not split |
Tier limits (markdown family)
A character limit applies on top of file size.
| Tier | Max file size | Max characters | Files per run |
|---|---|---|---|
| Free | 1 MB | 500,000 | 1 |
| Pro | 10 MB | 5,000,000 | 10* |
| Pro + Media | 50 MB | 20,000,000 | 50* |
| Developer | 500 MB | Unlimited | Unlimited* |
Cookbook
Five patterns for hands-on tutorials. Each shows workshop Markdown and the slides it makes. Keep commands short — there is no horizontal scroll on a slide.
An intro slide then a setup step
Two horizontal slides via ---.
# Docker in 90 minutes Workshop --- ## Step 1: install ```bash brew install docker ```
Command and expected output
Two slides: what to type, then what to expect.
## Run a container ```bash docker run hello-world ``` --- ## You should see ``` Hello from Docker! ```
A multi-part exercise as a vertical stack
---- keeps the parts of one exercise together.
## Exercise: build an image ---- Write a Dockerfile ---- Build it: ```bash docker build -t demo . ```
A flag-reference table slide
GFM table renders directly as a quick-reference.
## Common flags | Flag | Meaning | |------|----------------| | -d | Detached | | -p | Publish a port | | -v | Mount a volume |
A recap slide with links
Markdown links and autolinks render; hash routing makes slides shareable.
## Recap - Images vs containers - Ports and volumes Docs: docs.docker.com
Edge cases and what actually happens
Command line too wide
CautionReveal does not wrap <pre> lines; a long command runs off the slide. Use line continuations or shorten the command before converting.
No syntax highlighting
ExpectedCommands and code render in plain monospaced text with no color. If your workshop relies on highlighted output, add highlight.js to the downloaded HTML.
Heading did not split
By designA ## is a title on the current slide, not a new slide. Insert a --- to break between steps.
Venue has no Wi-Fi
CautionReveal.js loads from cdnjs; offline the deck is unstyled HTML. Test on the workshop network or self-host the assets in the file beforehand.
Speaker notes not generated
Not supportedThere is no notes feature. Instructor cues you type show on the projected slide. Add <aside class="notes"> to the HTML manually for presenter view.
Front matter at the top
CautionA leading YAML ---/--- block reads as separators and makes stray slides. Strip it first.
Curriculum over the limit
413 rejectedA full-day workshop can exceed 500,000 characters on Free while under 1 MB. The character cap is enforced separately — upgrade or split by module.
Several module files dropped
IgnoredOnly the first file converts. Merge modules with md-merger first.
Empty file
ExpectedEmpty input produces a valid blank deck — not an error.
Frequently asked questions
How do I separate workshop slides?
A line of only --- makes a new slide; a line of only ---- makes a vertical sub-slide for multi-part exercises. Headings do not split.
Will commands be syntax-highlighted?
No. Fenced blocks render as plain monospaced text. There is no highlight.js in the deck; add it to the HTML if you need color.
Do code fences keep exact spacing?
Yes. They render as <pre><code> with whitespace preserved. Watch line length — long lines overflow the slide.
Can the room work through an exercise step by step?
Yes. Separate parts with ---- to make a vertical stack everyone steps through together.
Does it work in a venue without internet?
Not by default. Reveal.js assets load from a CDN. Test on the venue network or self-host the assets in the downloaded file.
Can attendees keep the slides?
Yes. Share the -slides.html file so learners can replay the workshop at their own pace.
Are tables supported?
Yes. GitHub-Flavored Markdown pipe tables render — handy for flag or option reference slides.
Are speaker notes supported?
No. There is no Note: conversion; text stays on the slide. Add <aside class="notes"> manually for presenter view.
What theme is used?
The built-in Reveal.js black theme. There is no picker; change the theme link in the HTML to swap it.
How big can the curriculum file be?
Free: 1 MB and 500,000 characters. Pro: 10 MB / 5,000,000. Pro + Media: 50 MB / 20,000,000. Developer: 500 MB with no character cap.
Can I convert all modules at once?
No — one file per run. Merge them with md-merger, or convert each module separately.
What if I want a printable workbook?
Convert the same Markdown with md-to-pdf-modern for a clean PDF-ready page to hand out as a workbook. For a plain styled web page instead of slides, use md-to-html.
Privacy first
All Markdown processing runs locally in your browser using JavaScript. No file is ever uploaded to JAD Apps servers — only metadata counters are saved for signed-in dashboard stats.