LESSON.md

v1.9

A LESSON.md file is one eLearning lesson written in plain Markdown. It has a short YAML frontmatter block for the title, followed by content blocks wrapped in ::: fences. This page is the full format reference. For an assessment file, see ASSESSMENT.md.

Format overview

A LESSON.md file has three parts:

---
title: My Lesson Title        ← YAML frontmatter
---

::: text                       ← Block fence (opening)
# Welcome
This is a text block.
:::                            ← Block fence (closing)

::: image                      ← Another block
src: https://example.com/photo.jpg
alt: A description
:::

Frontmatter

Every file starts with YAML frontmatter containing the lesson title:

---
title: Workplace Safety Basics
---

The title becomes the lesson name in Slate. Quoted titles are also accepted: title: "My Title".

Block fences

Each block is wrapped in ::: blocktype and ::: delimiters. This is the fenced directive syntax used by remark-directive, VuePress, and Docusaurus - most AI tools recognize it.

::: text
Your content here.
:::

Every ::: opener needs a matching ::: closer on its own line. An unclosed fence fails the whole file.

Properties

Block properties use key: value syntax, one per line, at the top of the block body before any prose:

::: image
src: https://example.com/photo.jpg
alt: Workers wearing hard hats
caption: Always wear appropriate PPE
width: large
align: center
:::

Property keys are case-insensitive on import. Write them in the casing the tables below show (openInNewTab) for clean, readable files. An unknown key is silently ignored, so the block quietly loses that setting - do not guess property names.

Text content

Text inside blocks is standard Markdown. It gets converted to HTML on import:

::: text
# Section Heading

