anki_deck_from_text

Purpose

The purpose of this tool is to generate an Anki deck from annotations on a text file. This was specially developed for those who use Anki to learn language vocabulary.

Input structure

1. The input must be some sort of non-compressed text file (.txt, .md, etc.)
2. Every line to be converted to an Anki card must start with a marker, such as -. Use the marker option to set a custom marker. Every other line will be ignored.
3. The front and back of the cards are separated by a separator, such as =. Use the separator option to set a custom separator.

Example:

- die Katze = the cat
- das Haus = the house

Outside of these rules, you are free to populate your text file with other annotations which will be ignored when creating the deck.

Current card types

Currently, the output deck will be populated with cards from one type at a time. The currently implemented types are:

• basic: The Basic card type in Anki. Each line's text is split between front and back of one card by the separator
• sound: Similar to the Basic (type in the answer) card type, but with an added empty field on the back of the card that can be filled up afterwards with (for example) sound files by using an add-on such as HyperTTS. Note that this card type can also be used without filling up the sound field, thereby behaving as a Basic (type in the answer) card type.

Installation

Make sure you have python installed (version >= 3.12) and then run in the terminal/command-line:

pip install anki_deck_from_text

How to run

Open a terminal/command-line instance and follow the general structure:

anki_deck_from_text file_name.md output_name amazing_deck_name

For all options run:

anki_deck_from_text --help

You will get the following documentation:

Usage: anki_deck_from_text [OPTIONS] INPUT OUTPUT DECK_NAME

  Generate an Anki deck from annotations on a text file.

  INPUT is the text file. OUTPUT is the desired name for the .apkg file with
  the deck. DECK_NAME is the deck name that will be displayed in Anki.

Options:
  --version                   Show the version and exit.
  --separator TEXT            Character(s) that separate the text to be
                              written to the front and back of the cards
                              [default: =]
  --marker TEXT               Character(s) marking this line to be included in
                              the deck  [default: -]
  --card_model [basic|sound]  Anki card model to build the deck with
                              [default: basic]
  --reverse                   Swap front and back of each card
  --dry-run, --preview        Preview cards that would be generated without
                              writing a file
  --tags TEXT                 Comma-separated tags to add to all cards
  -i, --extra-input PATH      Additional input files to merge into the deck
                              (repeatable)
  -h, --help                  Show this message and exit.

Further development

Contributing

To contribute to this project:

1. Fork this project
2. Install Poetry
3. Install Nox (optional but recommended for automated tests and code formatting)
4. Change to the project directory and run $ poetry install

This should get your system setup to:

• Test that your changes didn't break the tool with $ nox or $ poetry run pytest
• Build with $ poetry build (optional)
• Test run with $ poetry run anki_deck_from_text [OPTIONS] INPUT OUTPUT DECK_NAME

Once you're happy with your changes and tests:

5. Create a pull request to be reviewed

Extending the tool

Add card types

To add extra card types follow the instructions in the models.py file docstring and then update the current available card types both in the docstring of generate_deck.py and in the relevant section of this README.

Refer to the Anki docs for how to design Anki card type structures.

Documentation

Full documentation is available at andremacedo88.github.io/anki_deck_from_text.