Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/louietan/anki-editor

Emacs minor mode for making Anki cards with Org
https://github.com/louietan/anki-editor

anki emacs flashcards org-mode

Last synced: 22 days ago
JSON representation

Emacs minor mode for making Anki cards with Org

Awesome Lists containing this project

README 

        
[[http://melpa.org/#/anki-editor][file:http://melpa.org/packages/anki-editor-badge.svg]]



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



/Since I'm not a native English speaker, feel free to correct me if

there were any ambiguity or grammatical mistakes ;-)/



* Installation



  *Requirements*

  - [[https://github.com/FooSoft/anki-connect#installation][anki-connect]],

    an Anki add-on required by this package to interact with Anki.

  - curl



  If you have [[http://melpa.org/][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][anki-editor.el]] in your

  emacs buffer, and =M-x package-install-from-buffer RET=.



* Usage



** The Layout of Notes



   Now you can compose Anki notes in Org syntax, e.g. lists, code

   examples, tables, embedded latex, when being submitted to Anki,

   they will be converted to HTML by Org-mode's HTML backend with

   specific markers (e.g. latex) translated to Anki style.



   The structure of a note is as follow, which is inspired by

   =org-drill=. More examples can be found in [[./examples.org][examples.org]].



   #+BEGIN_SRC org

     ,* Idiom                                                        :vocab:idioms:

       :PROPERTIES:

       :ANKI_DECK: English

       :ANKI_NOTE_TYPE: Basic (and reversed card)

       :ANKI_TAGS: languages european_languages

       :END:

     ,** Front

        (it's) raining cats and dogs

     ,** Back

        it's raining very hard

   #+END_SRC



   - An Anki note is an Org entry with =ANKI_NOTE_TYPE= property

   - Anki tags can be set in two ways

     1. With "ANKI_TAGS" property, multiple tags are separated with space

     2. With Org tags [fn:1], this could be turned off if you would like to keep Org tags separated from Anki tags

   - Other necessary information (e.g. deck, note type) of a note is

     put in the property drawer of the entry

     - As the value of =ANKI_DECK= is retrieved with inheritance, you

       don't have to set it per note, instead, you could create a deck

       entry with this property set and put note entries under it, or

       set it per file by ~#+PROPERTY: ANKI_DECK YourDeck~

   - Child entries of a note entry are fields



** Commands



   | Command                            | Brief Description                                                                    |

   |------------------------------------+--------------------------------------------------------------------------------------|

   | anki-editor-push-notes             | Push notes to Anki. Additional arguments can be used to restrict the range of notes. |

   | anki-editor-retry-failure-notes    | Same as above, except that it only pushes notes that have =ANKI_FAILURE_REASON=.     |

   | anki-editor-insert-note            | Insert a note entry like =M-RET=, interactively.                                     |

   | anki-editor-cloze-region           | Create a cloze deletion from region.                                                 |

   | 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.                                                  |



** Functions



   | Name                         | Description                                                |

   |------------------------------+------------------------------------------------------------|

   | anki-editor-map-note-entries | Simple wrapper that calls =org-map-entries=.               |

   | anki-editor-note-at-point    | Construct an alist representing a note from current 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.                |



* 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 may not work well when you are using 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, especially for note creation, 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 [[https://apps.ankiweb.net/docs/manual.html#adding-cards-and-notes][Anki docs]]

     #+BEGIN_QUOTE

     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.

     #+END_QUOTE



  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 [[https://www.emacswiki.org/emacs/InvisibleBuffers][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



  [[./demo.gif]]



* Donation



  This package was a set of utilities in my personal =.emacs=, then I

  thought it might be helpful to others, so I decided to make it a

  package and share with you guys.  Since then I have been devoting

  part of my free time to the maintenance of this package.



  Donation is not required, but if you like my work and want to show

  your appreciation you can donate via

  [[https://paypal.me/louietanlei][PayPal]], every cent is

  appreciated, thanks for your support :)



[fn:1] 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.