#+TITLE: ankifier

#+PROPERTY: LOGGING nil

# Note: This readme works with the org-make-toc <https://github.com/alphapapa/org-make-toc> package, which automatically updates the table of contents.

Efficiently create Anki flashcards from your notes.

I created this package to facilitate faster creation of Anki cards while I study
utilizing the fantastic text editing of Emacs.

* Screencast

[[screencasts/ankifier-basic.gif]]

* Contents                                                         :noexport:
:PROPERTIES:
:TOC:      :include siblings
:END:
:CONTENTS:
- [[#installation][Installation]]
- [[#usage][Usage]]
- [[#development][Development]]
  - [[#changelog][Changelog]]
  - [[#whats-next][What's Next?]]
- [[#acknowledgments][Acknowledgments]]
- [[#development][Development]]
:END:

* Installation
:PROPERTIES:
:TOC:      :depth 0
:END:
Requires Emacs 27.2+.

Dependencies:
+ ~expand-region.el~ ([[https://github.com/magnars/expand-region.el][link]]).

Recommended package:
+ ~anki-editor~
  While not /required/, this is the ~anki-editor~ package that allows the output of my package
  to be sent to Anki (utilizing the [[https://ankiweb.net/shared/info/2055492159][AnkiConnect]] addon).

Then put this file in your load-path, and put this in your init file:

Clone the repository.
#+begin_src shell
git clone https://www.github.com/adham-omran/ankifier
#+end_src

Load the package.
#+begin_src elisp
(load! "/path/to/ankifier/ankifier.el")
(require 'ankifier)
#+end_src

* Usage
:PROPERTIES:
:TOC:      :depth 0
:END:

Run one of these commands on an active region:

+ =ankifier-create-basic-from-region=: Create Basic question(s) from active
  region.
+ =ankifier-create-cloze-from-region=: Create Cloze question(s) from active
  region.
+ =ankifier-create-from-region=: Parse basic and cloze questions in the active
  region.
+ =ankifier-find-to-be-ankified=: Interactively search the buffer for
  un-ankified questions and prompt to ankify them.

Variables

+ Set =ankifier-insert-elsewhere= to =t= if you want the questions to be created
  under a =* Cards= org heading (This is what I mostly do).

  The name of the heading can be modified through =ankifier-cards-heading=.

+ Set =ankifier-context-question= to =t= if you want to use contextual questions,
  see examples for uses.

+ Set =ankifier-feedback= to =t= if you notes you ankify to have ANKIFIED at the
  start of the text to indicate that this has been ankified. Useful when you
  return to your notes after a while and wonder if you Ankified something or
  not.

+ =ankifier-anki-cloze-note-type= sets the card type for cloze cards.

+ =ankifier-anki-basic-note-type= sets the card type for basic cards.

+ =ankifier-anki-deck= sets the Anki deck to push cards to (default: "All").

+ =ankifier-anki-tags= sets the tags to apply to created cards (default: "").

+ Set =ankifier-arabic= to =t= to use Arabic question marks (؟) instead of
  Latin (?).

For a *basic* question, the questions must be separated by two newlines
and have a single question mark to indicate the /Question/ part and the /Answer/
part.


For a *cloze* question, the sentences must be separated by two new lines.

** Examples
*** Normal Format
#+begin_src org
What is Emacs?
An extensible, customizable, free/libre text editor — and more.

When was Emacs 27.2 released?
Mar 25, 2021.

Emacs is an {{c1::extensible}}, {{c2::customizable}}, free/libre {{c2::text
editor::application type}} — and more.
#+end_src
*** Contextual Question Format
#+begin_src org
Context: Question?
Context: Cloze.

Geography: What's the capital of France?
Paris.

Geography: {{c1::Paris}} is the capital of France.
#+end_src
This results in the ":" being replaced with two newline characters.
** Example Config
This is the config I'm using at the moment.
#+begin_src emacs-lisp
(setq ankifier-insert-elsewhere t
      ankifier-anki-basic-note-type "E-Basic"
      ankifier-anki-cloze-note-type "E-Cloze"
      ankifier-anki-deck "My Deck"
      ankifier-anki-tags "study"
      ankifier-arabic nil
      ankifier-feedback t
      ankifier-context-question t)
#+end_src
** Tips
+ You can customize settings in the =ankifier= group.
+ Check out [[https://yiufung.net/post/anki-org/][Power up Anki with Emacs, Org mode, anki-editor and more]] for ideas
  about general anki-editor use and how to get code highlighting working
  properly.
** Custom Fields

Extra fields can be added to generated cards via the =ankifier--extra-fields=
variable. It holds a list of plists, each with three keys:

- =field-name= — The name of the field in your Anki note template (e.g. "Source").
- =source-name= — The keyword or property name to read the value from.
- =source-type= — How to retrieve the value:
  - =file= — reads from an org file keyword (e.g. =#+SOURCE_NAME: value=). All
    cards in the file get the same value.
  - =property= — reads from an org property drawer (e.g. =:SOURCE_NAME: value=).
    Supports inheritance, so different headings can have different values.

*** Example: File-level keyword

Given this in your org file:
#+begin_src org
#+SOURCE_NAME: Introduction to Algorithms
#+end_src

And this configuration:
#+begin_src emacs-lisp
(setq ankifier--extra-fields
      '(( field-name "Source" source-name "SOURCE_NAME" source-type file )))
#+end_src

Each generated card will include a "Source" field with the value "Introduction to Algorithms".

*** Example: Per-heading property

Given this in your org file:
#+begin_src org
* Chapter 1
:PROPERTIES:
:SOURCE_NAME: Introduction to Algorithms, Ch. 1
:END:

What is an algorithm?
A well-defined computational procedure.

* Chapter 2
:PROPERTIES:
:SOURCE_NAME: Introduction to Algorithms, Ch. 2
:END:

What is insertion sort?
A sorting algorithm that builds the sorted array one item at a time.
#+end_src

And this configuration:
#+begin_src emacs-lisp
(setq ankifier--extra-fields
      '(( field-name "Source" source-name "SOURCE_NAME" source-type property )))
#+end_src

Cards created under "Chapter 1" will have =Source: Introduction to Algorithms, Ch. 1=,
while cards under "Chapter 2" will have =Source: Introduction to Algorithms, Ch. 2=.

* Development
** Changelog
:PROPERTIES:
:TOC:      :depth 0
:END:
- 1.4.2: Fix a bug where a space after ~::~ broke cloze deletion cards.
- 1.4.1: Fix bug with multiple ':' in a question for the basic card type.
- 1.4.0: Add the function ~ankifier-find-to-be-ankified~. Remove dependency on ~cl-lib~.
- 1.3.0: Add the function ~ankifier-create-from-region~.
- 1.2.0: Add the ability to include feedback for ankified notes.
- 1.1.0: Add the ability to format contextual questions.
- 1.0.0: Initial release.
* Acknowledgments
:PROPERTIES:
:TOC:      :depth 0
:END:
This package would not have been possible without [[https://github.com/louietan/anki-editor][anki-editor]], which allows the
flash cards to be sent to Anki in the first place.
* Development
:PROPERTIES:
:TOC:      :depth 0
:END:
Bug reports, feature requests, suggestions are all welcome, keep in mind this is
my first Emacs package!


# Local Variables:
# eval: (require 'org-make-toc)
# before-save-hook: org-make-toc
# org-export-with-properties: ()
# org-export-with-title: t
# End:
* Tasks
- [ ] Fix author on old commits