LearnSpec

Appearance

The LearnSpec Suite ​

LearnSpec is a family of thirteen Markdown-based formats that cover the full lifecycle of educational content, from a single lesson to a complete certification path.

Each format is independent, each is valid Markdown, and each composes with the others through the shared mechanisms defined in the Architecture Charter.

Overview ​

FormatExt.RoleStatus
LearnMD.learn.mdStructured educational contentStable, v0.3 (v0.4 drafting)
QuizMD.quiz.mdQuizzes and assessmentsStable, v0.3 drafting
ExerciseMD.exercise.mdExercises with model solutions and grading rubricsDraft v0.1
TrackMD.track.mdSequenced learning pathsDraft v0.1
FlashMD.flash.mdFlashcards and spaced repetitionDraft v0.1
NuggetMD.nugget.mdMicro-learning concepts for spaced repetitionDraft v0.3
DiagramMD.diagram.mdDiagram syntax + reusable diagrams referenced via !refDraft v0.2
AnimMD.anim.mdStep-reveal animations over vector scenesDraft v0.1
MediaMD.media.mdMedia catalogue with licencesDraft v0.1
GlossaryMD.glossary.mdTerm definitionsDraft v0.1
CurriculumMD.curriculum.mdReference frameworks and syllabiDraft v0.1
BadgeMD.badge.mdMicro-credentialsDraft v0.1
CertMD.cert.mdMacro-credentialsDraft v0.1

How the formats relate ​

The suite forms three layers:

  • Orchestrator: TrackMD sequences everything else.
  • Content formats: LearnMD, QuizMD, ExerciseMD, FlashMD, NuggetMD carry the actual material.
  • Leaf formats: DiagramMD, MediaMD, AnimMD, GlossaryMD, CurriculumMD, BadgeMD, CertMD are referenced but never reference anything else (AnimMD scripts ride inside the DiagramMD / MediaMD entries they animate).
                          ┌──────────────┐
                          │   TrackMD    │   ← orchestrator
                          └──────┬───────┘
     ┌──────────┬──────────┬─────┴────┬──────────┐
     ▼          ▼          ▼          ▼          ▼
  LearnMD    QuizMD   ExerciseMD   FlashMD   NuggetMD         ← content
     │          │          │          │          │
     └──────────┴──────────┴────┬─────┴──────────┘
                                ▼
     DiagramMD, MediaMD, AnimMD, GlossaryMD, CurriculumMD     ← leaves
                                │
                         BadgeMD, CertMD                      ← credentials

The full compatibility matrix, who can !import whom, who can !ref whom, lives in the charter.

Stable formats ​

LearnMD ​

Status: stable, v0.3 in production; v0.4 drafting to align with the new suite (extracts diagrams to DiagramMD, media to MediaMD, definitions to GlossaryMD).

The educational content format, explanations, examples, exercises, inline checkpoints. A complete course can live in a single .learn.md file; !import is a composition tool, not a prerequisite.

→ LearnMD documentation

QuizMD ​

Status: stable, v0.3 drafting consolidates the "YAML everywhere" principle across the three levels.

The assessment format, single questions, full quizzes, configurable behaviour through YAML at every level. Natively embeddable inline in a LearnMD via !import.

→ QuizMD documentation

Draft formats ​

The formats below are at draft v0.1 or v0.2, their specifications are still moving. That is a statement about the spec, not about availability: several are already implemented and used in production. Expect refinements, not upheaval.

ExerciseMD ​

Role: exercises, tasks where the learner produces work (a derivation, an essay, a translation, a program), graded against a model solution, explicit expectations, and a rubric.

The split with QuizMD is deliberate and enforced: if an answer can be graded by matching, it belongs in QuizMD; if grading requires judging a production, it belongs here. ExerciseMD therefore defines no closed-answer syntax at all, and a mixed exam paper composes both through TrackMD.

Key decisions: the canonical file holds statement and grading kit, with the subject and the answer key derived from it mechanically, parallel copies drift, derived views cannot. Rubrics come in two shapes: additive (one observable criterion per point) and levels (profile descriptors with floor scores) for holistic work.

TrackMD ​

Role: sequence learners through an ordered path of LearnMD, QuizMD, and FlashMD files, with completion criteria and progress checkpoints.

TrackMD is the only format that can !import all content types. A Level 0 .track.md is a human-readable table of contents in any standard Markdown reader.

