LearnMD

The educational content format of the LearnSpec suite.

LearnMD covers instruction — explaining what to know — while QuizMD covers assessment. Together they form a complete teach → assess stack, all in portable plain-text files.

A complete course — modules, lessons, examples, exercises, embedded quizzes — can live in a single valid .learn.md file. The !import directive is a composition tool for reusability, not a prerequisite.

Key principles

Principle	Description
Markdown-first	A .learn.md file is valid Markdown — readable in any editor
File-native	All content lives in files — no database required
Git-native	Versionable, diffable, and mergeable like code
AI-native	Generatable and consumable by LLMs without special tooling
Progressively enriched	Plain text (Level 0) up through special fenced blocks (Level 2)
LearnSpec-interoperable	Natively integrates with QuizMD, DiagramMD, MediaMD, and GlossaryMD

LearnMD inherits its frontmatter, directives, and validation rules from the shared Architecture Charter.

Format levels

Level	Mechanism	Purpose
0	Plain .learn.md, native Markdown	Minimal content, readable everywhere
1	YAML frontmatter + GFM callouts	Metadata, estimated time, language
2	Special fenced blocks + directives	Examples, summaries, inline quizzes, imports

Each level is a strict superset of the previous one.

Quick example

---
title: Introduction to Python
lang: en
description: "Variables, assignment, and basic types — a first contact with Python for absolute beginners."
estimated_time: 15min
tags: [python, variables]
spec_version: "0.4"
---

# Introduction to Python

!ref ./glossary-python.glossary.md

## Module 1 — Variables

A variable is a named reference to a value in memory.

```python
age = 25
name = "Alice"
```

> [!tip]
> Use descriptive names: `student_count` is clearer than `n`.

```quiz
? Which syntax is valid Python?
- [x] age = 25
- [ ] int age = 25
- [ ] var age = 25
```

!checkpoint id:module-1-done label:"Module 1 complete"

Status

LearnMD v0.3 is stable. v0.4 is drafting to align with the new LearnSpec suite — it extracts diagram syntax to DiagramMD, media catalogues to MediaMD, and term definitions to GlossaryMD, adds the universal !ref directive (for DiagramMD, MediaMD and GlossaryMD contexts) along with !checkpoint, and introduces ```diagram ref:slug for granular reuse of named diagrams.

Next steps

• Read the full Specification.
• Try the Getting Started guide.
• Browse Examples.