anki-editor/README.org

• Installation
• Usage
  • The Layout of Notes
  • Commands
  • Variables
• Limitations
  • Tags between Anki and Org
  • Working with Anki add-ons
• Troubleshooting
• Demo

anki-editor – An Emacs minor mode for making Anki cards with Org

Since I'm not a native English speaker, feel free to correct me if there are any ambiguity or grammatical mistakes ;-)

Installation

Requirements

• AnkiConnect, an Anki add-on required by this package to interact with Anki
• curl

If you have MELPA in your package-archives, just M-x package-install RET anki-editor RET, or install it manually by downloading and visiting anki-editor.el in your emacs buffer, and M-x package-install-from-buffer RET.

Usage

The Layout of Notes

The power of this mode comes from the builtin HTML export backend provided by Org, which enables you to use almost all the Org constructs for writing Anki notes: lists, code blocks, tables, latex and so on.

The structure of a note is as follows, which is inspired by org-drill. Check out examples.org for more examples.

  * Raining                                                      :vocab:idioms:
    :PROPERTIES:
    :ANKI_DECK: English
    :ANKI_NOTE_TYPE: Basic (and reversed card)
    :ANKI_TAGS: vocab idioms
    :END:
  ** Front
     (it's) raining cats and dogs
  ** Back
     it's raining very hard

• Anki deck is provided by ANKI_DECK property. This property is retrieved with inheritance, that is to say, it can be put in any ancestor entries or at top of the file by #+PROPERTY: ANKI_DECK DeckName.
• ANKI_NOTE_TYPE property is to specify the Anki note type of a note and is also required for identifying an Anki note entry.

• Anki tags can be provided in two ways:

  1. With a ANKI_TAGS property, multiple tags are separated by spaces
  2. With Org tags ¹, this could be turned off if you would like to keep Org tags separated from Anki tags
• Child entries of a note entry are fields.

Typing all these information by hand could be inefficient and prone to errors, so this package provides an interactive command anki-editor-insert-note to help with this and hooks up auto-completions for decks, note types and tags etc.

Commands

Command	Description
anki-editor-mode	Toggle this minor mode.
anki-editor-push-notes	Push notes to Anki. Additional arguments can be used to restrict the range of notes.
anki-editor-push-new-notes	Similar to anki-editor-push-notes, but push those that are without ANKI_NOTE_ID.
anki-editor-retry-failed-notes	Similar to anki-editor-push-notes, except that it only pushes notes with ANKI_FAILURE_REASON.
anki-editor-insert-note	Insert a note entry like M-RET, interactively.
anki-editor-delete-notes	Delete notes or the note at point.
anki-editor-cloze-dwim	Cloze current active region or a word the under the cursor.
anki-editor-export-subtree-to-html	Export the subtree at point to HTML.
anki-editor-convert-region-to-html	Convert and replace region to HTML.
anki-editor-anki-connect-check	Check if correct version of AnkiConnect is running.
anki-editor-anki-connect-upgrade	Upgrade AnkiConnect.
anki-editor-sync-collections	Synchronize your local anki collection.
anki-editor-gui-browse	Open Anki Browser with a query for current note or deck.
anki-editor-gui-add-cards	Open Anki Add Cards dialog with presets from current note entry.

Variables

Name	Default Value	Description
anki-editor-anki-connect-listening-address	"127.0.0.1"	The network address AnkiConnect is listening.
anki-editor-anki-connect-listening-port	"8765"	The port number AnkiConnect is listening.
anki-editor-break-consecutive-braces-in-latex	nil	If non-nil, consecutive `}' will be automatically separated by spaces to prevent early-closing of cloze.
anki-editor-create-decks	nil	If non-nil, creates deck before creating a note.
anki-editor-ignored-org-tags	'("export" "noexport")	A list of Org tags that are ignored when constructing notes form entries.
anki-editor-org-tags-as-anki-tags	t	If nil, tags of entries wont't be counted as Anki tags.
anki-editor-protected-tags	'("marked" "leech")	A list of tags that won't be deleted from Anki even though they're absent in Org entries.
anki-editor-use-math-jax	nil	Use Anki's built in MathJax support instead of LaTeX.

Limitations

Tags between Anki and Org

Because the set of characters allowed in tags is different between Anki and Org, you have to make sure that tags from Anki are compatible with Org and tags in Org could be recognized by Anki.

Working with Anki add-ons

This package might not work well with certain Anki add-ons especially those who extend the builtin Anki note editor to automatically fill note field content (e.g. Add note id).

Troubleshooting

In case of a failed operation and this package doesn't provide much useful information, don't be frustrated, see below for some hints.

1. Decks don't exist in Anki. This package by default doesn't create decks for you, when trying out this package with examples.org, you might find that every single note creation fails, simply because they're fake decks that might not be in your Anki collection. If you'd like it to automatically create missing decks, set anki-editor-create-decks to t.

2. Note is counted as a duplicate. From Anki docs

   Anki checks the first field for uniqueness, so it will warn you if you enter two cards with a Front field of “apple” (for example). The uniqueness check is limited to the current note type, so if you’re studying multiple languages, two cards with the same Front would not be listed as duplicates as long as you had a different note type for each language.

If all the above don't help, then we have to go deeper to find out what goes wrong. Here are some methods:

• Turn on logging in request.el. Customize request-log-level to debug, retry failed actions and switch to buffer ~ *request-log*~ (there's a leading space, see invisible buffer) to get logs from request.el. This way we can't inspect the request payload, since it's dumped into a temp file that's deleted when request finishes.
• Use a traffic sniffer to inspect communications between Emacs and Anki.

Demo

---

¹

It should be noted that Org only allows letters, numbers, _ and @ in a tag but Anki allows more, so you may have to edit you Anki tags before they can be used in Org without any surprise.