Skip to content

Latest commit

 

History

History
208 lines (154 loc) · 7.56 KB

README.md

File metadata and controls

208 lines (154 loc) · 7.56 KB
Raw

mkanki

An API for generating Anki decks.

Anki is a tool for spaced-repetition study.

Example

Here's an example of generating a simple deck with mkanki.

$ npm install --save mkanki
const anki = require('mkanki')
const m = new anki.Model({
  name: "Basic (and reversed card)",
  id: "1542906796044",
  flds: [
    { name: "Front" },
    { name: "Back" }
  ],
  req: [
    [ 0, "all", [ 0 ] ],
    [ 1, "all", [ 1 ] ]
  ],
  tmpls: [
    {
      name: "Card 1",
      qfmt: "{{Front}}",
      afmt: "{{FrontSide}}\n\n<hr id=answer>\n\n{{Back}}",
    },
    {
      name: "Card 2",
      qfmt: "{{Back}}",
      afmt: "{{FrontSide}}\n\n<hr id=answer>\n\n{{Front}}",
    }
  ],
})

const d = new anki.Deck(1542998993960, "hi")

d.addNote(m.note(['this is front', 'this is back']))

const p = new anki.Package()
p.addDeck(d)
p.writeToFile('deck.apkg')

Documentation

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.

Model

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.

new anki.Model(props)

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, and afmt 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.

new anki.ClozeModel(props)

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, and afmt 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.

model.note(fieldValues, [guid])

Create a note using this model.

  • fieldValues Array<string> | {[fieldName: string]: string} - If fieldValues is an array, the order of fields will be matched with the order of the flds in the model. If fieldValues 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.

Deck

In mkanki, decks are collections of notes (not cards, as in Anki proper).

new anki.Deck(id, name)

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.

deck.addNote(note)

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.

Package

A package collects together decks, notes, and any media objects (images, audio, video, etc.) to be exported into a .apkg file.

new anki.Package()

Create a new empty package.

package.addDeck(deck)

Add a deck to this package.

  • deck Deck - the deck to add.

package.addMedia(data, name)

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.

package.addMediaFile(filename, [name])

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 to filename.

package.writeToFile(filename)

Serializes the package to a file.

  • filename string - path to the exported package. Conventionally ends in ".apkg".

License

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!