LearnSpec

Appearance

The LearnSpec Suite ​

LearnSpec is a family of fourteen 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
ListenMD.listen.mdSpeech-only rendition of a content format, rendered for earsDraft v0.1
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, plus one relationship that sits outside the !import / !ref model entirely:

  • 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).
  • Rendition formats: ListenMD is not imported and not referenced, it is derived from a content format (typically LearnMD) by an editorial rewrite, and resynchronised to its source through chapter anchors rather than through a directive.
                          ┌──────────────┐
                          │   TrackMD    │   ← orchestrator
                          └──────┬───────┘
     ┌──────────┬──────────┬─────┴────┬──────────┐
     ▼          ▼          ▼          ▼          ▼
  LearnMD    QuizMD   ExerciseMD   FlashMD   NuggetMD         ← content
     │          │          │          │          │
     └──────────┴──────────┴────┬─────┴──────────┘
                                ▼
     DiagramMD, MediaMD, AnimMD, GlossaryMD, CurriculumMD     ← leaves
                                │
                         BadgeMD, CertMD                      ← credentials

  LearnMD ┄┄editorial rewrite┄┄▶ ListenMD                     ← rendition
                                                (not !import'd, not !ref'd)

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.

ListenMD ​

Role: the suite's first rendition format, a speech-only script for audio episodes, an ordered sequence of @role speech turns (@host, @signpost, @guest…) grouped into optional chapters, editorially derived from a content format (typically LearnMD) for a listener who cannot see a diagram, a table, or a list.

Key decisions: the derivation is editorial, not mechanical, tables get re-linearized into prose, visual references get narrated instead of pointed at, numbers get written the way they're spoken. Unlike every other format above, ListenMD is never !imported or !referenced, it stands alone, resynchronised to its source through ## Chapter {#source-anchor} headings whose anchor reuses the source document's own heading slug. Voice, provider, and style binding are kept entirely out of the file, resolved by whatever pipeline renders it.

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