Key decisions so far:

  • v0.1 is a linear sequence; conditional prerequisites deferred to v0.2.
  • TrackMD references BadgeMD and CertMD through on_completion metadata.

FlashMD ​

Role: front/back flashcards for spaced-repetition review. Consumed in a context separate from the lesson (review session, notification, flashcard mode), never inlined in a LearnMD.

Key decisions: inline LaTeX is available from Level 0, mathematical content is a fundamental element of cards, not an advanced feature. Visual richness (media:slug) comes at Level 2.

NuggetMD ​

Role: collections of nuggets, short, self-contained concepts read in under three minutes each, reviewed over time via spaced repetition.

NuggetMD sits between FlashMD and LearnMD: larger than an atomic fact, smaller than a full lesson. The author controls granularity, a file may hold one nugget or dozens.

Key decisions: each nugget enters its own FSRS slot; FlashMD and NuggetMD feed separate review queues, never mixed. A nugget that exceeds the three-minute reading limit belongs in LearnMD.

DiagramMD ​

Role: dual-purpose. It is both the canonical syntax specification for diagram blocks across the entire suite (mermaid, abc, chess, vega, d3, smiles, …) and a standalone file format for reusable named diagrams referenced by slug via !ref from any content format.

Other specs (LearnMD, QuizMD, FlashMD) delegate diagram documentation to DiagramMD, a diagram block valid in DiagramMD is valid everywhere in the suite. Rendering implementation is left to players.

AnimMD ​

Role: step-reveal animation scripts over existing vector scenes, a DiagramMD entry or a MediaMD SVG asset. A script only chooses the order of revelation of named elements (five verbs, prose captions); it contains no keyframes and no coordinates.

Key decisions: the script never contains a renderer id, a binding layer maps author-chosen names to the scene's source identifiers, resolved per generator at render time. Every failure mode degrades to the static scene: the worst case is exactly what the host displays today.

MediaMD ​

Role: centralise the metadata, sources, and licences for media assets so that other formats can reference images by a symbolic identifier without managing licensing themselves.

Resolution model:

markdown
![Cross-section of the heart](media:heart "https://commons.wikimedia.org/img/heart.svg")

A standard Markdown reader displays the image via the fallback URL. A LearnSpec player resolves media:heart through the MediaMD file pulled in by !ref, using the canonical source and licence.

Licence convention: SPDX identifiers (CC-BY-4.0, CC0-1.0, …). The value custom is reserved for cases SPDX does not cover, and must be accompanied by license_url or license_text.

GlossaryMD ​

Role: centralise definitions of key terms in a corpus. Referenced via !ref so a compatible player can highlight terms, surface tooltips, and link related entries, without modifying source content.

This is the format with the most natural graceful degradation: a Level 0 .glossary.md is a perfectly readable glossary in any Markdown viewer with no specific syntax at all. Inline Markdown and LaTeX are allowed in definitions; fenced blocks (Mermaid, quiz, rich examples) are not, a definition that needs a diagram is a lesson, not a glossary entry.

CurriculumMD ​

Role: describe what a corpus must cover, a school syllabus, a certification framework, an internal training plan, without being pedagogical content itself.

CurriculumMD is the first meta format in the suite: it holds no lessons or quizzes, only reference learning objectives. Content formats declare alignment with !ref; the actual coverage check is performed by the AI or the player.

Key decisions: a pure leaf format, imports and references nothing. Level 2 adds per-objective attributes (id, bloom, weight, mandatory) for machine-readable alignment.

BadgeMD ​

Role: define a micro-credential that recognises mastery of a specific, granular skill. Badges are stackable: a learner accumulates them along a path.

Designed for compatibility with Open Badges 3.0 (IMS Global / 1EdTech), so a .badge.md can be issued to LinkedIn, Credly, and similar platforms. SVG-native: the badge image lives next to the file and is bakeable.

CertMD ​

Role: define a macro-credential attesting mastery of a complete domain, typically requiring completion of one or more TrackMD paths, a passing score on a formal assessment, and possibly prerequisite badges.

CertMD is to BadgeMD what a degree is to a module completion certificate: same family, different scope. Kept as two separate formats to keep each spec focused.

Where to next ​

  • Read the Architecture Charter for the principles every format inherits, graceful degradation, levels, frontmatter, directives, validation.
  • Read the LearnMD and QuizMD specifications for the stable formats.
  • Follow github.com/learnspec for the draft specifications and their changelogs.

Released under the MIT License.

Copyright © 2024-present LearnSpec Contributors