189 lines
11 KiB
Org Mode
189 lines
11 KiB
Org Mode
* anki-editor
|
|
|
|
anki-editor is an [[https://www.gnu.org/software/emacs/emacs.html][Emacs]] minor for making [[https://apps.ankiweb.net][Anki]] cards with [[https://orgmode.org][Org]].
|
|
|
|
This repository contains a fork of [[https://github.com/louietan/anki-editor][louietan/anki-editor]]. So far the main difference is that the changes in the develop branch of the original have been merged into the master branch. See the unreleased section of [[https://github.com/orgtre/anki-editor/blob/master/Changelog.org][Changelog.org]] for a list of the new features that come with this. Additionally, a more flexible note structure, outlined [[https://github.com/eyeinsky/org-anki/issues/48#issuecomment-1216625730][here]], has been introduced. See the [[https://github.com/louietan/anki-editor/compare/master...orgtre:anki-editor:master][commit log]] for a full list of differences.
|
|
|
|
|
|
** Installation
|
|
|
|
*** External dependencies
|
|
|
|
Other than Emacs you need [[https://apps.ankiweb.net][Anki]], its [[https://github.com/FooSoft/anki-connect][AnkiConnect]] add-on, and [[https://curl.se][curl]] to use anki-editor.
|
|
|
|
*** Using package.el
|
|
|
|
If you're using the built-in =package.el= package manager, first manually download this repository and then type the following in Emacs:
|
|
|
|
: M-x package-install-file [RET] "path/to/anki-editor.el" [RET]
|
|
|
|
You can also first visit =anki-editor.el= in an Emacs buffer and then type =M-x package-install-from-buffer [RET]=. Both will install the anki-editor package, including uninstalled Elisp dependencies, into =package-user-dir= (=~/.emacs.d/elpa= by default), generate autoloads, and set up =load-path=.
|
|
|
|
*** Using straight.el
|
|
|
|
If you're using [[https://github.com/radian-software/straight.el][straight.el]] as package manager, install by adding this to your =init.el=:
|
|
#+begin_src elisp
|
|
(use-package anki-editor
|
|
:straight (:host github :repo "orgtre/anki-editor")
|
|
:commands anki-editor-mode)
|
|
#+end_src
|
|
|
|
** 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][examples.org]] for more examples.
|
|
|
|
#+BEGIN_SRC org
|
|
,* 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
|
|
#+END_SRC
|
|
|
|
- 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 [fn:1], 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.
|
|
|
|
[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.
|
|
|
|
*** 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. When note heading is not provided or is blank, it's used as the first field. |
|
|
| 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-api-check | Check if correct version of AnkiConnect is running. |
|
|
| 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-api-host | "127.0.0.1" | The network address AnkiConnect is listening. |
|
|
| anki-editor-api-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-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-latex-style | builtin | The style of latex to translate into. |
|
|
| anki-editor-include-default-style | t | Wheter or not to include `org-html-style-default' when using `anki-editor-copy-styles'. |
|
|
| anki-editor-html-head | nil | Additional html tags to append to card stylings when using `anki-editor-copy-styles'. |
|
|
| anki-editor-note-match | nil | Additional matching string for mapping through anki note headings. |
|
|
|
|
*** Functions and Macros
|
|
|
|
**** anki-editor-map-note-entries
|
|
|
|
Simple wrapper that calls ~org-map-entries~ with
|
|
~&ANKI_NOTE_TYPE<>\"\"~ appended to MATCH.
|
|
|
|
**** anki-editor-api-call
|
|
|
|
Invoke AnkiConnect with ACTION and PARAMS.
|
|
|
|
**** anki-editor-api-call-result
|
|
|
|
Calls above, returns result field or raise an error.
|
|
|
|
**** anki-editor-api-with-multi
|
|
|
|
Used in combination with ~anki-editor-api-enqueue~ to queue
|
|
multiple api calls and combine them into one 'multi' call at the
|
|
end, return the results of these calls in the same order.
|
|
|
|
Usage:
|
|
#+begin_src elisp
|
|
(cl-destructuring-bind (decks models tags notes)
|
|
(anki-editor-api-with-multi
|
|
;; The following api calls will be combined into one 'multi' call.
|
|
(anki-editor-api-enqueue 'deckNames)
|
|
(anki-editor-api-enqueue 'modelNames)
|
|
(anki-editor-api-enqueue 'getTags)
|
|
(anki-editor-api-enqueue 'findNotes :query "deck:Default"))
|
|
(message (concat "decks: %S\n"
|
|
"models: %S\n"
|
|
"tags: %S\n"
|
|
"notes: %S")
|
|
decks models tags notes))
|
|
#+end_src
|
|
|
|
**** anki-editor-api-enqueue
|
|
|
|
Like ~anki-editor-api-call~, but is only used in combination with
|
|
~anki-editor-api-with-multi~. Instead of sending the request
|
|
directly, it simply queues the request.
|
|
|
|
**** anki-editor-note-at-point
|
|
|
|
Make a note struct from current entry.
|
|
|
|
**** anki-editor-find-notes
|
|
|
|
Find notes with QUERY.
|
|
|
|
**** anki-editor-copy-styles
|
|
|
|
Copy `org-html-style-default' and `anki-editor-html-head' to Anki card stylings.
|
|
|
|
**** anki-editor-remove-styles
|
|
|
|
Remove from card stylings html tags generated by this mode.
|
|
|
|
** 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~).
|
|
|
|
** Demo
|
|
|
|
[[./demo.gif]]
|
|
|
|
** Donation
|
|
|
|
The original author [[https://github.com/louietan][louietan]] developed almost all of this package in his free time! If you find it useful, consider thanking him by donating to his [[https://paypal.me/louietanlei][PayPal]] (you can verify the link and read more at the original repository [[https://github.com/louietan/anki-editor#donation][here]]).
|