Mochi Documentation


Mochi

n. (餅) A Japanese rice cake made from glutinous rice.

n. (持ち) having; holding; possessing; durability


Mochi is an app to help you remember things. It uses a flash card system called spaced repetition. This system will automatically schedule cards for review based on how well you already know them. Cards that you know well will appear less often, and cards you don't know well will appear more frequently.


Decks

All cards are stored in a deck. Decks can also be stored in other decks to create hierarchies. Decks can have custom review settings, or inherit settings from their parent, or the global settings if they have no parent.

Decks can be displayed in a few different ways. Grid view, List view, Column view, and Notebook view are all available depending on your needs. You can change the view in the upper left-hand corner of the deck page.

Sharing

Decks can be shared in a couple of different ways. Either by exporting a copy of your deck and sending it to a friend so that they can import. Or by publishing it to the web and sharing it with a link.

Exported .mochi files are just zip archives with a collection of attachments and a JSON text file. If you want to edit an export, or create one manually, simply rename the .mochi file to a .zip file to extract it.

Publishing

Decks can be published to the web. Anyone with a link to the published deck can view that deck in the browser or in the Mochi app. They can also clone the deck to their own collection and start reviewing or editing without affecting your deck.


Cards

Cards are really the heart of Mochi. They are formatted using markdown and can have one or more discrete "sides" separated by three dashes (---). The sides act sort of like the answer/question of traditional flash cards. When you review a card you can gradually reveal each side.

Cards can either be used as flash cards with the spaced repetition system, or simply as note cards. If you don't want to review your note cards, you can archive them. Mochi works particularly well as a zettelkasten notebook.

Templates

Templates speed up card creation by allowing you to re-use the same layout for all of your cards. There are two important concepts to understand when it comes to using templates:

Templates

Templates look like normal markdown notes. You can use all of the same markdown features including HTML in your templates. The content of the template will be applied to any card that uses that template. The difference is that templates can access field values in a card. You can embed field values to your template by using this syntax: << My Field >>. Templates use Mustache to render fields, so you can also use conditional tags like <<# My Field >> foobar <</ My Field>> to only display "foobar" when My Field is not empty.

Fields

Fields add structured data to your cards. Instead of writing free-form text, you'll add content to your cards through fields. For example a template might have two fields: Question and Answer. Another example might have three fields: French word, English word, Example sentence. The fields you use depend on the material you're studying.

Primary field

Within a template, there is one field that is designated as the "primary field." This field will be used to represent the card in various parts of the UI (e.g. when referencing it in markdown).

Fields also support all of the same markdown that you can use in a non-templated card (including attachments).

Example templates

The following template will display the contents of the Question Field in an H1 on the first side, and the contents of the Answer field on the second side.

# << Question >>
---
<< Answer >>

The following template will display the contents of the French word field in an H2 tag on the front side, and the contents of the English word field, followed by the contents of Example sentence in a block quote element.

## << French word >>
---
<< English word >>

> << Example sentence >>

Conditional rendering

In some cases you may want to redner some content, or prevent the rendering of content based on whether a field is populated or not. This can be achieved with conditional tags.

Example: The text "foo" will render when my field is empty.

<<^ my field >>
foo
<</ my field >>

Example: The text "foo" will render when my field is not empty.

<<# my field >>
foo
<</ my field >>

Dynamic fields

There are several types of fields at your disposal in Mochi. The basic fields like Text will just display whatever you put in them in the template. There are a whole other set of field types called "Dynamic fields" which will transform the input text into some thing else. For example the Translate dynamic field type will translate the input text from one language to another. You can then add these fields to your template like you would any other field.

You can even change the source of a dynamic field from a text input, to the value from another field. This lets you generate a variety of content from a single input.

The following is a list of available Dynamic fields and how they transform the input text.

  • Draw - Does not accept any input. Embeds a drawable canvas on the card.
  • Checkbox - Can be used to conditionally render content in the template. See the Mustache documentation for more info on conditional rendering.
  • Text to speech - Creates a text to speech audio clip from the input text and embeds it into the card.
  • Image search - Performs an image search with the input text and embeds the result into the card.
  • Translation - Translates the input text from one language to another. (Note: the translated output can be used as the input for another dynamic field)
  • Dictionary - Looks up the definition of the input text in the specified dictionary, then displays it in the card.
  • Transcription - Takes an audio file and transcribes the spech into text that can be displayed on the card. Contents of the field should be a single audio file embedded as markdown. E.g. ![](my_audio_file.mp3).
  • AI Text Generator
    • Create flashcard - Creates a question / answer style flash card from the given text.
    • Create question - Generates a question based on the given statement.
    • Example sentence - Will create an example sentence for the given word.
    • Reword a sentence - Will reword the given sentence.
    • Create LaTeX expression - Will generate a LaTeX expression from the given text.
    • Custom - Send a custom prompt to the AI. If markdown is returned, it will be rendered. You can also access other fields in the prompt.
  • Chinese Pinyin - Adds pinyin pronunciation ruby characters to Chinese text.
  • Japanese furigana - Adds Japanese furigana pronunciation ruby characters to Japanese text.

