LESSON.md

v1.1

LESSON.md is an open standard created by Slate eLearning for writing eLearning lessons in Markdown. Like README.md or CLAUDE.md, it defines a convention that any tool can read and write. Author a lesson in any text editor or AI tool, then import the .md file directly into Slate.

The specification, template, and import are freely available on all Slate plans.

Why LESSON.md

eLearning content is typically locked inside proprietary authoring tools. LESSON.md is a plain-text alternative:

• Any AI tool can write it - Give the template to Claude, ChatGPT, or any LLM and get back a fully structured lesson
• Any editor can open it - VS Code, Obsidian, Notion, Google Docs, or a plain text editor
• Nothing is lost on import - The format maps directly to Slate’s block types
• Human-readable by default - Markdown is easy to review, diff, and version control

Quick start

1. Download the LESSON.md template from the import dialog in Slate (Course Overview → LESSON.md → Download LESSON.md)
2. Open the file in your preferred AI tool or text editor
3. Fill in the title and add blocks using the ::: fence syntax
4. In Slate, open a course and click LESSON.md on any section
5. Drop your file and click Import Lesson

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.
:::

Properties

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

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

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, 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 18 of Slate’s 19 block types. The labeled graphic block is excluded because interactive hotspot positioning can’t be expressed in Markdown.

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
:::

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

::: 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)
:::

Layout

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

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

::: 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
:::

Knowledge Check - Multiple Choice

Property	Required	Values	Default
type	Yes	multiple-choice	—
question	Yes	Text	—
correct-feedback	No	Text	Correct!
incorrect-feedback	No	Text	Try again.

Use [x] for the correct answer and [ ] for incorrect options. Multiple choice must have exactly one correct answer and at least two options.

::: knowledge-check
type: multiple-choice
question: What should you do first when you discover a fire?
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. Use [x] on all correct answers. At least one must be correct.

::: 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	—
correct-feedback	No	Text	Correct!
incorrect-feedback	No	Text	Try again.
caseSensitive	No	true, false	false

List all accepted answers with [x]. At least one accepted answer is required.

::: 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

Property	Required	Values	Default
mode	No	html, snippet, blocks	html
html	No	HTML string	""
css	No	CSS string	""
js	No	JavaScript string	""
useJquery	No	true, false	false

::: code
mode: html
html: <div class="alert"><strong>Notice:</strong> This area requires PPE.</div>
css: .alert { padding: 16px; background: #fff3cd; border: 1px solid #ffc107; border-radius: 8px; }
:::

For complex HTML/CSS/JS, consider using Slate’s code block editor directly - the inline property format is limited to single-line values.

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.
:::

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
• 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)
• 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.

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