Jonathan Wrede

Anki-KaTeX-Markdown: Markdown und KaTeX in Anki-Karten

Ein Anki-Add-on, das ich 2021 geschrieben habe und das einen Basic- und einen Cloze-Notiztyp mit Markdown und KaTeX anlegt: wie die Karten rendern, was Nutzer in den Issues melden und was sich über die Releases geändert hat.

Worum es geht

Anki-KaTeX-Markdown habe ich im Februar 2021 geschrieben. Es ist ein Add-on für Anki, das zwei Notiztypen anlegt, deren Karten Markdown und Mathematik darstellen: $...$ für Formeln im Text und $$...$$ für abgesetzte Formeln, gerendert mit KaTeX. Das README nennt zwei Gründe: KaTeX gilt als schneller als MathJax, und Markdown ist eine einzige Syntax für die gesamte Formatierung einer Karte. Ankis eigene MathJax-Syntax mit \(...\) und \[...\] funktioniert weiterhin. Das Add-on ist auf AnkiWeb veröffentlicht, das Repository hat 86 Sterne, 12 Forks und 20 offene Issues.

Was das Add-on tut

Beim Laden eines Profils prüft das Add-on, ob die Notiztypen "KaTeX and Markdown Basic" (Felder Front und Back) und "KaTeX and Markdown Cloze" (Felder Text und Back Extra) vorhanden sind, und legt sie an, falls sie fehlen. Danach kopiert es die Bibliotheken in den Medienordner der Sammlung: KaTeX mit seinen Schriften und der mhchem-Erweiterung für Chemie, markdown-it mit dem Plugin markdown-it-mark für ==markierten== Text und highlight.js für Codeblöcke. Die Vorlagen bereits vorhandener Notiztypen überschreibt es nicht. Ein Kommentar im Code nennt den Grund: Nutzer haben sie möglicherweise angepasst.

Im Editor fügt das Add-on unter den Feldern eine Vorschau ein, die bei jedem Tastendruck die ersten beiden Felder rendert.

Wie eine Karte gerendert wird

Jedes Feld steht in einem versteckten Element, zum Beispiel <div id="front"><pre>{{Front}}</pre></div>. Ein Skript in der Kartenvorlage lädt jede Bibliothek aus dem Medienordner. Lässt sich eine Datei dort nicht laden, holt es dieselbe Bibliothek von einem CDN. In einem Issue von 2021 habe ich festgehalten, dass die Apps auf dem Handy die lokalen Dateien nicht finden und deshalb das CDN nutzen. Das README sagt, dass die Karten auf jedem Gerät mit Internetverbindung funktionieren.

Das Rendern läuft dann in zwei Schritten. Das Skript wandelt das HTML, das Ankis Editor speichert (<br>, <div>, <span>, &nbsp;), zurück in reinen Text und startet das Auto-Render von KaTeX mit diesen Begrenzern:

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

Da throwOnError abgeschaltet ist, erscheint eine Formel mit Syntaxfehler an ihrer Stelle, und der Rest der Karte wird trotzdem gerendert. Anschließend rendert markdown-it das Ergebnis, mit erlaubtem HTML und highlight.js für Codeblöcke, die eine Sprache angeben. Erst danach wird das Element sichtbar, damit der ungerenderte Quelltext nicht kurz aufblitzt.

Weil die Mathematik vor dem Markdown gerendert wird, gilt auch ein $ in einem Codeblock als Formelbegrenzer. Darum geht es in mehreren Issues.

Was Nutzer sich wünschen

Die Issues lassen sich in einige Gruppen einteilen:

  • Dollarzeichen in Code: ${variable} in einem JavaScript-Block löst KaTeX aus (#24), und #48 zeigt nach einem $ rohes KaTeX-HTML. Beide sind offen.
  • Mobile Apps: Das Issue mit den meisten Kommentaren (25) ist #3, ein fehlgeschlagenes Laden von katex.min.js unter Android im März 2021. Für iOS gibt es eine eigene offene Meldung (#21).
  • Nachtmodus: Codeblöcke behielten einen hellen Hintergrund und waren nicht mehr lesbar (#29, #45).
  • Die Vorschau im Editor: Sie wurde in #8 gewünscht und vier Tage später ergänzt. #35 (macOS, 4 Reaktionen) und #38 (Windows) melden, dass die Vorschau nicht erscheint. Beide sind offen.
  • Eigene Notiztypen: Nutzer wünschen sich mehr Felder, eine umgekehrte Karte oder einen Cloze-Typ, der die Lücken einzeln aufdeckt. Ein Nutzer hat eine Anleitung geschrieben, wie man die Skripte in eigene Notiztypen übernimmt (#31, 21 Kommentare, 5 Reaktionen).

Was sich über die Releases geändert hat

Der größte Teil der Arbeit fiel zwischen Februar und August 2021 an: lokale Kopien der Bibliotheken mit dem CDN als Rückfallebene im März, ein kurzes Einblenden nach einer Meldung über Flackern (#5), das im April wieder entfiel, highlight.js im Juni, die Editor-Vorschau, mhchem und gestaltbare Lücken im Juli und markdown-it-mark im August. Im Juli habe ich versehentlich zu viele Änderungen zurückgenommen, wodurch die Chemie-Unterstützung bis Mitte August nicht funktionierte.

Im September 2022 habe ich einen GitHub-Actions-Workflow ergänzt, der den Add-on-Ordner zu MDKaTeX.ankiaddon packt und bei jedem Push als Release veröffentlicht. Die Versionsnummer ist die Laufnummer des Workflows, deshalb hat die Liste Lücken: V.16 und V.17 stammen aus dem September 2022, V.18 bis V.21 aus dem Mai 2023, als ich die Vorschau an den Editor einer neueren Anki-Version angepasst habe. Im März 2022 hatte ich in #31 geschrieben, dass ich das Projekt aus Zeitmangel mehr oder weniger aufgegeben hatte.

2023 schickte ein Mitwirkender einen Pull Request mit farbigen Cloze-Karten, besseren Codeblöcken, maskierten Dollarzeichen und Unterstützung für den Nachtmodus (#44). Ich habe mich gegen das Mergen entschieden, weil das Ersetzen der Notiztypen die Anpassungen zerstören könnte, die Nutzer an ihren lokalen Kopien gemacht hatten, und vorgeschlagen, stattdessen auf seine Version zu verweisen. Er hat sie als eigenes AnkiWeb-Add-on veröffentlicht, das neue Notiztypen anlegt. Keiner der sechs Pull Requests im Repository wurde gemergt.

V.24 vom 18.10.2026 behebt die Codeblöcke im Nachtmodus. _highlight.css hat jetzt dunkle Farben unter .nightMode und .night_mode, mit einem niedrigsten Token-Kontrast von 5,4:1. Das Add-on kopiert eine Datei nur dann in den Medienordner, wenn sie dort noch nicht liegt. Ein aktualisiertes Stylesheet erreichte bestehende Sammlungen deshalb nie. Seit V.24 ersetzt es _highlight.css beim Start. Damit wurden #29 und #45 geschlossen.

Code und Releases liegen unter github.com/Jwrede/Anki-KaTeX-Markdown.