ARMS Document Syntax Reference

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><common>
**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>
</common></card>

**Example**.

<card><common>
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*}
$$
</common></card>

ARMS Tags

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.

Card Examples

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><common>
The capital of France is <cloze>Paris</cloze>.
</common></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.

Common content vs cards

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!

Cloze Deletions

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.

Comments

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>

Meta information (optional)

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.

Practical tips

• You do not need to learn all ARMS tags to start, just start with the card examples as templates.
• If you copy/paste a card block between notes, its uuid="..." will help it remain “the same card”. Delete the uuid="..." if you want them to be different cards.
• If you share your note with others, you may want to remove the UUIDs (so they get new cards instead of overwriting yours).