Dynamic Elements

Like other markdown renderers, Mochi can render a subset of HTML within your cards. Mochi also comes equipped with some custom HTML elements that provide additional functionality.


<input>

Creates a text box for typing an answer. The typed answer will be checked against the value of the value attribute.

Attributes:

  • value - String - The value to check the typed answer against. You can provide multiple variants by separating them with a pipe (|) character. To require multiple correct answers, you can separate them with an ampersand (&).

  • type - String - "text" | "number"

  • inline - Boolean - Whether the input should appear inline within a line of text, or on a new line by iteself.

Example:

The capital of France is <input value="Paris" inline>.
A type of pastry made from leavened fried dough:
<input value="donut|doughnut">
Flu symptoms:
<input value="fever & cough & fatigue & sore throat & headache">

<draw>

Creates a drawable canvas on the card. The size of the canvas can be set using the width and height properties. Accepts the following attributes:

Attributes:

  • brushRadius - Integer - The size of the brush.

  • brushColor - CSS <color> - The color of the brush.

  • width - CSS <length> - The width of the canvas.

  • height - CSS <length> - The height of the canvas.

Example:

<draw height="200px" brushColor="#FF0000" brushRadius="4"/>

<furigana>

This component will add phonetic hiragana above above Japanese kanji. The text can contain a mixture of kanji, hiragan, and katakana, but should have at least one kanji character to function properly. The mode attribute can be one of normal, spaced, okurigana, or furigana. Defaults to okurigana. The to attribute can be one of hiragana, katakana, or romaji. Defaults to hiragana.

Example:

<furigana>例えば</furigana>

<pinyin>

This component displays Pinyin romanization above chinese characters, including tone denoting diacritic marks.

Example:

<pinyin>中心</pinyin>

Tags

You can add tags to a card by typing a # followed by the tag name. For example #food. A list of tags used will appear on the left side bar based. This list is derived from the tags used in cards and cannot be modified without modifying the cards that use them.

Hierarchical tags

You can create nested tags by adding forward slashes (/) in your tags. For example #sports/basketball/stats will create a #stats tag that is nested under the #basketball tag which is in turn nested under the #sports tag.


Markdown

Mochi support most standard markdown features in addition to some special extensions like $\LaTeX$, {振}(ふ)り{仮}(が){名}(な), ==highlighted text==, and {{cloze deletions}}. You can take a look at this guide for more help on makdown generally, or click the keyboard icon (desktop only) on the bottom right for more hints.

Adding Sides

Like traditional flash cards, Mochi cards can have one or two sides. You can separate "sides" in a card by adding three dashes on its own line: --- The content above the line will be the first side, and the content below will be on the second side. When reviewing cards, only the first side will be shown, and you can press the space bar to reveal the next side. But why stop at two sides? With Mochi you can add as many "sides" as you want, and they will be revealed one at a time.

Cloze deletions

Cloze deletions are a way of hiding information within a card when it's being reviewed.

Simple deletions

Mochi supports simple cloze deletions with the following markdown syntax:

The Shiba Inu is a breed of {{hunting dog}} from {{Japan}}.

Where both "hunting dog" and "Japan" will be hidden when the card is reviewed.

Cloze deletion groups

You can also prefix an index number to your cloze deletions to create separate cloze groups for your card, one for each index, where only one cloze group will be hidden at a time. For example:

The {{1::Shiba Inu}} is a breed of {{2::hunting dog}} from {{2::Japan}}.

In this example, you will be shown two different versions of the card, one where "Shiba Inu" is hidden, and one where "hunting dog" and "Japan" are hidden. These two versions will have their own review shedule and history.

References

You can make references to other cards or decks using MediaWiki syntax:

[[My card|the-card-id]] or just [[the-car-id]]

The text before the pipe | character will be displayed as the title of the link, and the text after the pipe is the card or deck ID. If no title is provided then the title of the card will be pulled dynamically based on the contents of the card.

You can open the referenced card in editing mode by holding command on Mac or control on Windows/Linux and clicking the reference text.

Cards that link to another card will be back referenced by the card that was linked to.

You can also embed one card inside of another by prepending a !:

![[the-card-id]]

This will embed the entire card contents seamlessly inline with the current card. To only embed a single side, you can use this variation:

![[the-card-id/1]]

Where 1 is the side number (in this case the first side). You can also embed attachments from other cards:

![[the-card-id/file-name.jpg]]

And finally you can embed individual fields using the field id:

![[the-card-id/field-id]]

To embed the entire card with a border you can use this syntax:

[[the-card-id:embed]]

Attachments

Media can be attached by dragging and dropping a file onto the editing area, or pasting an image that's been copied to the clipboard. The media will be stored locally and displayed using standard markdown syntax.

![Some Image](image-name.jpg)

The above syntax will work for audio and video files as well. If the card is deleted, the associate media will be deleted as well.

