> ## Documentation Index
> Fetch the complete documentation index at: https://docs.amgi.study/llms.txt
> Use this file to discover all available pages before exploring further.

# Card format

> Write basic cards, clozes, notes with fields, media, math and code in plain Markdown.

```markdown theme={null}
Q: What does **FSRS** stand for?
A: Free Spaced Repetition Scheduler

C: The capital of [France] is [Paris|city].

C: \[H⁺\] is the [concentration] of hydrogen ions; `v[0]` is the [first|which?] element.
```

* `Q:` / `A:`: basic card. Either field can continue onto later lines.
* `C:`: cloze. Each `[answer]` becomes its own card; `[answer|hint]` shows the hint.
  Write `\[` and `\]` for literal brackets. Brackets inside `` `code` `` are always literal.
* Images: `![](../media/photo.jpg)`, with the path relative to the deck file: from a deck
  in `cards`, `../media` is the collection's `media` folder. Use `![](<my photo (1).jpg>)`
  for paths with spaces or parentheses. An image can also be a cloze answer:
  `[![](flag.png)|flag]`.
* Sounds use the same syntax: `![](audio/word.mp3)`. Links to audio files (`mp3`, `m4a`,
  `wav`, `flac` and other formats macOS can play) show as play buttons. A card's sounds
  play when it appears, and the answer's when it is shown; press <kbd>R</kbd> to replay.
  Turn autoplay off in **Settings** (<kbd>⌘,</kbd>).
* Math: `$…$` inline and `$$…$$` for display, in TeX, turned into MathML by
  [Temml](https://temml.org) and drawn by WebKit in the system's math font. Brackets and `|` inside math are literal, so they never
  start a cloze. A `$` only starts math before a non-space (`$5 and $10` stays text);
  write `\$` for a literal one.
* Code: fenced blocks (` ```python ` … ` ``` ` or `~~~`) are highlighted by
  [Shiki](https://shiki.style) in any of its 200+ languages, with GitHub's light and dark
  themes. Each language's grammar loads the first time a card uses it. Blank lines and
  `Q:` lines inside a block stay part of the card. Brackets in code are literal, so a cloze
  gap in a code block or `` `span` `` is written `{{answer}}` or `{{answer|hint}}`:

  ````markdown theme={null}
  C: Raise a matrix to a power with the [expm|package] package:
  ```r
  powmat <- {{expm|function}}(1.1 * logm(mat))
  ```
  ````
* Chinese, Japanese and Korean text is set in Source Han Serif (Noto Serif CJK). Its
  fonts, about 6 MB per language, are downloaded from the
  [Amgi releases on GitHub](https://github.com/alisheryeginbay/amgi/releases) the first
  time a folder's decks use Hangul, kana or Han characters; until then the Mac's own
  serif stands in. Han characters take the forms of the Mac's first Chinese, Japanese or
  Korean language in **System Settings ▸ General ▸ Language & Region**, or Simplified
  Chinese when there is none.
* A card ends at a blank line or the next `Q:` / `C:` outside a code block. Every other
  line is ignored.

A card's identity comes from its text (the question for basic cards, the whole text
for clozes). You can move or reorder cards, fix answers and change tags without losing
history. Editing a question starts the card over.

## Tags and deck settings

End a card with a line of tags. A file can start with TOML front matter between `+++`
lines: `name` is the deck's display name and `tags` are added to every card in it.

```markdown theme={null}
+++
name = "Korean verbs"
tags = ["korean"]
+++

Q: 가다
A: to go
#verbs #motion
```

Tags go on the card's last lines, after its first one, and only a line made entirely
of `#tag` words counts, so a `# Heading` stays text. Pick a tag in the sidebar to browse
its cards across decks. Right-click a tag and choose **Choose Icon…** to give it an emoji:
type to search by name or keyword, use the arrow keys to move, and press <kbd>Return</kbd> to
choose. Icons are kept in `.amgi.sqlite`.

## Notes with fields

Besides `Q:` and `A:`, a card can come from a **note**: named fields, such as a word, its
meaning, its audio and an example sentence, that make one or more cards. Which fields a
note has, and which cards it makes, is its **note type**: a file in the `note-types`
folder at the root of the collection.

```toml theme={null}
# note-types/Vocabulary.toml
fields = ["Word", "Meaning", "Audio", "Sentence"]
cards = [
  "Word, Audio -> Meaning, Sentence",
  "Meaning -> Word",
]
```

A note starts with a line naming its note type after `@`, then its fields:

```markdown theme={null}
@Vocabulary
Word: manzana
Meaning: apple
Audio: ![](../media/manzana.mp3)
Sentence: Me como una manzana.
#food
```

* Fields can come in any order and continue onto later lines. The note ends at a blank
  line, a `Q:` or `C:`, or the next `@` line. Tags go on its last lines, as on any card.
* Each rule in `cards` makes one card: the fields before `->` on the front, the ones
  after it on the back, in that order. The note above makes two cards.
* With `=>` instead of `->`, as in `"Meaning => Word"`, you type the answer: the first
  back field the note fills. A box under the question takes it, <kbd>Return</kbd> shows
  the answer, and what you typed is shown against it, with wrong letters struck out and
  missing ones marked. Changing a rule between `->` and `=>` keeps its cards' history.
* Put an audio field right after the field it belongs to, as in
  `"Meaning -> Word, Word Audio"`: a sound after text plays from a button at the end of
  that text.
* Empty or missing fields are left out of a card, so a note without `Audio` shows just
  the word. A card is made only when it has a front field and a back field to show.
* Without `cards`, the first field is the front and the rest the back.
* Notes of any types and `Q:`/`C:` cards can share a deck. Field names are
  case-sensitive, and a line such as `Meaning: …` outside a note, or an `@` line inside a
  `Q:` or `C:` card, is just text.
* A card is identified by its front, like a `Q:` card with the same question. Editing
  back fields, reordering a note's lines or renaming a field keeps its history; editing
  a front field starts that card over. Suspending a card suspends its whole note.
* Problems in a note type, such as a rule naming a field that isn't in `fields`, are
  reported at its file; an `@` line naming a note type that doesn't exist says so.

## Suspending cards

A card tagged `#suspended` never comes up for study, and isn't counted as due or new;
`tags = ["suspended"]` in a deck's front matter suspends the whole deck. **Suspend Card**
in the toolbar while studying, or right-clicking cards while browsing, adds or removes the
tag in the file for you. Tags aren't part of a card's identity, so it keeps its history.
Pick the `suspended` tag in the sidebar to see them all.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.