npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

mkanki

v1.1.0

Published

Generate Anki decks. Supports cloze deletion and media.

Downloads

17

Readme

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!