Most used copy, paste, change the words
These six cover most lessons. Each one is complete: paste it into data.md and it works.
The header
The first lines of the file, between two --- lines. Only title is required.
--- title: Make This Lesson Your Own level: B1 intro: A short demo lesson. style: classic ---
An exercise
## starts a numbered exercise. The line after it, starting with >, tells students what to do.
## Watch | Individual · 4 minutes > Watch the video. Are the sentences true or false?
True or false
The letter at the end is the answer: [t] true, [f] false.
[tf] You can use your own audio files. [t] [tf] YouTube plays from your computer. [f]
A clip
File or YouTube link, start time, end time, name. Times are minutes:seconds.
[play audio.mp3 00:10 00:40 "Part 1"] [play https://youtu.be/p2hnrfN58H4 01:26 03:24 "Clip B"]
Gaps
Curly brackets make a gap. Use | for other accepted answers.
Go to the {folder} and paste your own {audio file|audio} there.Multiple choice and discussion
* marks the right option. Discussion questions have no answer.
[m] What can you replace? - Only the video * The audio and the video - Only the exercises [/m] [discuss] What would you change first? Why?
General rules
- Tags go at the start of a line, in lowercase:
[tf],[m],[play …]. - Block tags open and close on their own lines:
[m]…[/m]. - One-line tags keep the whole item on one line and have no closing tag:
[tf],[short],[odd],[discuss],[play],[img],[timer],[link]. - Inside a tag, titles, captions and names go in straight quotes:
"Clip A". Curly quotes break the tag. - Curly brackets always make a gap. To show the symbols themselves, write
\{ \}. *marks the correct option ·=introduces an answer ·|separates accepted alternatives.- Numbers, letters and the answer key are added by the page. Leave them out of the file.
- Times:
mm:ssorhh:mm:ss, digits only.
The full rules for AI assistants are in the LessonRender specification.
Setup files and loading
The folder
- index.html: the page. It stays the same for every lesson.
- data.md: the lesson, in plain text (UTF-8).
- Any media the lesson uses, in the same folder:
audio.mp3,video.mp4,image01.png… - To put a lesson online, upload the whole folder.
How a lesson opens
- The page looks for
data.mdnext to it, thendata.txt. - Another file:
index.html?lesson=venice.md - If it finds nothing, it shows Open a lesson: drag a file in, choose one, or paste the lesson text.
- LessonRender online always starts on that screen. It's the place for YouTube lessons.
- Open in the top bar loads another lesson at any time.
Pasting from an AI
- Paste the AI's whole answer if that's easier. The page keeps the lesson and drops the chat text around it.
- Ctrl+Enter (Cmd+Enter on a Mac) shows the lesson.
- A pasted lesson lives in that browser tab. To keep it, save it as
data.md.
Opened from your computer
- Chrome and Edge ask once for the lesson's folder and then remember it.
- Other browsers ask you to choose the file each time.
- Audio, video and images work. YouTube clips need the page online.
Header between two --- lines, at the very top
| Field | What it does | Example |
|---|---|---|
| title | Large title in the hero and the browser tab. Required. | title: The Bridges of Venice |
| subtitle | Italic line under the title. | subtitle: How a city learned to cross its canals |
| level | Shown in the small line above the title. | level: C1 |
| course | Replaces the word “Lesson” in that line. | course: English for Architects |
| intro | One short paragraph that sets the scene. One line in the file. | intro: Venice stands on mud… |
| meta | Small grey line of practical facts, separated by · . | meta: About 60 minutes · Audio: audio.mp3 |
| style | The lesson's default look: classic, modern, editorial, blueprint, concrete or notebook. A reader's own choice in the Aa menu wins. | style: notebook |
Structure and text
| Element | What it does | Notation |
|---|---|---|
| Part | Section divider with a label and a thin rule. Unnumbered. | # Part 1 – Listening |
| Exercise | Numbered, with a big number, and listed in the top menu. After | : who works together and for how long (Individual, Pairs, Groups, Whole class). | ## Warm-up | Pairs · 8 minutes |
| Instructions | Blue box for students. One per exercise, right after the ## line. | > Listen and complete the notes. |
| Subheading | Small heading inside an exercise. | ### Before you listen |
| Paragraph | Lines that follow each other join into one paragraph. A blank line starts a new one. | Venice is built on 118 islands. |
| Formatting | Bold, italics, inline code, links. | **bold** *italics* `code` [text](https://example.com) |
| Lists | Bulleted or numbered. | - item 1. item |
| Table | Gaps work in the cells below the header row. | | Date | Event |
|------|-------|
| 1591 | The {stone} bridge opens | |
Presentation blocks unnumbered and unmarked; they can go anywhere
| Block | What it does | Notation |
|---|---|---|
| Reading text | Title, source line and a drop cap on the first letter. numbered adds paragraph numbers. Gaps work inside. | [read numbered] Title | Source First paragraph… Second paragraph… [/read] |
| Image | Always square. Full width by default, cropped from the centre; left or right puts it beside the text. The caption also describes the image for screen readers. | [img plan.png "Caption"] [img plan.png right "Caption"] |
| Transparent image | Blends with the page and keeps its whole shape. PNG and WebP are detected online; SVG always. Add transparent when the page is opened from your computer. | [img piles.png right transparent "Caption"] |
| Image grid | Two or three [img] lines with no blank line between them sit side by side. | [img a.png "Above"] [img b.png "Below"] [img c.png "Plan"] |
| Transcript | Folded box. Straight after a [play] line, it folds inside that player. Name: lines show the speaker in bold; lines in square brackets show as sound cues. | [transcript "Transcript (after listening)"] Masha: In the 50s, Toronto… [Music] [/transcript] |
| Fact box | Shaded box with an optional title. Formatting works inside. | [note "Did you know?"] Text. [/note] |
| Vocabulary | Two-column glossary for reference. Title optional. | [vocab "Key words"] pile = a post driven into the ground [/vocab] |
| Useful language | Phrase box in two columns. Title optional. | [phrases "For the debate"] It could be argued that… [/phrases] |
| Role cards | Grid of cards; the part before the colon is the role. | [roles] Budget officer: Worried about costs. [/roles] |
| Timeline | Vertical timeline; any text works as the date. | [timeline] c. 697 = The Republic is declared [/timeline] |
| Pull quote | Large quotation with the speaker underneath. Up to 15 words. | [quote "Viljo Revell"] Text. [/quote] |
| Timer | Countdown with Start, Pause, Reset and a progress bar. Hidden when printing. | [timer 3:00 "Retell the story"] |
| Link card | Box that opens a page in a new tab. Title optional. | [link https://… "Read more"] |
| Teacher's notes | Gathered into a folded “Teacher's notes” box at the end of the page. One block, at the end of the file. | [teacher] Notes for me. [/teacher] |
Media clips one tag for audio, video and YouTube
| Source | What it does | Notation |
|---|---|---|
| Audio file | Player with play/pause, progress bar, time, Restart and speed (0.75×, 0.9×, 1×). Stops at the end time. Clips from the same file share one player, so starting one stops the other. .mp3, .m4a, .wav, .ogg. | [play audio.mp3 01:53 02:37 "Extract 1"] |
| Video file | Video player limited to the clip, plus a “Play clip” button. .mp4, .webm, .mov. | [play video.mp4 01:58 03:09 "Clip B"] |
| YouTube | Embedded clip with Restart and “Open on YouTube”. Any YouTube link works. Needs the page online. | [play https://youtu.be/uBwkMc1llmM 03:09 04:37 "Clip C"] |
Leave out the end time to play to the end, and both times to play the whole recording. The same clip can appear in several exercises: copy the line. A missing file shows a red message in the player.
Activities numbered, checked and added to the answer key
| Activity | What students do | Notation | Help bank |
|---|---|---|---|
| Gap fill | Type the missing word. Works in paragraphs, lists, tables and reading texts. | The {piles} were made of {oak|larch}. | Yes |
| Word bank | Gap fill with a box of answers above it, plus extra words after +, shuffled. The answers go into the box by themselves. | [bank + timber, glass]
Text with {gaps}.
[/bank] | Built in |
| Dropdown | Choose from a menu inside the sentence. | It {*was|were|has been} built in 1591. | — |
| Word formation | Type a word made from the base word after the gap. | The {construction}(CONSTRUCT) took years. | Yes |
| True / false | Pick True or False. | [tf] The bridge never fell down. [f] | — |
| Multiple choice | Pick one option (lettered a, b, c…). One question per block. | [m] Question? - wrong * right - wrong [/m] | — |
| Short answer | Type one to three words. | [short] When did it open? = 1591|in 1591 | Yes |
| Long answer | Write freely, then open a suggested answer to compare. Unmarked. | [long] Question? = Suggested answer. [/long] | — |
| Matching | Choose the letter of the matching definition. Definitions are shuffled. | [match] term = definition [/match] | — |
| Ordering | Move shuffled lines with ▲ ▼. Write them in the right order. | [order] First event. Second event. [/order] | — |
| Error correction | Rewrite a sentence that has one mistake. The wrong sentence is already in the box. | [fix] The bridge were built. = The bridge was built. [/fix] | — |
| Key word transformation | Complete the second sentence with the key word. The two = signs surround the answer. | [transform] They rebuilt the bridge. (BEEN) The bridge = has been rebuilt = by them. [/transform] | — |
| Odd one out | Pick the word that doesn't belong. | [odd] piles, beams, *gondolas, slabs | — |
| Categorising | Choose a group for each shuffled word. | [sort] Materials: concrete, steel Elements: beam, column [/sort] | — |
| Discussion | Numbered speaking prompt, with no buttons. | [discuss] Should Venice limit tourists? | — |
What happens automatically
Numbering and navigation
- Every
##exercise gets a number and a place in the sticky top menu. - Items and gaps are numbered inside each exercise.
- Matching, ordering and categorising are shuffled, and never start in the right order.
Checking
- Check answers marks each answer green or red and shows a score.
- Show answers fills in every answer in blue. Clear starts again.
- Checking ignores capitals, accents, curly or straight apostrophes, extra spaces and final punctuation.
Help and answer key
- Need help? Word bank: a folded list of the answers under exercises with typed gaps or short answers.
- Answer key: folded at the end of the page, grouped by exercise.
Safety nets
- Mistakes in the lesson file appear in a red box with their line numbers.
- A missing image shows “Cannot find … in this folder”. A missing recording shows a red message in its player.
Page controls top bar
| Control | What it does |
|---|---|
| Exercise menu | Jumps to any exercise. |
| Open | Loads another lesson file. Dragging a file onto the page does the same. |
| A clean printout: buttons, players, timers and help banks are left out; folded boxes print only if open. | |
| Aa | The Appearance menu: Light, Dark or Auto (follows the device), and the six styles below. The choice is remembered on that device. |
| Moon / sun | Quick switch between light and dark. |
The six styles
AaClassicNewspaper serif. The default.
AaModernClean sans, blue-grey and violet.
AaEditorialMagazine type on warm paper.
AaBlueprintDrawing grid, technical type.
AaConcreteBold capitals and heavy rules.
AaNotebookRuled paper and handwriting.
Troubleshooting
| Problem | Fix |
|---|---|
| The “Open a lesson” screen | On LessonRender online, that's where you start. Anywhere else, the page found no data.md or data.txt next to it. Check the name (capitals count), or choose the file. |
| A red box at the top | It lists mistakes with their line numbers. Fix them by hand, or paste the lines back to the AI that wrote the lesson. |
| Red box: “not closed” | A block tag is missing its [/tag] line. |
| YouTube won't play | The page is opened from your computer. Use LessonRender online, or “Open on YouTube” for now. |
| A gap appears where it shouldn't | Curly brackets in normal text. Write \{ and \}. |
| Pasted lesson shows chat text | Copy only the lesson box from the AI, starting at the first ---. |
| Online, data.md can't be found on GitHub Pages | Add an empty file called .nojekyll at the top of the site, so .md files are published as they are. |
| A transparent PNG shows a box | The page is opened from your computer. Add transparent to the [img] line. |
| A black drawing disappears in dark mode | Use mid-tone colours in transparent images. |