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 11 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.
• The lessons embed diagrams defined in DiagramMD, images catalogued in MediaMD, and highlight terms from a GlossaryMD.
• 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, which also operates a commercial implementation; the specs themselves remain independent of any single platform.