# Markdown To > Markdown To defines canonical, versioned Markdown specifications any agent can adopt — > `todo@0.1`, `kanban@0.1`, `narrate@0.1`, `backlog@0.1`, `backlog-workspace@0.1`, > `countdown@0.1`, `gantt@0.1`, `pdf@0.1`, `calendar@0.1`, `flashcards@0.1`, `timeline@0.1`, > `podcast@0.1`, `guided-narration@0.1`, `slides@0.1`, `form@0.1`, `epub@0.1`, `matrix@0.1`, > `quiz@0.1` — where a conforming `.md` file is not documentation about an application but its > complete, portable state: readable in any viewer, diffable in git, never captive to a tool. > Canonical specs, open to every agent. The file owns the state. Each document in the Specifications section below is normative prose in the required five-part shape (Purpose, Grammar, Rationale, Examples, Verb reference) or, for conventions.md, the shared base every spec inherits. Read conventions.md first; a spec document defines only what is particular to it. ## For spec authors - [How to add a Markdown To spec](https://markdownto.ai/specs/authoring.md): Establish a new Markdown To spec end to end — SPEC.md, companion SKILL.md, schema, fixtures, core, verbs, renderer, site sheet — with the parity bar, the derives-automatically list, and the gotchas that cost real sessions. Use when adding specs// to this repo, extending a spec with a new capability surface, or reviewing whether an existing spec is "done." ## Specifications - [Shared conventions](https://markdownto.ai/specs/conventions.md): the normative base every spec inherits — the frontmatter envelope, lazy `^id` identifiers, `[key:: value]` inline fields, `#tags`, `[[wikilinks]]`, preservation guarantees, and the shared `MDTO0xx` diagnostic codes. - [todo@0.1](https://markdownto.ai/specs/todo.md): a checklist or backlog as a plain Markdown file: task items, optionally grouped into sections, where the file itself is the complete state of the list. - [kanban@0.1](https://markdownto.ai/specs/kanban.md): a board as a plain Markdown file — a level-2 heading is a column, a task list item beneath it is a card — where the file is the complete state of the board. - [narrate@0.1](https://markdownto.ai/specs/narrate.md): a **narration manuscript**: a piece of writing meant to be heard, where headings are chapters, prose is the script, and the small amount of direction a narrator needs — voice, pace, pronunciations, a held beat, a passage not to read — lives in frontmatter and in sparse inline fields. - [backlog@0.1](https://markdownto.ai/specs/backlog.md): a prioritized backlog as a plain Markdown file: level-2 headings are **bands** in priority order, task items beneath them carry a four-state marker, and a task may declare what it is waiting on. - [backlog-workspace@0.1](https://markdownto.ai/specs/backlog-workspace.md): a backlog that has outgrown one file: a directory holding exactly one `backlog@0.1` spine, the detail notes its tasks have earned, an `archive/` for what closed, and sub-backlogs a spine task delegates to. - [countdown@0.1](https://markdownto.ai/specs/countdown.md): an **absolute-target countdown**: a moment with a title and useful Markdown context that becomes a live, accessible timer without ceasing to be a readable document. - [gantt@0.1](https://markdownto.ai/specs/gantt.md): a **project schedule**: level-2 headings are workstreams, task items are scheduled bars, and sparse inline fields carry dates, progress, and dependencies. - [pdf@0.1](https://markdownto.ai/specs/pdf.md): a **print publication**: ordinary GFM prose plus explicit page direction that renders as refined, self-contained HTML and builds into a paginated PDF from the same view. - [calendar@0.1](https://markdownto.ai/specs/calendar.md): a **portable calendar**: level-2 headings are calendar dates and the bullet entries beneath them are events. - [flashcards@0.1](https://markdownto.ai/specs/flashcards.md): a **study deck**: each level-2 heading is a question and the Markdown blocks beneath it are the answer revealed when the card flips. - [timeline@0.1](https://markdownto.ai/specs/timeline.md): a **dated narrative**: each level-2 heading names a date and event, and the Markdown beneath it carries the event's detail. - [podcast@0.1](https://markdownto.ai/specs/podcast.md): a portable two-speaker dialogue manuscript for native multi-speaker text-to-speech, with stable speaker identity, explicit production direction, and reproducible audio artifacts. - [guided-narration@0.1](https://markdownto.ai/specs/guided-narration.md): a spoken explanation synchronized with passages in a separate Markdown document or webpage. - [slides@0.1](https://markdownto.ai/specs/slides.md): a portable presentation: level-2 headings are slides, Markdown is the visible content, and sparse direction chooses a constrained layout and speaker notes. - [form@0.1](https://markdownto.ai/specs/form.md): a portable questionnaire and its current response: level-2 headings are fields, plain Markdown explains them, and response fences hold typed answers. - [epub@0.1](https://markdownto.ai/specs/epub.md): a reflowable book: level-2 headings are chapters, ordinary Markdown carries the manuscript, and explicit publication metadata travels with its assets. - [matrix@0.1](https://markdownto.ai/specs/matrix.md): an explicit weighted decision: level-2 headings are criteria, tables hold comparable scores, and authored weights determine a transparent ranking. - [quiz@0.1](https://markdownto.ai/specs/quiz.md): a self-study assessment and one current attempt: level-2 headings are questions, keyed choices carry alternatives, and explicit answer keys determine reproducible grading. ## Companion agent skills Read the matching skill for authoring, repair, validation, and editorial guidance. Skills are non-normative; the specifications and fixtures remain the conformance authority. - [todo@0.1 skill](https://markdownto.ai/specs/todo.skill.md): Create or edit portable Markdown To checklists with actionable, verifiable tasks. - [kanban@0.1 skill](https://markdownto.ai/specs/kanban.skill.md): Create or edit Markdown To boards whose columns express a clear workflow. - [narrate@0.1 skill](https://markdownto.ai/specs/narrate.skill.md): Write or revise Markdown To narration manuscripts for clear, engaging spoken delivery. - [backlog@0.1 skill](https://markdownto.ai/specs/backlog.skill.md): Create or edit prioritized Markdown To backlogs with clear next actions and blockers. - [backlog-workspace@0.1 skill](https://markdownto.ai/specs/backlog-workspace.skill.md): Organize or edit a Markdown To backlog directory with one priority spine, linked notes, and delegated work. - [countdown@0.1 skill](https://markdownto.ai/specs/countdown.skill.md): Create Markdown To countdowns with an unambiguous target and useful arrival instructions. - [gantt@0.1 skill](https://markdownto.ai/specs/gantt.skill.md): Create or edit Markdown To project schedules with explicit dates, progress, and dependencies. - [pdf@0.1 skill](https://markdownto.ai/specs/pdf.skill.md): Author or revise Markdown To publications with readable structure and deliberate page design. - [calendar@0.1 skill](https://markdownto.ai/specs/calendar.skill.md): Create or edit Markdown To calendars with clear event details and explicit local times. - [flashcards@0.1 skill](https://markdownto.ai/specs/flashcards.skill.md): Create or revise Markdown To study decks with focused retrieval prompts and accurate answers. - [timeline@0.1 skill](https://markdownto.ai/specs/timeline.skill.md): Create or revise Markdown To timelines with accurate dated events and a clear narrative. - [podcast@0.1 skill](https://markdownto.ai/specs/podcast.skill.md): Write or revise Markdown To two-speaker podcasts that conform to the dialogue spec and reward listening. - [guided-narration@0.1 skill](https://markdownto.ai/specs/guided-narration.skill.md): Author spoken tours of Markdown documents or webpages with deterministic passage and image targets. - [slides@0.1 skill](https://markdownto.ai/specs/slides.skill.md): Author, repair, validate, and review portable slides documents and their rendered results. - [form@0.1 skill](https://markdownto.ai/specs/form.skill.md): Author, repair, validate, and review portable form documents and their rendered results. - [epub@0.1 skill](https://markdownto.ai/specs/epub.skill.md): Author, repair, validate, and review portable epub documents and their rendered results. - [matrix@0.1 skill](https://markdownto.ai/specs/matrix.skill.md): Author, repair, validate, and review portable matrix documents and their rendered results. - [quiz@0.1 skill](https://markdownto.ai/specs/quiz.skill.md): Author, repair, validate, and review portable quiz documents and their rendered results. ## Code - [GitHub — seekinggradient/markdownto](https://github.com/seekinggradient/markdownto): every spec, schema, and conformance fixture, plus the CLI and renderer packages that implement them. Every document in the Specifications section above is also what `mdto spec ` prints locally — `` is `conventions`, `todo`, `kanban`, `narrate`, `backlog`, `backlog-workspace`, `countdown`, `gantt`, `pdf`, `calendar`, `flashcards`, `timeline`, `podcast`, `guided-narration`, `slides`, `form`, `epub`, `matrix`, or `quiz` — so an agent that already has the CLI never needs to fetch these at all.