A simple way to write Anki decks in Markdown.
Anki is awesome, in many ways. However, its card editor is... a little bit uncomfortable. I really wanted to write Anki cards in Markdown. So I made a tool to convert Markdown (+ standard MathJAX math notation) into Anki decks that can be easily imported. This way, it's possible to use any fancy markdown (and MathJAX) tools to build your decks.
NOTE This program requires Python 3, along with the packages in requirements.txt
Ankdown can be installed by doing pip3 install --user ankdown.
Cards are written in the following format:
Expected Value of \(f(x)\)
%
\[\mathbb{E}[f(x)] = \sum_x p(x)f(x)\]
%
math, probability
---
Variance of \(f(x)\)
%
\[\text{Var}(f(x)) = \mathbb{E}[(f(x) - \mathbb{E}[f(x)])^2]\]
Each of the solitary % signs is a field separator: the first
field is the front of the card, the second field is
the back of the card, and subsequent fields can contain whatever
you want them to (all fields after the second are optional).
--- markers represent a card boundary.
The tool needs these separators to be alone on their own lines, and most markdown editors will work better if you separate them from other text with empty lines, so that they're treated as their own paragraphs by the editor.
To compile your cards, put them in markdown files with .md extensions,
inside of a directory that has the name of the deck you'd like to put
the cards into. Then, run ankdown -r [directory] -p [package filename].
The package filename should end in .apkg.
You can then import the package using the Anki import tool. To do this,
go to File > Import, and then in the drop-down menu select "Packaged
Anki Deck/Collection (*.apkg)".
Once you've installed ankdown, it can be a hassle to run it on all
of your decks over and over again. There is an ankdown
Anki add-on that you
can use to make this process simpler: If you put all of your decks
in one megadirectory (mine is in ~/Flashcards), you can re-import
your decks in one swell foop by going to Tools > Reload Markdown Decks (or using the operating-system-dependent keybinding).
Ankdown has an unusually large number of known issues; my preferred method of discussing them is via github ticket.
Ankdown uses Genanki as a backend, which doesn't (as of this writing) handle multiple decks in a single package very well. If you point ankdown at a directory with multiple decks in subdirectories, it will do its best, and your cards will all be added to the package, but they won't be assigned to the correct decks. The ankdown plugin solves this problem by running the executable on each deck individually, and then importing all the resulting packages.
There used to be other ways to run ankdown, but they were slowly making the code worse and worse as I tried to keep them all operational. If there's a particular method of operating ankdown that you used and miss, let me know in a github issue.
Unfortunately, $ and $$ as math separators were not chosen by the anki
developers for the desktop client's MathJax display, and so in order for math
to work in both web and desktop, it became much simpler to use \(\) and
\[\]. These separators should be configurable in most markdown editors
(e.g. I use the VSCode Markdown+Math plugin). Older decks that were built
for ankdown need to be modified to use the new separators.
Ankdown should work with media references that result in src="" appearing
somewhere in the generated html (mainly images). If you need it to work with
other media types (like sounds), let me know in a github issue and I may make
time to fix this.
When you want to modify a card, just run your deck through the above process after changing the markdown file. Anki should notice, and update the card. This is done by giving the cards in your deck unique IDs based on their filename and index in the file.
This is the most robust solution I could come up with, but it has some downsides:
- It's not possible to automatically remove cards from your anki decks, since the anki package importer never deletes cards.
- If you delete a card from a markdown file, ankdown will give all of its successors off-by-one ID numbers, and so if they were different in important ways (like how much you needed to study them), anki will get confused. The best way to deal with this is to give each card its own markdown file.
Lastly, the catch-all disclaimer: this is, as they say, alpha-quality software. I wrote this program (and the add-on) to work for me; it's pretty likely that you'll hit bugs in proportion to how different your desires are from mine. That said, I want it to be useful for other people as well; please submit github tickets if you do run into problems!