LaTeX Note Importer for Anki

Let's have a look at a fairly minimal example file that LaTeX Note Importer can deal with:

\begin{document}
\begin{note}
   \begin{field}
       Is it true that \(1 + 1 = 0\)?
   \end{field}
   \begin{field}
       Yes and no. The equation
       \begin{equation*}
            1+1 = 0
       \end{equation*}
       holds only in characteristic two.
   \end{field}
\end{note}
\end{document}

Importing this file into Anki will create a new note with two fields. The contents of each field will be enclosed in Anki's [latex] ...[/latex] commands. (If you do not think this is a good idea, see the FAQ below.) For example, in Anki's built-in editor, the first field of the imported note will be displayed as follows:

[latex]
Is it true that \(1 + 1 = 0\)?
[/latex]

In order for the importer to work correctly, the tex-file needs to be saved in utf-8 encoding. This is the same prerequisite as required by Anki's built-in text importer. If you use emacs for text editing, you can force the file to be saved in utf-8 by adding % -*- coding:utf-8 -*- to the beginning of your file.

Of course, we would also like our LaTeX file to be compilable! We should therefore add a line that informs the LaTeX compiler about the encoding we are using, and we should define the note and field environments. Here's a compilable version of the above example:

% -*- coding:utf-8 -*-
\documentclass[12pt]{article}
\usepackage[utf8]{inputenc}
\newenvironment{note}{\paragraph{NOTE:}}{}
\newenvironment{field}{\paragraph{field:}}{}
\begin{document}
\begin{note}
   \begin{field}
       Is it true that \(1 + 1 = 0\)?
   \end{field}
   \begin{field}
       Yes and no. The equation
       \begin{equation*}
                  1+1 = 0
       \end{equation*}
       holds only in characteristic two.
   \end{field}
\end{note}
\end{document}

There is no restriction on the number of notes you can include in a single LaTeX file, nor on the number of fields you can include in a note. Unlike Anki's built-in text importer, LaTeX Note Importer does not require each note to have the same number of fields. However, you should keep in mind that you will have to specify a single Anki note type when importing the file; notes should not have more fields than this note type provides. And, if you use tags, it’s best to have at least one note in your file that has exactly as many fields as the note type provides: see details on tag import.

On first reading, you’ll probably now want to skip down to the instructions for importing.

The following files are provided mainly for inspiration.

Altogether, LaTeX Note Importer supports four different field types:

• LaTeX fields: \begin{field} …some LaTeX… \end{field}
  The contents of these fields are surrounded by [latex]…[/latex] when imported. Moreover, the following special characters are replaced by their html-equivalents: <, >, &. (This is necessary. Anki will translate them back when sending them to the LaTeX compiler.)
• Short LaTeX fields: \xfield{ …some LaTeX… }
  These fields work like the previous ones, except that no additional line breaks are inserted after [latex] and before [/latex]. The idea is to use this field type primarily for short, single-line LaTeX code, which will then remain single-line upon importing. For example, you could use this type of field for prompts/questions, and the usual field environment for answers.
• Plain text fields: \begin{plain} …some text… \end{plain}
  As the name indicates, these fields can be used to import plain text – the text will not be included in [latex]…[/latex], nor will any other operations be performed on it.
• Short plain text fields: \xplain{ …some text… }
  Like the previous one. For example, this field can be used for note IDs (see the section on updating notes).

Of course, you will need to define each field type that you use in the preamble of your file in order for the file to be compilable.

You can add tags to the notes in your LaTeX file using the command:

\tags{ tag1 tag2 … }

Again, you will also need to add some definition of this command to the preamble in order for the file to be compilable, for example:

