anki-editor/README.org

190 lines
11 KiB
Org Mode
Raw Normal View History

* anki-editor
2018-02-04 07:43:11 +01:00
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]].
2017-12-27 17:20:01 +01:00
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.
2018-07-06 15:10:03 +02:00
2018-01-15 15:11:02 +01:00
** Installation
2017-12-27 17:20:01 +01:00
*** External dependencies
2018-01-15 15:11:02 +01:00
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.
2018-01-15 15:11:02 +01:00
*** 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
2018-01-15 15:11:02 +01:00
2019-09-23 11:13:10 +02:00
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.
2018-06-10 15:13:00 +02:00
2019-09-23 11:13:10 +02:00
The structure of a note is as follows, which is inspired by
~org-drill~. Check out [[./examples.org][examples.org]] for more examples.
2018-06-10 15:13:00 +02:00
#+BEGIN_SRC org
2019-09-23 11:13:10 +02:00
,* Raining :vocab:idioms:
2018-01-15 15:11:02 +01:00
:PROPERTIES:
2018-06-10 15:13:00 +02:00
:ANKI_DECK: English
2018-01-15 15:11:02 +01:00
:ANKI_NOTE_TYPE: Basic (and reversed card)
2019-09-23 11:13:10 +02:00
:ANKI_TAGS: vocab idioms
2018-01-15 15:11:02 +01:00
:END:
2018-06-10 15:13:00 +02:00
,** Front
2018-01-15 15:11:02 +01:00
(it's) raining cats and dogs
2018-06-10 15:13:00 +02:00
,** Back
2018-01-15 15:11:02 +01:00
it's raining very hard
2018-06-10 15:13:00 +02:00
#+END_SRC
2019-09-23 11:13:10 +02:00
- 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.
2018-06-10 15:13:00 +02:00
[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
2018-06-10 15:13:00 +02:00
2020-02-24 06:39:31 +01:00
| 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. |
2018-07-06 15:10:03 +02:00
*** Variables
2018-07-29 11:43:56 +02:00
| Name | Default Value | Description |
|-----------------------------------------------+------------------------+----------------------------------------------------------------------------------------------------------|
2019-11-03 14:41:56 +01:00
| 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. |
2020-03-01 17:10:53 +01:00
| anki-editor-break-consecutive-braces-in-latex | nil | If non-nil, consecutive "}" will be automatically separated by spaces to prevent early-closing of cloze. |
2018-07-29 11:43:56 +02:00
| 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. |
2019-11-11 16:03:55 +01:00
| anki-editor-latex-style | builtin | The style of latex to translate into. |
2020-03-01 17:10:53 +01:00
| 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'. |
2020-03-09 14:36:27 +01:00
| anki-editor-note-match | nil | Additional matching string for mapping through anki note headings. |
2018-07-29 11:43:56 +02:00
*** Functions and Macros
2019-11-03 14:41:56 +01:00
**** anki-editor-map-note-entries
2019-11-03 14:41:56 +01:00
Simple wrapper that calls ~org-map-entries~ with
~&ANKI_NOTE_TYPE<>\"\"~ appended to MATCH.
**** anki-editor-api-call
2019-11-03 14:41:56 +01:00
Invoke AnkiConnect with ACTION and PARAMS.
**** anki-editor-api-call-result
2019-11-03 14:41:56 +01:00
Calls above, returns result field or raise an error.
**** anki-editor-api-with-multi
2019-11-03 14:41:56 +01:00
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
2019-11-03 14:41:56 +01:00
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
2019-11-03 14:41:56 +01:00
Make a note struct from current entry.
**** anki-editor-find-notes
2019-11-03 14:41:56 +01:00
Find notes with QUERY.
**** anki-editor-copy-styles
2020-03-01 17:10:53 +01:00
Copy `org-html-style-default' and `anki-editor-html-head' to Anki card stylings.
**** anki-editor-remove-styles
2020-03-01 17:10:53 +01:00
Remove from card stylings html tags generated by this mode.
2018-07-29 11:43:56 +02:00
** 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
2019-09-23 11:13:10 +02:00
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~).
2018-01-15 15:11:02 +01:00
** Demo
2018-01-15 15:11:02 +01:00
[[./demo.gif]]
** Donation
2020-03-09 16:08:19 +01:00
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]]).