anki-editor/README.org at master

Allow specifying field values from org-mode properties (#22 )

* Allow specifying field values from org-mode properties

* Update documentation and fine-tune the diff

* Refactor, fix indentation, and other minor fixes

Renamed all-fields to named-fields since the heading and content
before first subheading can also be a field.

---------

Co-authored-by: Renat Galimov <renat@Renats-MacBook-Pro.local>
Co-authored-by: orgtre <orgtre@posteo.net>

2023-04-13 14:02:42 +02:00

14 KiB

Raw Permalink Blame History

anki-editor

anki-editor

anki-editor is an Emacs minor mode for making Anki cards with Org Mode.

This repository is a fork of louietan/anki-editor. By now there are quite a few differences and extensions compared to the original:

The develop branch of the original has been merged into the master branch; see the unreleased section of Changelog.org for a list of the new features that come with this.
Almost all outstanding pull requests to the original have been integrated; this issue tracks the two exceptions.
A more flexible note structure, outlined here, has been introduced.
The commands to push notes, delete notes, and insert notes have been improved.
A transient interface to all commands has been created.

See the commit log for a full list of differences. Note that this README does not reflect all the changes and additions yet.

Installation

External dependencies

Other than Emacs you need Anki, its AnkiConnect add-on, and curl to use anki-editor. Because of AnkiConnect, anki-editor-mode needs Anki to be running (see issue for explanation).

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 straight.el as package manager, install by adding this to your init.el:

(use-package anki-editor
  :defer t
  :straight (:fork "orgtre"))

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
  * Is there a shorter way to write notes?
     :PROPERTIES:
     :ANKI_NOTE_TYPE: Basic
     :END:

  ** Back

     Yes, like this one, Front is missing, ~anki-editor~ will use note
     heading as Front.  This is neat as sometimes it's verbose to repeat
     the same content in note heading and first field.

     This works for all note types, just make one field absent and
     ~anki-editor~ will use note heading as that missing field.

  * Is there a an even shorter way to write notes?
     :PROPERTIES:
     :ANKI_NOTE_TYPE: Basic
     :END:

     Yes, like this one, Front and Back is missing, ~anki-editor~ will use note
     heading as Front and the text after as Back.  This is neat as sometimes it's verbose to repeat
     the same content in note heading and first field.

     This works for all note types, just make the first 2 fields absent and
     ~anki-editor~ will use note heading as first field and the text below the heading as second field.

  * You can extract a field value from an org-property
     :PROPERTIES:
     :ANKI_NOTE_TYPE: Basic
     :ANKI_FIELD_FRONT: Can one define an anki-field inside an org-mode property?
     :ANKI_PREPEND_HEADING: nil
     :END:

     Yes. In this example, =anki-editor=  will use the =ANKI_FIELD_FRONT= property value as
     a front side of the Anki card and the body of the card as its back.

  ** Front
     Notice that property fields will override subheading fields.
     This block will be skipped

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

To see the docs for the most recent commands use M-x describe-function (for more info see Emacs Manual - Help 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

To see the docs for the most recent commands use M-x describe-variable (for more info see Emacs Manual - Help Commands)

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:

  (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))

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

One Way Sync with Anki

To sync anki notes and decks to org see (orgtre/ankiorg).

The following items are not synchronized to org:

Deletion of Notes
Deck Changes

Demo

/elisp/anki-editor/media/branch/master/demo.gif

Donation

The original author louietan developed almost all of this package in his free time! If you find it useful, consider thanking him by donating to his PayPal (you can verify the link and read more at the original repository here).

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.

14 KiB Raw Permalink Blame History