Mochi Markdown and Cloze Guide
Every Mochi card is a small Markdown document, which is why formatting that looks fine in the editor sometimes splits a card in half. Here is the syntax that matters day to day, how hidden text and numbered groups actually behave, and how audio rides along inside the deck file.
The Markdown a Mochi card understands
Mochi does not have fields. A card is one document, and the line of three dashes in the middle is the only structural rule you cannot break. Everything else is ordinary Markdown, rendered on every single review.
| What | Syntax | Detail |
|---|---|---|
| The two sides of a card | front\n---\nback | A card is one Markdown document split by a line containing three dashes. Everything above is the prompt, everything below is the answer. This is also why a card that starts with a horizontal rule breaks: Mochi reads the rule as the split. |
| Headings | ## Word or question | Headings render larger and heavier. A single level-two heading on the front is the common shape for a vocabulary card; deeper levels are for structure inside a longer answer. |
| Emphasis | *italic* and **bold** | Useful for the part of the answer that carries the meaning: the gender of a noun, the stressed syllable, the preposition a verb takes. |
| Lists | - item, or 1. item | The readable way to hold two or three senses of a word on the back without turning the card into a paragraph. Keep it to a handful of items: a card with ten bullets is a note, not a flashcard. |
| Code and inline code | `inline` or a fenced block | Not only for programming: a monospaced span is the cleanest way to show a spelling, an IPA transcription, or a form you do not want the reader to gloss over. |
| Quotes | > quoted line | Good for an example sentence taken from a source, visually separated from your own explanation. |
| Attachments |  | References a file that ships inside the same .mochi archive. Images render inline; audio files render as a small player on the card. |
If you are still setting the deck up, creating Mochi cards step by step covers the surrounding workflow, and Mochi best practices covers what belongs on a card in the first place.
Hidden text, numbered groups and media
Cloze in Mochi is not a card type you switch on. It is syntax inside the same Markdown, which means any card can become a cloze card by adding braces, and a deck can mix both freely. Anki does the opposite: cloze there is a separate note type with a numbered marker, covered in the guide to Anki cloze cards.
Basic hidden text
W {{schronisku}} ogladamy psy, ktore czekaja na nowy dom.- The hidden span can be a word, a phrase, or a whole clause: Mochi does not care where the boundaries fall.
- Everything outside the braces stays visible, so the sentence around the gap is what makes the answer recoverable.
- One card, one review. A sentence with a single hidden span behaves like a normal two-sided card that happens to show context.
Numbered groups
{{1::Insulin}} is produced by the {{2::pancreas}}.- Each numbered group becomes its own review variant with its own schedule and history, rather than one card with two blanks.
- That is powerful for facts with two independent halves, and wasteful for language sentences where you only want to recall one word.
- Spans sharing the same number are revealed together, which is how you hide a separable verb or a multi-word expression as a single answer.
Typing the answer
Przed wyborem psa idziemy z nim na {{spacer}}.- Typing forces production instead of recognition, which is the harder and more useful direction for vocabulary you intend to actually use.
- It also punishes near-misses: a missing diacritic counts as wrong, so turn it on when spelling matters and off when it does not.
- The setting is global, not per card, so decide it for how you study rather than per deck.
Media next to the gap
Hodowca zalecil stopniowe {{przyzwyczajanie}} szczeniaka.
- The path is relative to the archive: put the file in the zip next to data.edn and reference it as @media/name.
- Mochi's own export format reference documents the archive but not this reference syntax; we established it by exporting a card with an attachment and reading the archive, and it is what NextLang writes.
- Because the audio is inside the file, a cloze deck keeps speaking offline and on any device you sync to, with no Mochi Pro subscription involved.
Writing cloze cards that are worth reviewing
The syntax takes a minute to learn. Deciding what to hide is the part that determines whether the deck teaches you anything, and it is where most hand-written cloze decks go wrong.
| Rule | Short version | Why |
|---|---|---|
| One gap per sentence | for language decks | Two blanks in one sentence remove the context that makes the third word guessable. Hide the item you are learning and leave the rest as scaffolding. |
| Hide the word, not the grammar | content over function | Blanking a preposition or an ending teaches a rule; blanking the noun teaches vocabulary. Both are valid, but a deck that mixes them at random tests nothing in particular. |
| Keep the sentence short | 8 to 15 words | Long sentences are slower to read on every single review, and the extra clauses rarely add recall value. If the sentence needs a comma-heavy subordinate clause to make sense, the word probably needs a simpler example. |
| Sentence at your level, word above it | scaffolding rule | The grammar and surrounding vocabulary should be things you already know, so the hidden word is the only new element on the card. The word itself may be harder than your level; its sentence must not be. |
| Inflect the hidden word naturally | not the dictionary form | In inflected languages the point is producing the form the sentence requires. A card that expects a nominative singular inside an accusative slot trains the wrong answer. |
Have the sentences in a spreadsheet already? CSV to Mochi converts them in your browser, braces included, without uploading the file anywhere.
Generating, voicing and migrating cloze decks
Writing one good cloze sentence is pleasant. Writing two hundred is the reason most people abandon the format. Here is what changes when the sentences, the audio and the syntax are produced for you.
Writing good cloze sentences by hand is the slow part: you need a natural sentence, at your level, with exactly one useful word to hide, and a translation to check yourself against. NextLang's Mochi generator has a Card type switch. Pick Cloze, and every card comes out as a sentence in the language you are learning with one word wrapped in Mochi's own syntax, the translation on the back, and the target level applied to the hidden word rather than to the sentence around it. The file you download is a .mochi archive, so the blanks are native from the first review.
Mochi's REST API needs a Pro subscription, but the file format does not: an archive may carry media files next to data.edn. NextLang uses that route, so a generated cloze deck arrives with an mp3 of the full sentence attached to each card and a player under the text. You hear the sentence pronounced by a native-quality neural voice, including the word you just recalled, which is the part a written blank cannot teach. Nothing is fetched at review time, so it works offline.
The two apps mean the same thing with different syntax: Anki writes {{c1::word}} and Mochi writes {{word}}, with Mochi's numbered form {{1::word}} playing the role of Anki's c1, c2 groups. A raw Anki export dropped into Mochi therefore shows the c1 prefix as literal text unless something rewrites it. Our Anki to Mochi converter and the Mochi generator both write the Mochi form directly. The migration guide covers what else changes shape on the way across.
Cloze is strong for words that live inside a construction: verbs with a fixed preposition, collocations, cases and aspect pairs. It is weak for pure labels, where a picture or a bare pair is faster, and for anything you want to recall in both directions, since a blank only ever tests one. A healthy deck usually mixes both card types rather than converting wholesale.
Everything you can do with Markdown, you will see on every repetition. Bold on the answer half is worth it; a heading, a quote and three bullets on one card is not. Keep the front to the sentence, put the translation and any note under it, and reserve emphasis for the one detail that decides whether your answer was right. If a card needs a table to be understood, it is a document, not a flashcard.
Premium access includes:
Frequently asked questions
No. Mochi hides text wrapped in double curly braces, as in {{word}}, and uses {{1::word}} when you want numbered groups. Anki uses {{c1::word}} for every deletion. Pasting Anki text into Mochi leaves the c1 prefix visible on the card, so the syntax needs rewriting on the way across.
For language learning, one. Each numbered group in Mochi becomes a separate review, so a sentence with three groups produces three cards from one piece of context. That is efficient for independent facts and counterproductive for a sentence whose whole job is to give one word its context.
Yes, and it does not need Mochi Pro. Put the mp3 inside the .mochi archive and reference it from the card as . Mochi renders a small player. Decks generated by NextLang with audio enabled already ship this way.
A line containing only three dashes separates the front from the back. If your content itself contains a horizontal rule, Mochi treats the first one as the split. Escape it or use a different visual break inside the card body.
Yes. CSV carries plain text, and Mochi parses whatever Markdown that text contains when it renders the card. That includes cloze braces, which is how a spreadsheet of sentences can become a cloze deck through our CSV to Mochi converter.
Turn on Type hidden text in Mochi's preferences. The blank becomes an input and Mochi checks your answer, diacritics included. It is a global setting rather than a per-deck one.
Keep reading
Related guides that build on what you just read.