This paragraph has **bold**, *italic*, and [links](https://example.com).

- Bullet one
- Bullet two

1. Numbered item
2. Another item
:::

Heading levels: In Slate, H1 is reserved for the course title and H2 for lesson titles. Markdown headings are automatically shifted by two levels on import: # becomes H3, ## becomes H4, and so on. Write your headings naturally - the parser handles the conversion.

Nested sections

Blocks that contain sub-items (accordion, tabs, process, timeline, layout, card carousel) use ## headings to delimit each section:

::: accordion
## First Section
Content for section one.

## Second Section
Content for section two.
:::

Comments

HTML comments are stripped during import. The template uses them extensively to annotate examples:

<!-- This comment won't appear in the imported lesson -->

---

Block reference

LESSON.md supports 21 of Slate’s 22 block picker entries (20 of 21 persisted block types). Labelled Graphic is an Image variant with its own directive. The code block is excluded because HTML, CSS, and JavaScript can’t be reliably expressed in Markdown’s single-line property format. Use Slate’s built-in code block editor instead, which offers syntax highlighting, auto-formatting, and AI generation.

Text

Rich text content with full Markdown support.

::: text
# Heading

Paragraph with **bold**, *italic*, and [links](https://example.com).

- List items work
- As do numbered lists
:::

No properties - the entire block body is Markdown content.

Image

Property	Required	Values	Default
src	Yes	URL	—
alt	No	Text	""
caption	No	Text	—
width	No	full, large, medium, small	large
align	No	left, center, right	center

::: image
src: https://example.com/safety-gear.jpg
alt: Worker wearing protective equipment
caption: Always wear appropriate PPE
width: large
align: center
:::

In a course bundle, src can also be a relative path like media/cover.png. See LESSON.md Bundles for bundled media.

Labeled Graphic

An image with interactive hotspot labels. Each ## heading creates a clickable hotspot positioned on the image.

Property	Required	Values	Default
src	Yes	URL	—
alt	No	Text	""
caption	No	Text	—
width	No	full, large, medium, small	large
align	No	left, center, right	center

Hotspot properties (per ## section):

Property	Required	Values	Default
x	Yes	0–100 (% from left)	50
y	Yes	0–100 (% from top)	50

The heading text becomes the hotspot label. Content after the properties is the hotspot description (Markdown, supports bold, italic, lists, and links). Maximum 10 hotspots per image.

Note

Hotspot x and y values are approximate percentages. After importing, open the lesson in Slate to fine-tune hotspot positions visually by dragging the markers.

::: labeled-graphic
src: https://example.com/cell-diagram.jpg
alt: Diagram of a biological cell
caption: Click each label to learn more
width: large
align: center

## Nucleus
x: 25
y: 40
The **nucleus** controls cellular functions and contains DNA.

## Mitochondrion
x: 75
y: 60
The powerhouse of the cell - generates ATP through cellular respiration.

## Cell Membrane
x: 90
y: 50
The outer boundary that controls what enters and exits the cell.
:::

Video

Property	Required	Values	Default
src	Yes	URL	—
provider	No	youtube, vimeo, googledrive, synthesia, loom, url, upload	Auto-detected from URL
caption	No	Text	—

::: video
src: https://www.youtube.com/watch?v=dQw4w9WgXcQ
caption: Training overview video
:::

The provider is auto-detected from the URL. YouTube, Vimeo, Google Drive, Synthesia, and Loom URLs are recognized automatically.

Audio

Property	Required	Values	Default
src	Yes	URL	—
caption	No	Text	—

::: audio
src: https://example.com/podcast-episode.mp3
caption: Listen to the full interview
:::

Document

Property	Required	Values	Default
src	Yes	URL	—
filename	No	Text	Extracted from URL
title	No	Text	""
description	No	Text	""

A downloadable file attachment. The src must be a URL to a hosted file. The filename is extracted from the URL if not provided, and the file type is detected from the extension.

::: document
src: https://example.com/safety-manual.pdf
filename: Safety Manual.pdf
title: Workplace Safety Manual
description: Complete guide to workplace safety procedures
:::

Divider

Property	Required	Values	Default
style	No	line, space, dots	line

::: divider
style: dots
:::

Button

Property	Required	Values	Default
text	No	Text	Click me
url	No	URL	""
style	No	primary, secondary, outline	primary
openInNewTab	No	true, false	false
align	No	left, center, right	—

::: button
text: Download Resources
url: https://example.com/resources.pdf
style: primary
openInNewTab: true
align: center
:::

Embed (iframe)

Property	Required	Values	Default
src	Yes	URL	—
width	No	CSS value	100%
height	No	CSS value	400
title	No	Text	""
allowFullscreen	No	true, false	true

The block type is iframe.

::: iframe
src: https://www.canva.com/design/embed/abc123
width: 100%
height: 600
title: Interactive presentation
allowFullscreen: true
:::

Accordion

Property	Required	Values	Default
allowMultiple	No	true, false	false

Each ## heading creates a collapsible section. Content within each section is Markdown.

::: accordion
allowMultiple: false

## Fire Safety
Fire safety involves understanding exit routes and extinguisher locations.

Always know your nearest **two exits**.

## Electrical Safety
Never work on live circuits without proper lockout/tagout procedures.

- De-energize equipment first
- Apply locks and tags
- Verify zero energy state

## Chemical Safety
Handle hazardous materials according to their Safety Data Sheets (SDS).
:::

Tabs

Property	Required	Values	Default
orientation	No	horizontal, vertical	horizontal

Each ## heading creates a tab. The heading text becomes the tab label.

::: tabs
orientation: horizontal

## Overview
This module covers the fundamentals of workplace safety.

## Objectives
By the end of this lesson, you will be able to:
- Identify common hazards
- Use protective equipment correctly

## Resources
- [OSHA Guidelines](https://osha.gov)
- [Company Safety Manual](https://example.com/safety)
:::

Process

Use Process for ordered actions or stages. Every ## heading starts a step. The optional marker: line must immediately follow its heading; without one, Slate shows the step number. The rest of each item is Markdown.

Property	Required	Values	Default
orientation	No	vertical, horizontal	vertical (warning if omitted)
style	No	standard, accent, minimal	standard

::: process
orientation: horizontal
style: accent

## Discover
Interview learners and review the current workflow.

## Design
marker: 2

Create and test the proposed learning experience.
:::

Timeline

Use Timeline for dated or labelled milestones. Every ## heading starts an event. An optional marker: line immediately after its heading can hold a date, year, phase, or era as plain text. The rest of each item is Markdown.

Property	Required	Values	Default
orientation	No	vertical, horizontal	vertical (warning if omitted)
style	No	standard, accent, minimal	standard

::: timeline
orientation: vertical
style: minimal

## Company founded
marker: 2019

The first version of the product launched.

## International expansion
marker: 2023

The company opened its first international office.
:::

Slate always writes orientation and style when it exports either block. Missing or invalid orientation warns and uses vertical. Missing style uses standard; invalid style warns and uses standard. Each block needs at least one ## item or the import fails. Only marker is read as an item property. Other property-shaped lines, such as Owner: Alice, remain in the item description. Process and Timeline are not allowed in ASSESSMENT.md.

Layout

Property	Required	Values	Default
preset	No	2-col-equal, 2-col-left, 2-col-right, 3-col-equal, 4-col-equal, 2x2, masonry-2, masonry-3	Auto from column count
gap	No	none, sm, md, lg	md

Each ## heading creates a cell. Content within each cell is converted to text blocks.

For grid presets, the number of ## headings matches the column count. For masonry presets (masonry-2, masonry-3), each ## heading becomes a single masonry item, and the preset name determines how many columns the items flow into.

::: layout
preset: 2-col-equal
gap: md

## Left Column
Content for the **left column** with Markdown support.

## Right Column
Content for the **right column**.

- List items work here too
:::

::: layout
preset: masonry-3
gap: md

## Short item
A single line of text.

## Taller item
Longer content that takes up more vertical space, demonstrating how items of varying heights flow through the columns.

## Medium item
Another item. Masonry keeps items in source order and distributes them evenly across the configured columns.

## Next item
Items do not reflow across columns when their height changes, so expanding an image or adding a line will not shuffle the rest.
:::

Knowledge Check - Multiple Choice

Property	Required	Values	Default
type	Yes	multiple-choice	—
question	Yes	Text	—
instructions	No	Text	None
correct-feedback	No	Text	Correct!
incorrect-feedback	No	Text	Try again.
maxAttempts	No	Number	0 (unlimited)
revealCorrectAnswer	No	true, false	false
revealAnswersPerAttempt	No	true, false	true
showFeedback	No	true, false	true
eliminateWrongOptions	No	true, false	false

Use [x] for the correct answer and [ ] for incorrect options. Multiple choice must have exactly one correct answer and at least two options. The eliminateWrongOptions property keeps previously-wrong options marked and unavailable on later attempts. The optional instructions property (added in v1.7) adds a short learner-facing line under the question, such as “Select the correct answer.”

::: knowledge-check
type: multiple-choice
question: What should you do first when you discover a fire?
instructions: Select the correct answer.
correct-feedback: Correct! Always activate the alarm first.
incorrect-feedback: Review the fire response procedures and try again.

- [ ] Attempt to extinguish it
- [x] Activate the fire alarm
- [ ] Open the windows
- [ ] Continue working
:::

Knowledge Check - Multiple Select

Same properties as multiple choice (except eliminateWrongOptions, which is multiple-choice only). Use [x] on all correct answers. At least one must be correct. When you supply an instructions line on a multiple-select question, it replaces the built-in “Select all that apply” hint the player would otherwise show.

::: knowledge-check
type: multiple-select
question: Which of the following are types of PPE? (Select all that apply)
correct-feedback: Correct! All of these are PPE.
incorrect-feedback: Some items are missing. Review the PPE categories.

- [x] Safety goggles
- [x] Hard hat
- [ ] Laptop
- [x] Steel-toed boots
- [ ] Notebook
:::

Knowledge Check - Fill in the Blank

Property	Required	Values	Default
type	Yes	fill-in-the-blank	—
question	Yes	Text	—
instructions	No	Text	None
correct-feedback	No	Text	Correct!
incorrect-feedback	No	Text	Try again.
caseSensitive	No	true, false	false
maxAttempts	No	Number	0 (unlimited)
revealCorrectAnswer	No	true, false	true
revealAnswersPerAttempt	No	true, false	true
showFeedback	No	true, false	true

List all accepted answers with [x]. At least one accepted answer is required. Use _____ in the question to mark the blank. The revealCorrectAnswer default is true on fill-in-the-blank, showing the first accepted answer when the learner reaches the attempt limit.

::: knowledge-check
type: fill-in-the-blank
question: The chemical symbol for water is _____.
correct-feedback: Correct! Water is H2O.
incorrect-feedback: Think about hydrogen and oxygen.

- [x] H2O
- [x] h2o
:::

Table

Property	Required	Values	Default
headerRow	No	true, false	true
headerColumn	No	true, false	false
borderStyle	No	all, horizontal, outer, none	all
striping	No	none, even, odd	none
caption	No	Text	—

Use standard Markdown pipe table syntax. The separator row (| --- | --- |) is required between the header and data rows.

::: table
headerRow: true
borderStyle: all
striping: even
caption: PPE requirements by area

| Area        | Hard Hat | Goggles | Gloves |
| ----------- | -------- | ------- | ------ |
| Warehouse   | Yes      | No      | Yes    |
| Laboratory  | No       | Yes     | Yes    |
| Office      | No       | No      | No     |
| Loading Bay | Yes      | No      | Yes    |
:::

Code (not supported)

Code blocks are not included in LESSON.md. The HTML, CSS, and JavaScript content that code blocks are designed to hold can’t be reliably expressed in the single-line property format - meaningful code almost always spans multiple lines. This boundary is intentional, not an oversight.

To add custom HTML/CSS/JS to a lesson, use Slate’s built-in code block editor directly. It offers syntax highlighting, auto-formatting, and AI generation.

Card

Property	Required	Values	Default
title	No	Text	""
subtitle	No	Text	""
style	No	default, outlined, elevated, filled	default
imageUrl	No	URL	""
imageAlt	No	Text	""
imagePosition	No	top, left, right, none	top if image, none otherwise
linkUrl	No	URL	""
linkNewTab	No	true, false	false

Markdown content after the properties becomes the card body.

::: card
title: Fire Extinguisher Types
subtitle: Know which to use
style: elevated
imageUrl: https://example.com/extinguishers.jpg
imageAlt: Different types of fire extinguishers

- **Class A** - Ordinary combustibles (wood, paper)
- **Class B** - Flammable liquids (gasoline, oil)
- **Class C** - Electrical equipment
:::

Flip Card

Property	Required	Values	Default
flipDirection	No	horizontal, vertical	horizontal
flipTrigger	No	hover, click	click
aspectRatio	No	1:1, 4:3, 16:9, auto	4:3

Use ## Front and ## Back headings. Each side supports its own properties (title, subtitle, imageUrl, imageAlt, style) followed by Markdown content.

::: flip-card
flipDirection: horizontal
flipTrigger: click
aspectRatio: 4:3

## Front
title: What does PASS stand for?
subtitle: Click to reveal

A common acronym for fire extinguisher use.

## Back
title: PASS
subtitle: Fire extinguisher technique

- **P**ull the pin
- **A**im at the base of the fire
- **S**queeze the handle
- **S**weep side to side
:::

Card Carousel

Property	Required	Values	Default
style	No	default, outlined, elevated, filled	default
cardsPerView	No	1, 2, 3, 4	3
showNavigation	No	true, false	true
showDots	No	true, false	true
autoplay	No	true, false	false
autoplayInterval	No	Milliseconds	5000
loop	No	true, false	true

Each ## heading creates a card. Cards support their own properties (subtitle, imageUrl, imageAlt, linkUrl, linkNewTab) followed by Markdown body content.

::: card-carousel
style: outlined
cardsPerView: 3
showNavigation: true
showDots: true

## Hard Hat
subtitle: Head protection
imageUrl: https://example.com/hard-hat.jpg
imageAlt: Yellow hard hat

Protects against falling objects and head impacts.

## Safety Goggles
subtitle: Eye protection
imageUrl: https://example.com/goggles.jpg
imageAlt: Safety goggles

Shields eyes from chemical splashes and debris.

## Gloves
subtitle: Hand protection
imageUrl: https://example.com/gloves.jpg
imageAlt: Work gloves

Prevents cuts, burns, and chemical exposure.
:::

Flip Card Carousel

Property	Required	Values	Default
flipDirection	No	horizontal, vertical	horizontal
flipTrigger	No	hover, click	click
aspectRatio	No	1:1, 4:3, 16:9, auto	4:3
style	No	default, outlined, elevated, filled	default
cardsPerView	No	1, 2, 3, 4	1
showNavigation	No	true, false	true
showDots	No	true, false	true
autoplay	No	true, false	false
autoplayInterval	No	Milliseconds	5000
loop	No	true, false	true

Each ## heading defines a card. Inside each card, use ### Front and ### Back subsections. Each side supports its own properties (title, subtitle, imageUrl, imageAlt, style) followed by Markdown content.

::: flip-card-carousel
flipDirection: horizontal
flipTrigger: click
aspectRatio: 4:3
cardsPerView: 1
showNavigation: true
showDots: true
loop: true

## Card 1

### Front
title: Safety Rule 1
imageUrl: https://example.com/rule1.jpg

### Back
title: Why it matters

Detailed explanation of the first safety rule.

## Card 2

### Front
title: Safety Rule 2
imageUrl: https://example.com/rule2.jpg

### Back
title: Why it matters

Detailed explanation of the second safety rule.
:::

Note

Property	Required	Values	Default
variant	No	1 (accent), 2 (bordered), 3 (filled), 4 (minimal)	1

A callout block for highlighting important information. The content is Markdown.

::: note
variant: 2

**Important:** Always wear protective equipment in the warehouse area.
:::

---

Error handling

The parser validates your file and reports issues in two categories:

Errors (prevent import):

• Missing title in frontmatter
• No blocks found
• Unclosed ::: fence
• Process or Timeline block without any ## items
• Knowledge check with fewer than 2 options
• Fill-in-the-blank with no accepted answers

Warnings (block is skipped or created with defaults):

• Unknown block type
• Missing required property (e.g., image without src)
• Missing or invalid Process/Timeline orientation, or invalid style (the block uses a default)
• Multiple-choice question with more than one correct answer

The import dialog shows all warnings before you confirm the import.

---

Tips for AI tools

When using LESSON.md with an AI assistant, these prompts work well:

Starting from scratch:

Here is a LESSON.md template. Create a lesson about [topic] for [audience]. Use a variety of block types including text, images, knowledge checks, and accordions.

From existing content:

Convert the following content into LESSON.md format. Use knowledge checks to test comprehension and accordions to organize detailed sections. Here is the template for reference: [paste template]

Iterating:

Add a multiple-select knowledge check after the safety procedures section. Include 5 options with 3 correct answers.

For a guided experience, the lesson-md skill gives AI tools the full format knowledge, templates, and validation built in.

Best practices

• Provide the template - Always include the LESSON.md template or a link to this specification so the AI knows the exact syntax
• Specify block types - Ask for specific block types rather than letting the AI choose generically
• Review before importing - AI-generated content should be reviewed for accuracy before importing
• Use comments - Ask the AI to include HTML comments explaining its choices, since they’re stripped on import

Related

• LESSON.md overview - what the format is and how to get started
• ASSESSMENT.md - the scored assessment format
• LESSON.md Bundles - turn a zip of lessons into a full course