\newcommand*{\tags}[1]{\paragraph{tags: }#1}

The scope of the tags tag1, tag2 … depends on the relative position of the \tags-command:

• global tags: If the command is placed in between notes, the tags tag1, tag2, … will be applied to all the following notes, until another \tags-command in between notes is encountered. These tags do not accumulate, i.e. a global tag command always overwrites all preceding global tag commands.
• local tags: If the command is placed inside a note (but not inside a field), tag1, tag2, … will be applied to the current note only. These tags are applied in addition to the global tags, and they accumulate within a note.

The behaviour is best illustrated with an example:

\tags{g1 g2}
\begin{note}
   \tags{l1}
   \begin{field}
       Is it true that \(1 + 1 = 0\)?
   \end{field}
   % This note has tags g1, g2, l1.
\end{note}

\begin{note}
   \begin{field}
       Is it true that \(1 + 1 = 1\)?
   \end{field}
   % This note has tags g1, g2.
\end{note}

\tags{g3}
\begin{note}
   \tags{l2}
   \begin{field}
       Is it true that \(1 + 1 = 2\)?
   \end{field}
   \tags{l3}
   % This note has tags g3, l2, l3.
\end{note}

All text in between notes or in between fields is ignored by the importer. In particular, you can use this space for adding comments in your file. LaTeX comments within fields are also handled correctly as long as they are used within sane limits. Fragments of the form

\begin% some comment
{field}

will definitely confuse the importer, even though they do not seem to confuse LaTeX compilers.

You can import your LaTeX file using either the menu (File > Import...) or the [Import File] button at the bottom of the main Anki window. A dialog window allows you to specify which deck to import the notes to, which note type to base them on, and how to map the imported fields onto the fields of that note type. (By default, the fields are kept in the order in which they appear in the LaTeX file.) Moreover, you can choose between the following three options:

Update existing notes when first field matches
Ignore lines where first field matches existing note
Import even if existing note has same first field

This import dialog is part of core Anki, so the wording is perhaps not perfectly adapted to LaTeX files—read "ignore notes" for "ignore lines".

To export a deck into a tex file, go to File > Export... in the main menu and select [Notes in LaTeX (*.tex)] as export format.

1. If you haven’t already done so, follow the installation instructions above.
2. Download the example file TopoCards.tex. You will create and maintain all notes in this single file.
3. Adapt the LaTeX preamble of the file to your needs. Try as much as possible to include all packages and macros that you will need for this particular course. Every time you change the preamble later, you will also have to repeat Step 5 below.
4. Download the example deck TopoCards.apkg and import it into Anki (File > Import...). This will create a deck called Maths::TopoCards and a note type called TopoNote. You can rename and edit the note type under Tools > Manage Note Types…. Be sure to keep the first field for the ID.

5. If you changed the LaTeX preamble in Step 2, then copy the preamble of your LaTeX file to Anki: Tools > Manage Note Types > [TopoNote] > Options… .

   (In the case of our example file TopoCards.tex, only a part of the preamble is included in the settings of TopoNote. This is because TopoCards.tex uses some raw tex commands to produce its pdf output, and these commands throw errors in Anki.)

For the general syntax to use in the LaTeX file, see above. Here, we just explain the weekly workflow.

1. After the last note in the file, insert

   \tags{LectureN}
   

   or a similar line, where N is the number of the current lecture. This will tag each of the following cards with the tag “LectureN”. Don’t put a whitespace between Lecture and N, as this will create two separate tags! (Using tags for sorting cards into lectures is better than using (sub)decks.)

2. Write the notes for this week/lecture below that line. Each note should begin with a field containing a unique ID. For example, you can just number your notes consecutively as you type them, or use a UUID generator. This will allow notes to be updated on successive imports. The Anki note template provided with the example deck accepts at most 8 further fields (4 prompts and 4 answers). Don’t put more fields into a single note.

   If you haven’t messed up, it should be possible to process the file with pdflatex. So you can check your notes before importing them into Anki.

3. Import the LaTeX file into Anki (File > Import…). In the import dialog, choose

   Update existing notes if first line matches.

   and, if you used tags in the file as recommended, make sure the last field is mapped to Tags.

Export your deck as an *.apgk-file via Gear icon next to deck > Export. In the export dialog, choose the following settings:

Export format: Anki Deck Package
Include scheduling information
Include media

You can share the *.apkg-file file with friends or publish it on the web.

Why does the importer encapsulate all fields with [latex] … [/latex]? Wouldn't it be more sensible to import fields as they are and instead insert the [latex]-commands into our card template?

Although this does work sometimes, the Anki manual explicitly discourages this approach:

Media references to fields are not allowed. They may or may not display during review, and will not work when checking for unused media, importing/exporting, and so on. Examples that won't work:

[…] 

[latex]{{Field 1}}[/latex] 

Instead, you should include the media references in the field.

With previous versions of LaTeX Note Importer, it was impossible to update the tags of existing notes. This is due to a limitation of the core Anki importer: it does not update tags of existing notes unless these tags are imported as an additional field.

The code is available on GitHub. Once the add-on is installed, you can find the code in the folder …/​Anki/​addons/​latexbiport.