Open Formatv1.5

Your eLearning content, in plain text.

LESSON.md is an open format for block-based eLearning content. Portable between tools. Readable by humans. Built for everyone in L&D.

See an ExampleConvert a Course

Bridges, not moats.

Instructional designers, academics, and subject matter experts pour time and expertise into learning content. It shouldn't be locked inside a single tool. LESSON.md is how we moved ours out into the open.

Tied to one tool

Whether you're using multiple tools or switching to a new one, your content ends up in formats that don't talk to each other.

Stuck reformatting

Course creators work across authoring tools, presentation software, and more. Every handoff means copy-pasting, reformatting, and losing structure.

Invisible to modern AI tools

Large language models can help you create and improve lessons, but only if they can read your content. Most authoring formats weren't designed for that.

See what a lesson looks like.

It's just a text file. Anyone can read it. Any tool can parse it.

fire-safety.lesson.md
1---
2title: Fire Safety Basics
3---
4
5::: text
6## What to do in a fire emergency
7
8Every second counts. Knowing what to do
9before a fire starts can save lives.
10:::
11
12::: image
13src: https://example.com/fire-safety.jpg
14alt: Fire evacuation route map
15caption: Know your building's evacuation routes
16:::
17
18::: knowledge-check
19type: multiple-choice
20question: What should you do first in a fire?
21maxAttempts: 3
22correct-feedback: Staying calm helps you make better decisions.
23
24- [ ] Run to the nearest exit
25- [x] Stay calm and assess the situation
26- [ ] Open the nearest window
27:::
Lesson title
Title and settings at the top in simple YAML
Content blocks
Each block starts with ::: and a type
Interactivity
Quizzes, buttons, and more with simple properties

What it means for you.

Whether you're an instructional designer, teacher, course creator, or eLearning software vendor, LESSON.md was shaped with both sides of the handoff in mind.

For Course Creators
  • Move lessons between any block-based tool that adopts the format
  • Read and edit your content in any text editor
  • Use AI to draft, review, and improve lessons
  • Never lose work to a vendor shutdown or format change
For eLearning Vendors
  • Import and export a format your users already understand
  • Build on Markdown: parsers exist in every language
  • Attract users who value portability and openness
  • Authoring tools, LMS platforms with built-in editors, and AI systems can all speak the same language

How it works.

A LESSON.md file goes from plain text to published lesson in three steps.

1

Write your lesson

Create a LESSON.md file in any text editor. Use Markdown for content and simple directives for interactive blocks.

2

Import it

Bring your file into any tool that supports the format. No copy-pasting, no reformatting.

3

Add media and publish

Drop in images, video, and other assets in your authoring tool. Your lesson structure is already in place.

Slate's Add Lesson dialog showing options to create a blank lesson, generate with AI, or import a LESSON.md file

Bundle multiple lessons into a course.

Zip a folder of LESSON.md files and any tool that supports the bundle layout will unpack them into a complete course. Numbered prefixes order sections and lessons. README.md is ignored. Drop a media/ folder at the root for bundled images and audio.

Flat sampleFoldered sample

Easy to adopt. Impossible to outgrow.

LESSON.md came out of patterns we recognized while building Slate. The format starts at the lesson level: a single, self-contained unit of learning. It's open, so other vendors can use it, extend it, or leave it.

Just Markdown

If your tool can read Markdown, you're most of the way there. No proprietary SDK or license required.

Make it yours

Each vendor creates their own LESSON.md based on shared patterns, then adds properties for their own block types. Tools importing simply skip what doesn't apply.

Extensible by design

Standard Markdown for content. A simple directive syntax for interactive blocks. The format grows with your tool, not against it.

See how Slate implements LESSON.md → View Slate's documentation

Explore LESSON.md.

Try it in an authoring tool, or use it in your own product.

Try free in SlateConvert a course
Support Slate

Slate eLearning is a Canadian startup building open tools for eLearning. When you subscribe to a paid plan, you help us unlock funding from Canadian AI innovation programs — so your support goes further than you might think.

View Plans→
Format changelogv1.5 latest
  1. v1.5
    • New knowledge-check question behaviour controls: Maximum attempts, Reveal correct answer when locked, Show answer-level feedback, Show general feedback, and Eliminate wrong options (multiple-choice only). Each setting inherits the course default when omitted.
  2. v1.4
    • New layout presets: masonry-2 and masonry-3 for variable-height column flow.
  3. v1.3
    • New block: flip-card-carousel. A carousel of flip cards where each card flips independently.
  4. v1.2
    • New block: labeled-graphic. Images with up to 10 clickable hotspots.
    • Removed the code block from the spec.
  5. v1.1
    • New block: note. Highlighted information boxes.
  6. v1.0
    • Initial public release of the format.

Contributors