mnmd-anki-sync 0.1.2

Sync mnemonic markdown files to Anki with rich cloze deletion syntax

MNMD Anki Sync

Sync mnemonic markdown files to Anki with rich cloze deletion syntax.

Features

• Rich cloze syntax: Basic, grouped, and sequence clozes
• Hints and extras: Add hints ({{answer|hint}}) and extra info ({{answer<extra}})
• Math support: LaTeX equations ($inline$ and $$block$$) automatically converted to Anki format
• Markdown rendering: Bold, italic, lists, images, code blocks, line breaks
• Scope control: Specify paragraph context for each cloze with [-before,after]
• Smart updates: Automatically tracks Anki IDs to prevent duplicates
• Editor links: Open source files from Anki in VS Code, VSCodium, Neovim, or Obsidian
• Dry-run mode: Preview changes before syncing with --dry-run
• Type-safe: Built with Pydantic for robust data validation
• Well-tested: 282 unit tests with 94% code coverage

Installation

For Users

Recommended: Install with pipx (installs in isolated environment)

pipx install mnmd-anki-sync

Alternative: Install with pip

pip install mnmd-anki-sync

Or install with uv

uv pip install mnmd-anki-sync

Install from GitHub (latest development version)

pip install git+https://github.com/am-campbell/mnmd-anki-sync.git

For Developers

Clone the repository and install with uv:

git clone https://github.com/am-campbell/mnmd-anki-sync.git
cd mnmd-anki-sync
uv sync --extra dev

Quick Start

1. Make sure Anki is running with AnkiConnect installed

2. View the syntax guide:

mnmd syntax

3. Create a markdown file with cloze deletions:

The capital of France is {{Paris}}.

My favorite languages are {{1>Python}} and {{1>Rust}}.

Any paragraph containing {{...}} becomes a flashcard automatically.

4. Sync to Anki:

mnmd sync myfile.md --deck "My Deck"

Syntax Guide

Run mnmd syntax to view the complete syntax documentation, or see below for quick examples.

Basic Cloze

The capital of France is {{Paris}}.

Creates one card with "The capital of France is [...]"

Grouped Cloze

My favorite languages are {{1>Python}} and {{1>Rust}}.

Both items are hidden together on the same card: "My favorite languages are [...] and [...]"

Sequence Cloze

Steps to make coffee:
{{1.1>Grind beans}}
{{1.2>Add hot water}}
{{1.3>Wait and enjoy}}

Creates progressive reveal: first step hidden, then second, then third

Hints and Extras

Python is a {{dynamically typed|type checking happens at runtime}} language.
The package manager is {{pip<PyPI hosts over 400,000 packages}}.

• |hint adds hint text shown on card front
• <extra adds extra information shown on card back
• Combine: {{answer|hint<extra}}

Math Support

Einstein's equation: {{$E = mc^2$}}

LaTeX math ($inline$ and $$block$$) is automatically converted to Anki's format

Scope Modifiers

Context paragraph with background info.

The answer is {{here}}[-1].

The [-1] includes the previous paragraph in the card context.

• [-1] = include 1 paragraph before
• [1] = include 1 paragraph after
• [-1,1] = include 1 before and 1 after

Explicit Context Blocks (Optional)

> ?
> Use block quotes starting with "> ?" when you want
> full control over multi-paragraph card content.
> The cloze is {{here}}.

This is optional - paragraphs with clozes work automatically.

CLI Commands

# Sync files
mnmd sync file.md --deck "Biology" --tags "chapter1"

# Sync with specific editor
mnmd sync file.md --editor nvim
mnmd sync file.md --editor vscode

# Validate syntax
mnmd validate file.md

# Show syntax guide (opens in pager)
mnmd syntax

# Show syntax guide without pager (direct output)
mnmd syntax --no-pager

# Show version
mnmd version

Editor Configuration

Set your preferred editor for source links in Anki cards. Choose from:

• vscode - Visual Studio Code (default, works out of box)
• vscodium - VSCodium (works out of box)
• obsidian - Obsidian (works out of box)
• file - System default handler (works out of box)
• nvim - Neovim (requires setup, see EDITOR_SETUP.md)

Config file (~/.mnmdrc):

editor_protocol: vscode  # or nvim, vscodium, obsidian, file
default_deck: My Deck
default_tags:
  - mnmd

Command line:

mnmd sync file.md --editor nvim

For Neovim users: The nvim:// protocol requires custom setup. Either:

1. Use file protocol (easiest): editor_protocol: file
2. Register nvim:// handler (see EDITOR_SETUP.md)

The file protocol opens files with your system's default markdown editor.

Development

# Run tests
uv run pytest

# Type check
uv run mypy src

For AI Agents & LLM Integration

If you're building tools that generate mnemonic markdown or integrating LLMs to create flashcards, see agents-syntax.md for:

• Precise syntax specification optimized for LLM parsing
• Complete pattern reference with regex-like precision
• Common pitfalls and error prevention
• Validation checklist
• Quick reference table

This file provides unambiguous rules for programmatic generation of valid MNMD syntax.

Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Add tests for new features
4. Ensure all tests pass: uv run pytest
5. Submit a pull request

Publishing & Distribution

See DISTRIBUTION.md for instructions on publishing releases to PyPI and GitHub.

License

Apache 2.0 - See LICENSE file for details