Markdown to Anki

[!CAUTION] This software is provided "as is", without warranty of any kind. The author is not responsible for any consequences of its use, including but not limited to data loss, corrupted Anki collections, or unintended modifications to your notes. Back up your Anki collection before syncing. Use at your own risk.

markdown-to-anki is a lightweight Python CLI that automatically converts raw Markdown files into Anki cards using AnkiConnect. It's designed for learners and note-takers who prefer writing in Markdown and want to seamlessly sync their content into Anki.

Installation

pip install markdown-to-anki

Requires Python 3.10+ and AnkiConnect running in your Anki app.

Getting Started

Open Anki, then register note models once:

m2a --folder ~/notes/anki init

Then sync your notes anytime:

m2a --folder ~/notes/anki sync

Commands

Only files modified within the last TIME_RANGE seconds (default 2 hours) are processed.

Force a full sync — to re-sync all notes regardless of modification time, touch every Markdown file first:

find ~/notes/anki -name "*.md" -exec touch {} +
m2a --folder ~/notes/anki sync

Configuration

Settings are resolved in this order — highest priority wins:

CLI flag  >  environment variable / .env  >  config file  >  default

CLI flags

m2a --folder ~/notes/anki --url http://localhost:8765 sync
m2a --resources ~/my-templates init

Config file

Create ~/.config/markdown-to-anki/config.yaml (respects $XDG_CONFIG_HOME):

md_folder: ~/notes/anki
time_range: 7200
anki_url: http://localhost:8765
resources_dir: ~/notes/anki-templates

Environment variables / .env

Place a .env file in the directory where you run m2a, or set the variables in your shell:

MD_FOLDER=~/notes/anki
TIME_RANGE=7200
ANKI_URL=http://localhost:8765
M2A_RESOURCES_DIR=~/notes/anki-templates

Markdown Style

Each Markdown file may contain one or more cards. Use YAML frontmatter for per-file metadata and the comment separators below to split cards and fields:

---
deck: M2A::Example::Math
tags: math, theorem
model: m2a-basic
# skip: 1   # uncomment to skip this file
---

<!--CARD-->

### Front of card 1

<!--FIELD-->

Back of card 1

<!--CARD-->
<!--TAGS: hard, exam-->

### Front of card 2

<!--FIELD-->

Back of card 2

Supported metadata keys: deck, tags, model, skip.

Per-card tags via <!--TAGS: a, b--> (anywhere inside a card section) are merged with the file-level tags from frontmatter.

Built-in note types

Cloze cards

Use Anki's native {{c1::...}} syntax in the Text field. Multiple deletions (c1, c2, …) are supported in a single card.

---
deck: M2A::Example::Cloze
model: m2a-cloze
---

<!--CARD-->

The capital of {{c1::France}} is {{c2::Paris}}.

<!--FIELD-->

European geography.

<!--CARD-->

{{c1::Water}} boils at {{c2::100}}°C at standard pressure.

<!--FIELD-->

Basic chemistry fact.

The Text field holds the cloze content; Extra is shown on the back and can hold supplementary notes.

Custom Resources

Point --resources (or resources_dir / M2A_RESOURCES_DIR) at your own directory to override built-in templates/styles and define new note types. Only the files you provide are overridden — everything else falls back to the built-in defaults.

Override built-in templates or styles

Mirror the built-in layout under your resources directory:

my-resources/
└── anki/
    ├── styles/
    │   └── basic.css          # overrides the built-in basic.css
    └── templates/
        └── basic/
            └── front.html     # overrides the built-in front template

Define custom note types

Place a YAML file per model inside a models/ subdirectory:

my-resources/
├── models/
│   └── my-vocab.yaml
├── styles/
│   └── my-vocab.css
└── templates/
    └── my-vocab/
        ├── front.html
        └── back.html

models/my-vocab.yaml:

name: my-vocab
fields:
  - Word
  - Definition
  - Example
is_cloze: false
css_file: styles/my-vocab.css # relative to my-resources/
templates:
  - name: word-to-definition
    front_file: templates/my-vocab/front.html
    back_file: templates/my-vocab/back.html

Inline CSS and HTML are also supported instead of file references:

name: my-simple
fields:
  - Question
  - Hint
  - Answer
css: ".card { font-family: sans-serif; }"
templates:
  - name: card
    front: "<div>{{Question}}</div><div class='hint'>{{Hint}}</div>"
    back: "<div>{{Answer}}</div>"

Fields map to <!--FIELD--> sections in order. A card with three fields uses two separators:

---
model: my-vocab
deck: Languages::English
---

<!--CARD-->

hello

<!--FIELD-->

A common English greeting.

<!--FIELD-->

"Hello, how are you?" — used when meeting someone.

Run m2a --resources my-resources/ init once to register your custom models in Anki, then use m2a --resources my-resources/ sync as usual.

Cronjob

Automatically sync your notes to AnkiWeb hourly:

crontab -e

# sync hourly (replace /usr/local/bin/m2a with the output of: which m2a)
5 * * * *  /usr/local/bin/m2a --folder ~/notes/anki sync_web &>/dev/null

Examples

See the example notes for working Markdown files covering basic cards, cloze deletions, math, code, and audio.

License

This project is open-sourced and licensed under the MIT license.