ARMS documents are mostly “normal document” (Markdown or LaTeX), with a small set of ARMS tags to describe cards and metadata.
Let’s see a real example note:
Today we are learning some basic arithmetic, the peano axioms for natural numbers.
<card>
<front>
What is a natural number?
</front>
<back>
**Definition**: A natural number is either $0$ (zero)
or a successor of a natural number $S(n)$.
</back>
</card>
Once the natural number is defined, we can define what addition is.
<card>
**Definition**: Addition is defined by the following rules:
- For any natural number n, <cloze>$0 + n = n$</cloze>
- For any <cloze>natural numbers m and n, $S(m) + n = S(m + n)$</cloze>
</card>
**Example**.
<card>
Let's compute 2 + 2.
$$
\begin{align*}
2 + 2 & = S(S(0)) + S(S(0)) \\
& = <cloze>S(S(0) + S(S(0)))</cloze> \\
& = S(0 + S(S(S(0)))) \\
& = S(S(S(S(0)))) \\
& = 4
\end{align*}
$$
</card>ARMS tags look like HTML/XML: they have opening tags <tag> and closing tags </tag>. For example:
<card>
<front>This is the front of the card</front>
<back>This is the back of the card</back>
</card>Only a specific set of tags are treated specially (e.g. card, front, back, meta, …). Other <...> sequences are treated as normal text.
A card with its front and back explicitly described:
<card>
<front>What is 2 + 2?</front>
<back>4.</back>
</card>A card using cloze deletion:
<card>
The capital of France is <cloze>Paris</cloze>.
</card>For this card, its front will show “The capital of France is (…).”, and its back will show “The capital of France is Paris.”
During “Generate preview / Confirm generation”, arms will insert a stable UUID for each card present in your note:
<card uuid="c52b1550-18da-41b2-8ca7-83850bc0444c">
<front>...</front>
<back>...</back>
</card>If a card already has a UUID, the system preserves it (identity persists). If you change or remove the UUID, you will be generating the same card again.
Anything outside <card>...</card> is just note content, they won’t be part of any card.
You can also explicitly mark “common content”:
I'm just part of the note. I don't appear in any card.
<common>
I am also part of the note, but I appear in all cards, front and back.
</common>Common block is included in both front and back. Outside any card block, it’s also included in all cards!
Inside a common block, you can mark a cloze deletion:
<common>
The capital of France is <cloze>Paris</cloze>.
</common>The renderer can render a placeholder for the front, and render the original content for the back.
Note: You cannot cloze inside front or back, cloze must be inside a common block. Right now, in <card> blocks, any text outside <front>...</front> and <back>...</back> is treated as common content, so using <common> is optional.
You can embed comments that are kept in the document structure:
<comment>
This is a comment. It does not go into cards or being displayed when you view notes.
</comment>ARMS supports meta and configs:
<title>My Note Title</title>
<author>Your Name</author>
<description>Short description.</description>
<configs>
<clozePlaceholder>(...)</clozePlaceholder>
</configs>You can ignore them at first; it’s optional.
uuid="..." will help it remain “the same card”. Delete the uuid="..." if you want them to be different cards.You can mark sections of your document and include them elsewhere.
<mark id="section1">
This is section 1.
</mark>
<card>
<include id="section1">
This is additional common content for the card.
</card>
<mark id="definition-lie-algebra">
**Definition**: A Lie algebra $\mathfrak{g}$ over a field $K$ is a vector space
over $K$ equipped with a bilinear operation
$$[ \cdot , \cdot ] : \mathfrak{g} \times \mathfrak{g} \to \mathfrak{g}$$
called the *Lie bracket*, satisfying the following properties:
1. **Antisymmetry**: For all $x, y \in \mathfrak{g}$, $[x, y] = -[y, x]$
2. **Jacobi Identity**: For all $x, y, z \in \mathfrak{g}$,
$$[x, [y, z]] + [y, [z, x]] + [z, [x, y]] = 0.$$
</mark>
<card>
<front>
What is the definition of a Lie algebra $\mathfrak{g}$ over a field $K$?
</front>
<back>
<include id="definition-lie-algebra">
</back>
</card>The closing tag of <include> is optional.
Include can be recursive, but can not form cycles: it can only include previously defined marks, not the ones defined later.
Mark can also mark a block, but it must be a single block with no other content outside.
<mark id="something"><front include-in-card="false">
This is the front of the card.
</front></mark>
<card>
<front>
<include id="something">
</front>
<back>
This is the back of the card.
</back>
</card>include-in-note and include-in-card attributesYou can control whether the content should appear, for example you can create a card or a block that does not appear in the note but only in cards:
<common id="ref" include-in-card="false">
This content appears only in notes, not in the cards.
But you can use `<include id="ref">` to include it (in cards or note) again.
</common>
<card include-in-note="false">
This content appears only in cards, not in the note.
<include id="ref">
</card>Alternatively, we now support <block include-in-note> and <block no-include-in-note> as well as <block include-in-card> and <block no-include-in-card> to control inclusion, here block can be any block.
You can omit the <common>...</common> wrapper inside a <card>...</card>, in which case all content inside the card is treated as common content.
<card>
This is all common content in the card.
</card>The include command now supports uncloze attribute to remove all the cloze tags inside the included content.
<card id="capital-france">
The capital of France is <cloze>Paris</cloze>.
</card>
<card>
<include uncloze id="capital-france">
In Paris, there is the <cloze>Eiffel</cloze> Tower.
</card>