An API for generating Anki decks.
Anki is a tool for spaced-repetition study.
Note: This is a fork of nornagon/mkanki.
For examples of how to use this library, see the examples folder.
npm install --save mkanki
First, some information about how Anki works.
In Anki, things to be remembered are called notes. Each note can have several fields—most commonly, a "Front" and a "Back", but the fields can be arbitrary. Each note can potentially correspond to many individual cards, each of which should help you remember one facet of the note.
The thing that describes how those fields are turned into flashcards is called a model. Every note is described by exactly one model. The model defines which fields are allowed, and additionally defines one or more templates, which are written as HTML with mustache-like placeholders.
Finally, each card belongs to a deck. Decks collect cards into logical groups that you might want to study separately from each other.
Models, notes, cards and decks are the fundamental concepts of Anki. In mkanki, cards are implicitly defined by notes and models, and you will only deal with models, notes, and decks.
Anki supports two types of models: standard and cloze. Standard models generate one card per template, while cloze models generate one card per cloze deletion. See the Anki cloze documentation for more on cloze deletion.
Create a new standard model with the given properties. props
is an object
with the following fields.
id
string - a stable, unique identifier for this model. Generate this once with+new Date
and then hard-code it into your code. Keeping this stable means that if the package is updated and re-imported into Anki, the app will be able to tell which cards are new and which cards should be merged into already-existing cards, preserving study history.name
string - the name of the model. Shows up in the "Add" UI in Anki.flds
Array<{name: string}> - the fields in the model.tmpls
Array<{name?: string, qfmt: string, afmt: string}> - a list of card templates to be generated from each note.qfmt
is the HTML template for the question, andafmt
is the HTML template for the answer.name
is displayed in the configuration screen in Anki and nowhere else, and will default to "Card N". See the Anki template documentation for more on template formatting.req
Array<[number, "all" | "any", Array<number>]> - this describes which fields must be non-empty in order for a card to be generated. Each entry in this list is a tuple of the template index, "all" or "any", and a list of field indices. In order for a card to be generated for a given note and template, one or all of the fields specified in the field list must be non-empty. If the requirement isn't met for a given (template, note) pair, no card will be generated.
Create a new cloze model with the given properties. props
is an object with
the following fields.
id
string - a stable, unique identifier for this model. Generate this once with+new Date
and then hard-code it into your code. Keeping this stable means that if the package is updated and re-imported into Anki, the app will be able to tell which cards are new and which cards should be merged into already-existing cards, preserving study history.name
string - the name of the model. Shows up in the "Add" UI in Anki.flds
Array<{name: string}> - the fields in the model.tmpl
{name?: string, qfmt: string, afmt: string} - the cloze template to be generated from each note.qfmt
is the HTML template for the question, andafmt
is the HTML template for the answer.name
is displayed in the configuration screen in Anki and nowhere else, and will default to "Cloze". See the Anki template documentation for more on cloze template formatting. Cloze models can only have one template.
Create a note using this model.
fieldValues
Array<string> | {[fieldName: string]: string} - IffieldValues
is an array, the order of fields will be matched with the order of theflds
in the model. IffieldValues
is an object, the keys must be the names of fields in the model.guid
string (optional) - a stable, unique identifier for this note. When re-importing an updated version of this note, Anki will replace notes with matching identifiers. Defaults to a hash of the field values.
In mkanki, decks are collections of notes (not cards, as in Anki proper).
Create a new deck.
id
string - a stable, unique identifier for this deck. Generate this once with+new Date
and then hard-code it into your code. Keeping this stable means that if the package is updated and re-imported into Anki, the app will be able to tell which cards are new and which cards should be merged into already-existing cards, preserving study history.name
string - the name of the deck. When importing, Anki will create new decks with the specified names for each deck in the package.
Add a note to this deck. Technically, it is possible for a single note in Anki to generate cards belonging to multiple decks, but mkanki does not support that.
note
Note - create notes usingmodel.note()
.
A package collects together decks, notes, and any media objects (images, audio,
video, etc.) to be exported into a .apkg
file.
Create a new empty package.
Add a deck to this package.
deck
Deck - the deck to add.
Add a media file to this package.
data
string | Buffer - the contents of the media file.name
string - the name of the file in the package.
Add a media file from the filesystem to this package.
filename
string - path to the file.name
string (optional) - the name of the file in the package. Defaults tofilename
.
Serializes the package to a file.
filename
string - path to the exported package. Conventionally ends in".apkg"
.
mkanki is licensed to everyone under the terms of the GNU Affero General Public License v3. If you'd like to use mkanki under different terms, I'm happy to accommodate you—just email me!