LaTeX Note Importer for Anki
Table of ContentsClose
LaTeX Note Importer is an add-on for Anki, an open-source flash-card program developed and maintained by Damien Elmes. As the name says, the add-on provides functionality for importing notes from LaTeX files. This allows you to create Anki notes in your favourite editor or IDE. Of course, this is mainly useful for notes that contain a lot of LaTeX to begin with, for example mathematical notes.
1 Installation
You will need the following prerequisites:
- LaTeX: you need a local (La)TeX installation.
- Anki: you need a local installation of Anki, and it needs to be set up to interact with your local TeX installation.
Assuming you have these, installing LaTeX Note Importer is easy.
In Anki’s main window, choose Tools
>
Add-ons
>
Browse & Install...
, enter
1199027445
and click [OK]
. Then restart Anki.
2 Examples
2.1 Minimal example
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.
2.2 Compilable example
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.
2.3 More examples
The following files are provided mainly for inspiration.
2.3.1 A basic example
You can import demo.tex
into Anki as it is. Note however that in order for the notes to compile in Anki, you still need to manually copy the LaTeX preamble into Anki.
2.3.2 An example in which the pdf-output can be cut into paper cards
Again, you can import TopoCards.tex
into Anki as it is, but you will need to import the preamble manually. Alternatively, you can first import the example deck (*.apkg) into Anki: this will in particular create a note type compatible with the LaTeX file, i.e. with the correct number of fields, and with the correct LaTeX preamble.
3 Syntax
3.1 Fields
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.
3.2 Tags
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}
3.3 Comments
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.
4 Porting
4.1 Import
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".
4.1.1 Preamble
The preamble of the LaTeX file is not imported. You can configure the LaTeX preamble used by Anki by selecting (Tools
>
Manage Note Types...
) in the main menu, choosing the relevant note type and clicking on the [Options]
button.
4.1.2 Tags
In the current version of LaTeX Note Importer, tags are only imported correctly if the (maximum) number of fields per note in the LaTeX file matches the number of fields of the note type selected in the import dialog.
For example, suppose our note type has just the two fields Front
and Back
, and accordingly each note in our LaTeX file also has two fields. If any of these notes has a tag, then the import dialog will show up with three fields. It will look something like this:
Field 1 of file is: mapped to
Front
Field 2 of file is: mapped toBack
Field 3 of file is: mapped toTags
This is what we want! The mysterious Field 3
contains the tags that we specified with the \tags
-command in our LaTeX file, and if we do not change the default association of Field 3
with Tags
, then these tags will be imported correctly.
I won't attempt to defend the shortcomings of this user interface, but I'll include the following ascii art purely for its aesthetic value:
+------------+ +--------+ LaTeX --+ LaTeX Note +---> list of ---+ IMPORT +--> Anki file --+ Importer +---> field values ---+ DIALOG +--> database +------------+ +--------+
Back to our example. What happens if our note type has more fields than occur in the notes in our LaTeX file? Suppose, for instance, that our note type has a third field Hints
, but we are using the same LaTeX file as before. Then the import dialog will instead display as:
Field 1 of file is: mapped to
Front
Field 2 of file is: mapped toBack
Field 3 of file is: mapped toHints
The tags we specified in the LaTeX file are again displayed as a mysterious Field 3
, but now they will be imported as Hints
instead of tags! We can easily correct this insane default behaviour, however, by clicking on the Change
button next to Hints
in the dialog and selecting Tags
instead.
Finally, if at least one of the notes in our LaTeX file does contain a third field, everything is automatically fine again. The dialog comes up with an additional Field 4
, and this field is correctly mapped to Tags
:
Field 1 of file is: mapped to
Front
Field 2 of file is: mapped toBack
Field 3 of file is: mapped toHints
Field 4 of file is: mapped toTags
4.1.3 Updating notes
Suppose you have imported some notes and started learning with them. Suppose that, after a while, you notice some mistakes or inconsistencies that you would like to correct. Is it possible to make these corrections in your original LaTeX file and reimport it without losing all of Anki’s scheduling information for this deck?
The answer is YES, you can. As long as you don’t edit the first field of each note, you can update them in Anki by editing them in your LaTeX file and choosing the option
Update existing notes when first field matches
when you import.
So, what if you also want to edit the first field? The trick is to plan ahead and reserve the first field of each note for a unique ID that will never change. The \xplain-fields
are provided with exactly this purpose in mind. For more details, see the step-by-step guide on how to maintain a deck for a lecture course.
5 Maintaining a deck for a lecture course
The following is a step-by-step guide explaining how to create and maintain an Anki deck for a maths lecture course as you go along. The idea is to create and import cards each week as the course progresses, but in such a way that you can still go back and make changes later on.
5.1 Preparations
- If you haven’t already done so, follow the installation instructions above.
- Download the example file TopoCards.tex. You will create and maintain all notes in this single file.
- 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.
- Download the example deck TopoCards.apkg and import it into Anki (
File
>
Import...
). This will create a deck calledMaths::TopoCards
and a note type calledTopoNote
. You can rename and edit the note type underTools
>
Manage Note Types…
. Be sure to keep the first field for the ID. 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 ofTopoNote
. This is becauseTopoCards.tex
uses some raw tex commands to produce its pdf output, and these commands throw errors in Anki.)
5.2 Weekly workflow
For the general syntax to use in the LaTeX file, see above. Here, we just explain the weekly workflow.
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 betweenLecture
andN
, as this will create two separate tags! (Using tags for sorting cards into lectures is better than using (sub)decks.)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.Import the LaTeX file into Anki (
File
>
Import…
). In the import dialog, chooseUpdate 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
.
5.3 Sharing/publishing
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.
6 FAQ
You can contact me using any of the means listed on my homepage. Here, I just answer some of the most likely questions.
6.1 Why not keep the [latex]-commands in a card template?
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.
6.2 Why has the mechanism for importing tags changed?
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.
6.3 Where can I find the code?
The code is available on GitHub.
Once the add-on is installed, you can find the code in the folder …/Anki/addons/latexbiport
.