DiagramMD
The diagram format of the LearnSpec suite, and the canonical syntax reference for diagrams across the suite.
DiagramMD plays a dual role:
- Syntax specification: every diagram block type usable in LearnMD, QuizMD and FlashMD is defined here. A diagram block valid in DiagramMD is valid everywhere in the suite.
- Standalone file format:
.diagram.mdfiles hold reusable named diagrams, referenced via!reffrom any content format and addressed individually by slug.
DiagramMD is a pure leaf format: it imports and references no other LearnSpec format, and is itself consumed via !ref, never via !import. How diagrams are rendered (server-side, client-side, hybrid) is left entirely to the player implementation.
Key principles
| Principle | Description |
|---|---|
| Markdown-first | A .diagram.md file is valid Markdown readable in any editor |
| File-native | All diagrams live in files, no database required |
| Graceful degradation | In any standard reader, each block displays as readable plain-text code |
| Player-agnostic | The spec defines syntax, not render implementation |
| AI-native | Generatable and consumable by an LLM without specific tooling |
DiagramMD inherits its frontmatter and validation rules from the shared Architecture Charter.
Supported diagram types
mermaid, tikz, graphviz, plantuml, blockdiag, seqdiag, chess, abc, smiles, vega-lite
All blocks accept the same set of common attributes: id, caption, width, alt. A diagram fenced block additionally supports ref:slug to reference a diagram declared in a !ref-ed .diagram.md file.
Quick example
```mermaid caption:"System architecture" width:80%
flowchart LR
A[Client] --> B[API]
B --> C[(Database)]
B --> D[Cache]
```Status
DiagramMD is a draft v0.2. It absorbs and replaces the diagram documentation previously found in LearnMD v0.3, and aligns its consumption model on !ref (like MediaMD) for granular, slug-based references.
Next steps
- Read the full Specification.
A stock entry can carry an AnimMD companion script, a step-reveal animation played over the rendered diagram, degrading to the static figure everywhere else.