Decks and cards
A deck is one concept. It is the only thing you teach with. A deck holds its cards, its flashcards and its references. Everything above a deck, a topic, a section and a domain, collects from the decks under it.
A card is one step of a deck. It holds one idea. The learner reads the cards of a deck one after another, in one scroll.
A deck file
A deck is a .md file in a topic directory. Its filename stem is its id. It has front matter, then its blocks.
---
title: Ohm's law
---
::: card
Three quantities, one relationship. Ohm's law says the current through a conductor equals the
voltage across it divided by its resistance.[Ohm's law](reference:ohms-law)
$$ I = \frac{V}{R} $$
More voltage drives more current; more resistance allows less.
:::
::: card
You will most often use it rearranged as $V = I R$, which gives the voltage drop across a
component from the current through it and its resistance.
:::
::: flashcard q1
A 9 V supply is connected across a 3 Ω resistor. What current flows?
::: answer
$I = V / R = 9 / 3 = 3\ \text{A}$. Divide the voltage by the resistance.
:::
:::
::: reference ohms-law
# Ohm's law
The current through a conductor equals the voltage across it divided by its resistance.
::: equation
I = \frac{V}{R} \qquad V = I R \qquad R = \frac{V}{I}
:::
:::
Front matter
| Field | Is |
|---|---|
title | the name of the deck. Without it, the app shows the full id of the deck. |
draft | true holds the deck back (The tree) |
The front matter of a deck has no other fields. Any other field is an error, and the checker names the fields it takes:
ERROR ./math/alg/linears/solving.md: `titel` is not a field of a deck: a deck takes title, draft
A deck declares no id: its id is its filename stem.
Add the id of each new deck to the order of its topic.
What a deck holds
A deck holds four blocks at its top level, and nothing else:
| Block | Is |
|---|---|
::: card | one step of the concept |
::: figure | a picture with a caption, as a card of its own |
::: flashcard | a flashcard (Flashcards and solutions) |
::: reference | a result to look up (References and derivations) |
Write the cards and the figures first, in the order the learner reads them. Write the flashcards after them, then the references. A flashcard between two cards is inline: the learner meets it in the deck.
Text outside a block is an error. The app does not show it, so the checker reports it at its first line. Put all prose inside a card:
ERROR ./math/alg/linears/solving.md:5: this text sits outside any block, so the app never shows it: put it in a `::: card`, or take it out
A card
A card opens with ::: card and closes with :::. Between the two lines, write Markdown:
- prose, with
*italic*,**bold**,`code`and lists - inline math,
$a x + b = 0$, and display math,$$ x = 3 $$(Math, figures and assets) - a picture from an
assets/directory, - one live plot, as a fenced
plotblock (Live plots) - links to references,
[Ohm's law](reference:ohms-law), and to figures,[Figure](figure:gravity-field)
The app numbers the cards of a deck from 1, in order. A word after ::: card has no effect: a card has no id of its own.
A card that holds a plot draws it after its prose, at the end of the card. A card draws one plot. A second plot in one card is an error:
ERROR ./math/alg/linears/solving.md:11: this `card` already holds a `plot` block, and a card draws only one: put the second plot in a card of its own
A figure
A figure is a card with a picture and a caption. The app shows it as a card of its own, and puts Figure N. before the caption.
::: figure gravity-field
Earth's gravitational field reaches every point of the surrounding space, drawing the distant
Moon inward across the emptiness.
:::
The word after ::: figure is its id. Without an id, the figure takes f1, f2, in order. Two figures in one deck cannot share an id. A figure counts as a card, so it takes a card number too. A figure can hold one plot, as a card can.
A card links a figure of the same deck by its id:
The Moon feels it across 380,000 km of empty space ([Figure](figure:gravity-field)).
The app replaces the link with Figure N, where N is the number of the figure in the deck. The text of the link is not shown. So insert or move figures freely: each link follows its figure. A figure: link works in the cards and the flashcards of the same deck only. A link to no figure is an error:
ERROR ./math/alg/linears/solving.md:6: `figure:nope` names no figure in this deck
One idea per card
A card holds one idea, in a short text. The Course is a scroll, so a card has no fixed frame. It is as long as its text, and it never scrolls inside itself. Only the author keeps it short.
- One idea. A card with two ideas is two cards.
- In order. Each card rests on the cards before it. Do not refer forward.
- Concrete first. Say what happens, then give it a name.
- Move long proofs out. A derivation that grows belongs in a reference. Link the reference from the card with
[label](reference:id). - No recap. A card states its idea once and stops.
A deck is short too. The decks of Stemin Foundations hold between two and eight cards, and most hold three to five.
Ids and progress
The app records which cards the learner saw, per deck. A refresh keeps that record when a deck keeps its id, or when a renamed deck keeps the same cards. Publish and add to Stemin gives the rules.