For images, you can adjust the dimensions by adding |800x600 to the image title. The first number will be the width, and the second number the height. If you exclude the height, the image will resize proportionally.

![Some Image|800x600](image-name.jpg)
![Some Image|800](image-name.jpg)

Ruby / furigana annotation

Some languages (like Chinese or Japanese) which have words that cannot be read phonetically, so it is useful to annotate them with phonetic readings. You can accomplish this using the following syntax:

{持}(も)ち

HTML

If markdown isn't enough, you can also add HTML to your cards. For example, to change the color of a word you can write: <span style="color:red">foo</span> which will look like this: foo.


Spaced repetition

Spaced repetition is a very powerful flash card scheduling system. It exploits something called forgetting curve, which describes the fact that it takes longer to forget something if you are reminded of it right before you forget it.

Mochi's spaced repetition algorithm is very simple. Each time you remember a card, the time it takes before it's reviewed again doubles. When a card is forgotten that time is cut in half. These settings can be tweaked in the settings, and different decks can have their own settings.

Learning new cards

New cards are not immediately placed in the review schedule. That is what the New cards section is for. This is useful in case you want to add a lot of cards up front, or are importing a deck form somewhere else and want to gradually add cards to your review schedule.

You can learn all new cards in your collection by clicking "New cards" in the left side bar. Or you can learn new cards for a single deck by clicking the "New cards" button at the top of the deck page.

You can limit the number of new cards that will be shown each day in the review settings. The setting can be adjusted for the entire app, or for individual decks.

Tip: If you want to use a deck as a notebook, you can limit the new cards to 0, or archive it.

Reviewing cards

When a card is due, it will show up in the "Due today" screen. The cards will be presented in random order, and cards that are past due (due yesterday or earlier) will be shown first. If you miss a card, you'll have an opportunity to re-review it at the end.

Reverse reviews

Normally when reviewing a card, the first side is revealed, followed by the second side (and so on if there are more than two sides). When the "reverse reviews" option is enabled, the card will also be shown with the last side revealed, followed by the side before it, and so on.

This allows you to, for example, test recognition and recall with a single card. There will be two separate review histories for each direction.

Reverse reviews can be enabled globally, per deck, or per card.

Cramming

In addition to the other two modes, you can also review your cards outside of the spaced repetition schedule. The "Cram" button allows you to review all of the cards in your deck regardless of whether they're due. Reviews. in this mode will not affect the standard spaced repetition scheduling.

Additionally, if any filters or search terms are applied to the deck, the Cram mode will only show cards from the filter / search results. For example, you can filter for cards that have a retention rate less than 80%, and do a cram on just those cards.

Archiving

Cards and decks can both be "archived." When a card is archived, it will not show up in the "New cards" section, or in the "Due today" section. Its review history will remain unchanged.

To view all of the archived cards in a deck, you can apply a filter for archived cards in the corresponding deck page.

When a deck is archived, all of the cards in that deck will effectively be archived.


Import and export

Mochi supports various import and export options to maximize portability of data, and allow users to easily share decks with each other.

.mochi format

Decks can be exported as .mochi files. This format will export all cards within a particular deck as well as various metadata such as review history, card order, etc.

Anki .apkg format

Mochi supports importing Anki .apkg files. Because of the differences between Mochi and Anki, however, Anki cards will not necessarily import exactly as they appear in Anki. For best results, consider editing the templates of your Anki decks to remove extraneous HTML and remove all CSS and Javascript before exporting. When imported into Mochi, the CSS and Javascript will be removed, and the HTML will be converted to markdown, so the cards should work in Anki without any CSS or Javascript.

Markdown format

You can also choose to export your decks as a collection of markdown files. At the moment this export format does not preserve metadata like review history, card order, etc.

You can also import individual markdown files into Mochi to create cards. You can either import a collection of files, in which each file will be imported as a card, or you can import a single file and choose a delimiter to create multiple cards per file.

CSV format

When importing using a CSV file, each row will be imported as a card.

When importing into a deck with a template, each column will be interpreted as a field on the template. The header value of the column will determine which field in the template it corresponds to. You can either use the field name, or it's ID as the header value.

When importing into a deck without a template, each column will be interpreted as a separate side on the card.


Keyboard shortcuts

Mochi is designed to get out of your way so that you can learn as quickly and easily as possible. To that end almost every action on every screen has keyboard shortcuts. For example d will delete a note or card, space will reveal the next side of a card, e will edit a note or card, etc.

You can press ? at any time, or click the keyboard icon in the bottom right to see a list of keyboard shortcuts for the current screen.


Embedding Mochi on your site

You can embed the entire Mochi application within your website using an iframe. There are several query parameters that can be appended to the URL to customize the look and feel of Mochi while it's embedded, similar to embedding a youtube video. The available options are as follows:

  • hide-sidebar : boolean
  • Controls whether the left hand side bar is hidden by default or not.
  • hide-sidebar-toggle-button : boolean
  • Controls whether the button that toggles the sidebar visibility is displayed or not.
  • page : cram | learn
  • Determine which screen to load on first.