Jonathan Wrede

Anki-KaTeX-Markdown: Markdown and KaTeX in Anki cards

An Anki add-on I wrote in 2021 that creates a Basic and a Cloze note type which render Markdown and KaTeX: how the cards render, what users report in the issues, and what changed over the releases.

What it is

I wrote Anki-KaTeX-Markdown in February 2021. It is an Anki add-on that creates two note types whose cards render Markdown and math: $...$ for inline formulas and $$...$$ for display formulas, rendered with KaTeX. The README gives two reasons: KaTeX is considered faster than MathJax, and Markdown is one syntax for all formatting on a card. Anki's own MathJax syntax with \(...\) and \[...\] keeps working. The add-on is published on AnkiWeb, and the repository has 86 stars, 12 forks and 20 open issues.

What the add-on does

When a profile loads, the add-on checks for the note types "KaTeX and Markdown Basic" (fields Front and Back) and "KaTeX and Markdown Cloze" (fields Text and Back Extra) and creates them if they are missing. It then copies the libraries into the collection's media folder: KaTeX with its fonts and the mhchem extension for chemistry, markdown-it with the markdown-it-mark plugin for ==highlighted== text, and highlight.js for code blocks. It does not overwrite the templates of note types that already exist. A comment in the code says why: users may have changed them.

In the editor, the add-on adds a preview area below the fields that renders the first two fields on every key press.

How a card renders

Each field sits in a hidden element, for example <div id="front"><pre>{{Front}}</pre></div>. A script in the card template loads every library from the media folder. If a file cannot be loaded there, it loads the same library from a CDN. In a 2021 issue I noted that the phone apps do not find the local files, so they use the CDN. The README says that the cards work on any device with an internet connection.

Rendering then runs in two steps. The script turns the HTML that Anki's editor stores (<br>, <div>, <span>, &nbsp;) back into plain text and runs KaTeX's auto-render with these delimiters:

delimiters: [
  {left: "$$", right: "$$", display: true},
  {left: "$", right: "$", display: false}
],
throwOnError: false

With throwOnError disabled, a formula with a syntax error is shown in place and the rest of the card still renders. Afterwards markdown-it renders the result, with HTML allowed and highlight.js for fenced code blocks that name a language. Only then is the element made visible, so the unrendered source does not flash on screen.

Because math is rendered before Markdown, a $ inside a code block is also read as a math delimiter. That is the subject of several issues.

What users ask for

The issues fall into a few groups:

  • Dollar signs in code: ${variable} in a JavaScript block triggers KaTeX (#24), and #48 shows raw KaTeX HTML after a $. Both are open.
  • Mobile apps: the issue with the most comments (25) is #3, a failed load of katex.min.js on Android in March 2021. iOS has its own open report (#21).
  • Night mode: code blocks kept a light background and became unreadable (#29, #45).
  • The editor preview: it was requested in #8 and added four days later. #35 (macOS, 4 reactions) and #38 (Windows) report that the preview does not appear. Both are open.
  • Own note types: users want more fields, a reverse card or a cloze type that reveals one deletion at a time. A user wrote a tutorial for copying the scripts into custom note types (#31, 21 comments, 5 reactions).

What changed over the releases

Most of the work happened between February and August 2021: local copies of the libraries with the CDN as fallback in March, a short fade-in after a report of flickering (#5), removed again in April, highlight.js in June, the editor preview, mhchem and stylable clozes in July, and markdown-it-mark in August. In July I reverted too many changes by accident, which broke chemistry support until mid-August.

In September 2022 I added a GitHub Actions workflow that packs the add-on folder into MDKaTeX.ankiaddon and publishes it as a release on every push. The version number is the workflow's run number, so the list has gaps: V.16 and V.17 date from September 2022, V.18 to V.21 from May 2023, when I adapted the preview to the editor of a newer Anki version. In March 2022 I had written in #31 that I had mostly abandoned the project for lack of time.

In 2023 a contributor sent a pull request with colored cloze cards, better code blocks, escaped dollar signs and night mode support (#44). I decided not to merge it, because replacing the note types could destroy the changes users had made to their local copies, and suggested pointing users to the contributor's version instead. The contributor published it as a separate AnkiWeb add-on that creates new note types. None of the six pull requests in the repository was merged.

V.24 on 2026-10-18 fixes the night mode code blocks. _highlight.css now has dark colours under .nightMode and .night_mode, with a lowest token contrast of 5.4:1. The add-on copies a file into the media folder only if it is not there yet, so an updated stylesheet never reached existing collections. Since V.24 it replaces _highlight.css on startup. This closed #29 and #45.

The code and the releases are at github.com/Jwrede/Anki-KaTeX-Markdown.