7 · Directives reference
Every card marker and deck/card key in one place. Scope is where each may
appear: a deck key is a line in the frontmatter (the ----fenced YAML block
at the top of the file), a card key is a <!-- key: value --> comment at the
card’s end (comment machinery trails its card, the id line last), and deck · card keys work either way, with the card one
taking precedence. The heading rows are structure rather than keys: # scopes a
section, the rest scope a card. Each links to the chapter that explains it in
full.
| Token | Scope | What it does |
|---|---|---|
## front | card | Starts a card at column 0; the lines below are the answer. → ch 3 |
# heading | section | Opens a section: its text and the prose under it are the shared context of every card below, shown on demand (c in the web app), never while you answer. Takes no directives and no card ID. → ch 3 |
### to ###### front | card | A sub-card of the card one level shallower, withheld from review until that parent graduates. Six hashes is the deepest, since a seventh is prose. → ch 3 |
> block | card | A blockquote: a note shown after you answer when its first line is an alert badge ([!NOTE], [!TIP], [!IMPORTANT], [!WARNING], [!CAUTION]), otherwise a quotation that belongs to the answer and reveals with it. → ch 3 |
<!-- --> | anywhere | A deck’s comments are alix machinery, not editorial prose. A comment that is not recognized (a directive, a locator, an id, or an invocation) is ignored and draws a doctor finding, whatever its length. Prose about a deck belongs in description:, its origin in source:. |
choices: single / choices: multiple | card | Invocation comment on the line below a task list: maps it to a choice card, one correct answer or select-all-that-apply. A bare task list stays a literal checklist. |
cards | card | Invocation comment on the line below a pipe table: maps it to a card table. A bare table renders literally. |
plain | card · section | On the line below a task list, a table, or a thematic break of any spelling: keeps that one shape literal (for a break: the divider and thematic-break grammar, in every position, including where the break would otherwise be an error). |
choices | deck | Deck-wide default task-list mapping: single or multiple. A per-card invocation overrides it. → ch 3 |
format-version | deck | Reserved. The deck format’s version, not the deck’s own. Absence means 1, so alix never writes it; any number other than 1 is refused rather than guessed at. → ch 3 |
id | deck | The frontmatter deck ID (deck-<token>) marks an initialized deck and authorizes maintenance of missing card IDs. Its deck- prefix is what tells alix’s decks apart. → ch 3 |
id | card | The HTML-comment card ID (card-<token>) anchors review history. It is minted by alix deck init or a deck-creation workflow and maintained by alix, never hand-authored. After a card table it is the table’s container ID; each row’s card composes it with the row stamp (r:) at the end of the row, after the closing pipe. → ch 3 |
reveal | deck · card | How the answer is uncovered: flip (default) or line. Cloze is triggered by a blank: directive, never by a reveal: value. |
review | deck | The order cards are served at review: scheduled (default) or sequential. → ch 5 |
input | deck · card | type (default) or draw: answer on a canvas instead of typing. → ch 4 |
direction | deck · card | Review direction: forward, reverse, both. |
sampling | deck · card | on (default) or off: whether a card table’s rows may draw Recognize options from their own column. A table’s value overrides the deck’s in either direction. |
ignore | card | Bare <!-- ignore --> in the card’s trailing machinery: the card stays in the file with its id and history but leaves review, the exam, and the counts, and it may lack an answer. For a draft you have not finished, or a card you no longer want to learn. → ch 3 |
strictness | workspace | Exam grading rigor for the members, in alix.toml’s [defaults] only: a learner setting, so a deck declaring it gets an unknown-key lint. |
requires | deck | Prerequisite deck that gates unlocks (repeatable). |
title | deck | The deck’s display name, a single non-empty line. Without it a deck is named by its condensed trace:, else by its filename stem; a # heading is never the name. → ch 3 |
description | deck | A short summary, shown in the web picker’s deck drawer. → ch 3 |
authors | deck | Who made the deck: one value or a list. Holds people and any AI that helped, so there is no separate generated-by key. Yours to fill in; alix never rewrites it. |
license | deck | The deck’s licence, a single string, by convention an SPDX identifier. |
created-at | deck | When the deck was made, a single string, by convention an ISO 8601 date. Stored verbatim and not validated. |
link | deck | tutor reference URL, tutor-only (repeatable). |
source | deck | Exam ground truth: a YAML list of URLs, files, or directories (one entry is the norm), also a trace’s cited path and a tutor reference. It identifies evidence but never grants access to a wider local tree. A workspace alix.toml may declare a source too, as supporting context for its members. |
trace | deck | What a trace walks; its presence makes the deck a trace. |
at | card | A repeatable named-field locator into the source (at: file:lines fingerprint: xxh64-..., plus asset: once frozen; a range-less path or URL cites the whole source): a trace checkpoint’s reveal target, or a fact card’s source citation shown on reveal. |
given | card | A trace checkpoint’s off-screen symbol, as name - meaning (repeatable). |
diagram | card | Machine-maintained stamp on the line after a ```mermaid fence, tying the fence text to its frozen image and geometry (fingerprint:, asset:, geometry:). Written by deck init, never hand-authored. → ch 6 |
blank | card | Masks and asks: a region of the preceding image (rect x= y= width= height= hidden="...", optional [group]) or a text span in the answer block (span hidden="...", optional occurrence=/boundary=). Carries a minted b: stamp (and position: anchor on a span), maintained by alix like ids. → ch 6 |
cover | card | Masks without ever asking, for legends and labels that give answers away: rect on the preceding image or span in the answer block. No group, no stamp, no card. → ch 6 |
crop | card | A viewport onto the preceding image (rect x= y= width= height=, at most one per image); region coordinates stay in full-source space. → ch 6 |
Media (images, and later audio/video) isn’t a directive: write a standard
Markdown  where you want one to appear, and its position decides
the side. See Image cards.
link vs source
Two that look similar but aren’t. Both point at material a deck is about, but
source is the exam’s ground truth: questions are generated from it and
answers graded against it, and a URL source doubles as a tutor reference.
link is only a tutor reference and never becomes exam material; use it
for supplementary reading the exam should ignore. The implication runs one
way: a source URL is offered to the tutor, but a link is never promoted to
a source.
Precedence
Where a directive can come from several places, the more specific wins:
card
<!-- -->> deck frontmatter > workspace[defaults]> built-in default
So a card’s reveal directive overrides the deck’s, which overrides a
workspace’s [defaults], which overrides alix’s default (flip).
The session depth (Recognize/Recall/Reconstruct) is not in this chain either: it isn’t config or a deck directive at all. It’s chosen per session (the picker’s Depth… menu), the same way for every deck (see Reveal & session depths).