LearnSpecAn open suite of Markdown formats for learning

A suite, not a single format ​

LearnSpec is an open specification suite for educational content. Each format is plain Markdown, each lives in flat files, and each composes with the others through a small set of shared mechanisms.

The 13 formats ​

Three principles tie the suite together ​

1. Graceful degradation: any LearnSpec syntax that would produce a broken render in a standard Markdown reader is forbidden without an explicit fallback.
2. File-native: metadata lives in YAML frontmatter, references are paths or URLs, a corpus is a folder. No database is ever required to read content.
3. Progressive levels: every format has a Level 0 (pure Markdown), Level 1 (frontmatter), and Level 2 (fenced blocks and directives). Each level is a strict superset of the previous one.

These rules are documented in the Architecture Charter, the shared foundation every format builds on.

How the formats compose ​

A learning corpus typically combines several formats:

• A TrackMD sequences a path through several LearnMD lessons and QuizMD checkpoints.
• Where a checkpoint calls for produced work rather than a selected answer, an ExerciseMD sheet carries the task and the rubric that grades it.
• The lessons embed diagrams defined in DiagramMD, images catalogued in MediaMD, and highlight terms from a GlossaryMD.
• A diagram whose reading order carries an argument can ship an AnimMD companion script, and the lesson plays it as a step-reveal animation.
• A FlashMD deck or a NuggetMD collection supports spaced-repetition review of the same material.
• The corpus declares alignment with a CurriculumMD reference framework, so coverage can be checked against an official syllabus.
• Completion may award a BadgeMD (per skill) or a CertMD (per track).

All references are resolved through three directives, !import, !ref, !checkpoint, defined once in the charter and used identically across the suite.

Status & governance ​

LearnSpec is an open standard under the MIT licence. Specifications, tooling, and reference parsers are developed in the open at github.com/learnspec. The standard is currently maintained by neuroneo-md; the specs themselves remain independent of any single platform.