Html2anki

CLI tool written with Python that helps you create a single HTML document containing multiple Anki flashcards, and generates a TSV file for easy import into Anki, allowing you to work with your preferred text editor.

Motivation

When I create new flashcards for Anki using the tools it provides, I would rather write html directly instead of using the “word processor” interface it offers. Although this built-in html editor works well, it doesn’t have useful features such as code suggestion, code completion or autoformatting (features that any text-editor out there offers). In addition, if I want to create several flashcards for the same topic (let’s say I’m studying mathematics, and I want to create flashcards about dividing polynomials using the remainder and factor theorems), I would like to be able to quickly access the previous flashcards so I can copy some math formulas that I will reuse, or to copy a previous flashcard’s structure, which is easier if all of them are in the very same file that I am editing at the moment (instead of going to the Anki’s browser to find them).

That is why I decided to write a Python CLI tool that allows me to easily write all my flashcards about a topic on a single html document using my text-editor of choice. It works by extracting any flashcard inside the file, and then exports them as a tsv file that can be easily imported into Anki.

Dependencies

The project uses the following external libraries:

• BeautifulSoup4 for parsing HTML documents.
• Pyinstaller for packaging the application.

Quick Start

Linux

First, ensure that Python installed on your system. After that, clone the repository, navigate to the project's root directory and create a python virtual environment using:

python3 -m venv .venv

Activate the virtual enviroment and install the project's dependencies using:

source .venv/bin/activate
pip install -r requirements.txt

Make the build.sh script executable by setting its permissions using:

chmod +x build.sh

Then, compile the program into an executable file using:

./build.sh

Finally, copy the executable into a directory that is in your system's path. A good location is ~/bin, but you can manually add another directory to the path if needed and copy the executable there. To copy the executable to ~/bin, use:

cp dist/html2anki ~/bin/

If all is working as expected, running the following command should return the help message of the program:

html2anki --help

Usage

The flashcards that the program extracts must be have the following HTML structure:

Basic:

  <div class="flashcard">
    <!-- front's content here -->
   <hr class="frontback"/>
    <!-- reverse's content here -->
  </div>

Cloze:

  <div class="flashcardcloze">
    <!-- content here -->
  </div>

The previously mentioned div elements must be part of a proper HTML structure (they must be child elements of the body of the HTML document).

The program's interface offers three commands: convert, template, and add. You can access the help of any of them using:

html2anki <command_name> --help

convert

usage: html2anki convert -i input_file [-op output_files_prefix] [-t tag]

Extracts all div element with specified classes 'flashcard' or 'flashcardcloze' and generates TSV files containing the extracted content. The resulting TSV files are ready to be imported into Anki.

Options:

• -i, --input-file: REQUIRED. Name of the html file that contains Anki flashcards.
• -op, --output-files-prefix: The prefix name for the TSV files to be generated by the program. If the document contains flashcards of both cloze and basic type, it generates two TSV files, one per flashcard type (<prefix>_cloze.tsv and <prefix>_basic.tsv respectively). By default, the value of the prefix is the name of the input file without file extension.
• -t, --tag: Tag of the flashcards (third column of the TSV file). The default value is the name of the input file without file extension.

template

Creates an HTML document containing CSS styling that makes it easier to distinguish the flashcards when rendering the HTML document on a web browser.

Options:

• -o, --output: Name of the file to be created. Default value: html2anki_template.html.

add

usage: html2anki add [Exactly one of : -c, -b] input

Appends an empty div element with the specified class as the last child element of the body of the HTML document contained by the input file.

Positional Arguments:

• input: file containing an html document.

Options:

• -c, --cloze: Add a div element representing a cloze flashcard.
• -b, --basic: Add a div element representing a basic flashcard.

This command was created with the idea of automating the creation of the div elements that the program identifies as Anki flashcards. Instead of using it directly from the command line, I recommend making your text editor execute the command on the file that you are editing. As an example, I've added the following code into my Neovim's init.lua file (its main configuration file):

-- HTML2ANKI
-- basic
local function addBasicFlashcard()
    local fileName = vim.api.nvim_buf_get_name(0)
    vim.cmd("! html2anki add -b " .. fileName)
    vim.cmd("! prettier -w " .. fileName)
end

vim.api.nvim_create_user_command("H2aBasic", function()
    addBasicFlashcard()
    vim.cmd(":edit")
    local line_count = vim.api.nvim_buf_line_count(0)
    local line = line_count - 5
    vim.api.nvim_win_set_cursor(0, {line, 27})
end, {})

-- cloze
local function addClozeFlashcard()
    local fileName = vim.api.nvim_buf_get_name(0)
    vim.cmd("! html2anki add -c " .. fileName)
    vim.cmd("! prettier -w " .. fileName)
end

vim.api.nvim_create_user_command("H2aCloze", function()
    addClozeFlashcard()
    vim.cmd(":edit")
    local line_count = vim.api.nvim_buf_line_count(0)
    local line = line_count - 3
    print("line_count", line_count)
    vim.api.nvim_win_set_cursor(0, {line, 32})
end, {})

This code provides two commands to be used inside of Neovim: H2aBasic and H2aCloze. They append basic and cloze flashcards at the end of the HTML's body element.

Note: I have Prettier installed on my system. I use it to keep the html document's format consistent. This is because Html2anki modifies it using the formatting functionality that Beautiful Soup provides.