ankitextlayer 0.1.2
Bidirectional sync between Anki and Markdown
License: MIT
Requires Python: >=3.10

# AnkiTextLayer (ATL)

Write your decks in Markdown, sync them to Anki for studying, make edits in either place, and sync changes back.

## Why Use This

- **Write in Markdown**: Your cards live in plain text: easy to edit fast, search, refactor, and review in your editor.
- **Keep full overview**: Browse hundreds of cards in one file, search across decks instantly, and reorganize freely.
- **Work with AI**: Markdown is a great interface for AI help (drafting, rephrasing, generating variants) while you stay in control of the final wording.
- **Version control**: Track exactly what changed and when, roll back safely, and collaborate using Git like any other text-based project.

If you already love Anki for studying, ATL just upgrades how you create and maintain your cards.

## How It Works

In a directory of your choice, each Markdown file represents an Anki deck. On first sync, ATL assigns HTML comment IDs to each card for tracking. After that, it knows what's new, changed, moved between decks, or deleted, and will sync accordingly.

Two note types are provided: `LayerQA` and `LayerCloze`. In a markdown file, each field is represented by a line starting with a specific letter and a colon. `Q:` and `A:` start question and answer fields, `T:` starts a text field for clozes, and `E:` and `M:` start optional extra and "more" fields on the back of the card. Cards are separated by a blank line, three dashes, and another blank line.

A fresh markdown deck could look like this:

```markdown
Q: What is the capital of France?
A: Paris.
E: ![alt text](tour_eiffel.png){width=700}

---

T: The capital of Germany is {{c1::Berlin}}.
```

With the first ATL sync to Anki, the deck and each card gets a unique ID in an HTML comment:

```markdown
<!-- deck_id: 1770487991521 -->
<!-- card_id: 1770487991522 -->
Q: What is the capital of France?
A: Paris.
E: ![alt text](tour_eiffel.png){width=700}

---

<!-- note_id: 1770487991521 -->
T: The capital of Germany is {{c1::Berlin}}.
```

ATL only acts on the provided note types, so your existing collection is never affected. You can mix managed and unmanaged cards in the same deck without issues.

Before every ATL sync, it automatically creates a Git commit so you can always roll back if something breaks.

## How to Get Started

Install via [pipx](https://github.com/pypa/pipx):
```bash
pipx install ankitextlayer
```
Make sure Anki is running, with the [AnkiConnect add-on](https://ankiweb.net/shared/info/2055492159) enabled. Then initialize ATL in any directory (not your Anki data folder):

```bash
ankitextlayer init --tutorial
```
The tutorial flag creates a sample markdown deck with further information. We can import it into Anki using:
```bash
ankitextlayer ma
```
Where `ma` is shorthand for `markdown-to-anki`. Conversely, there is `ankitextlayer am` for `anki-to-markdown`. The tutorial deck should provide you with a good starting point to explore the features of ATL.

## Workflow

Start by writing your cards in Markdown. Images can be added by pasting them directly into your markdown file in VS Code as explained in the tutorial. When you ATL sync to Anki, the images are saved in the media collection of Anki (`media/LayerMedia/`) via a symlink set up by ATL.

```markdown
Q: Question text here
A: Answer text here
E: Extra information (optional)
M: Content behind "more" button (optional)

---

T: Text with {{c1::cloze deletions}}.

---

And so on…
```

Push your cards to Anki, study them, make edits in either place, then pull changes back:

```bash
ankitextlayer init   # Use once per directory, to set up
ankitextlayer ma     # Markdown to Anki
# Review and edit in Anki...
ankitextlayer am     # Anki to Markdown
```
And that's it — Your markdown files and Anki decks stay in sync, giving you the best of both worlds.

## Development

Tested and running on macOS. I expect some rough edges in this early version, so any feedback/issue/PR is welcome.

---

## Support This Project

If ATL saves you time or makes your workflow better, consider buying me a coffee! 

[![ko-fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/visserle)

MIT License