Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/kitschpatrol/yanki

A CLI tool and TypeScript library for syncing Markdown to Anki flashcards.
https://github.com/kitschpatrol/yanki

anki anki-connect cli flashcards markdown npm-package spaced-repetition sync

Last synced: about 1 month ago
JSON representation

A CLI tool and TypeScript library for syncing Markdown to Anki flashcards.

Host: GitHub
URL: https://github.com/kitschpatrol/yanki
Owner: kitschpatrol
License: mit
Created: 2024-05-30T08:21:58.000Z (6 months ago)
Default Branch: main
Last Pushed: 2024-09-19T15:21:00.000Z (about 2 months ago)
Last Synced: 2024-10-01T09:41:46.851Z (about 2 months ago)
Topics: anki, anki-connect, cli, flashcards, markdown, npm-package, spaced-repetition, sync
Language: TypeScript
Homepage:
Size: 6.2 MB
Stars: 10
Watchers: 2
Forks: 0
Open Issues: 0
Metadata Files:
- Readme: readme.md
- License: license.txt

Awesome Lists containing this project

README

# yanki

[![NPM Package yanki](https://img.shields.io/npm/v/yanki.svg)](https://npmjs.com/package/yanki)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**A CLI tool and TypeScript library for syncing Markdown to Anki flashcards.**

> \[!IMPORTANT]
> Yanki is feature-complete but will remain zero-versioned until it's been thoroughly tested. Please exercise caution and make backups of your Anki notes until the 1.0.0 release.

## Table of contents

- [Overview](#overview)
- [Quick start](#quick-start)
- [Features](#features)
- [Markdown note types](#markdown-note-types)
- [Getting started](#getting-started)
- [Usage](#usage)
- [Advanced features](#advanced-features)
- [Background](#background)
- [Known issues](#known-issues)
- [The future](#the-future)
- [Maintainers](#maintainers)
- [Acknowledgments](#acknowledgments)
- [Contributing](#contributing)
- [License](#license)

## Overview

Yanki simply syncs a folder of Markdown notes to Anki.

The primary novelty of its approach is in how Markdown is translated into Anki notes, and how folders are translated into Anki decks:

- **One** Markdown file maps to **one** Anki note.

- The **structure** of a Markdown note determines the **type** of Anki note it becomes, so no extra syntax or Anki-specific markup is required — just pure Markdown.

- The **parent folder** of your Markdown note determines its **deck name** in Anki, with any intermediate hierarchies created as needed.

This package provides both a stand-alone CLI tool and a TypeScript library for ease of integration in other projects.

The library powers the [`yanki-obsidian`](https://github.com/kitschpatrol/yanki-obsidian) Obsidian plugin. And for lower-level access to Anki, please take a look at the [`yanki-connect`](https://github.com/kitschpatrol/yanki-connect) TypeScript library.

The "Y" prefix in "Yanki" is in the "Yet another" naming tradition; a nod to Anki's robust and occasionally duplicative ecosystem of third-party tools. (Also, appropriately, Yankī are a variety of [truant youth](https://en.wikipedia.org/wiki/Yankee#/media/File:ヤンキー.jpg).)

## Quick start

Install [Node.js](https://nodejs.org) if you haven't already. (Yanki requires Node 18.19.0+, 20.5.0+, or newer.)

Assuming you have a folder of Markdown note files, the [Anki app](https://apps.ankiweb.net) is open and has the the [Anki-Connect](https://foosoft.net/projects/anki-connect/) add-on installed:

```sh
npx yanki ./folder-of-markdown
```

This will turn the folder's Markdown files into Anki notes and send them up to the Anki database.

## Features

### One Markdown file = one Anki note

Avoid the complexity of mixing and matching multi-note and single-note syntaxes. One local Markdown file always yields one Anki note.

### Local folder hierarchy = Anki deck hierarchy

Yanki uses the source Markdown file's parent directory name as the deck name. Complex folder hierarchies are also supported — Anki decks will be created and nested as needed to match the structure of the local file system.

### Embrace of Anki's default note types

More note types, more problems.

Yanki _only_ supports turning Markdown into the _Basic_, _Basic (and reversed card)_, _Basic (type in the answer)_, and _Cloze_ note types that ship as defaults in the Anki App.

### Infer Anki note type from Markdown structure

Since the number of supported note types is small, the type of Anki note to create from a given document can be inferred from a few simple rules about the structure of the Markdown.

For example, a Basic note is any Markdown file with a `---` horizontal rule splitting the front and back of the card:

```md
I'm the front.

---

I'm the back.
```

That's it, no extra metadata or Anki-specific markup is required. You can add whatever additional Markdown syntax you'd like to style the note.

The structural cues for all four supported note types are described [later in this document](#markdown-note-types).

### Tags in frontmatter

Optionally, you can add a `tags` array to your Markdown file's frontmatter and have it automatically synchronized to the Anki database. Frontmatter is also used to store the Anki note's ID after an initial synchronization.

### Intelligent synchronization

Your local Markdown files are the single point of truth for what will and up in Anki, but Yanki knows to leave your other Anki notes alone.

When you edit a local markdown note, Yanki makes every effort to update rather than delete it in the Anki database so that progress is preserved.

But when you do want to delete something, it's as simple as deleting the local Markdown note from the file system and running `yanki sync` to remove it from the Anki database. Protections are in place to prevent deleting Anki notes that weren't initially created by Yanki.

If you use [AnkiWeb](https://ankiweb.net/) to sync your notes to the cloud, Yanki will also trigger this next step in the sync, automating the flow from Markdown → Anki → AnkiWeb in one shot.

### Existing notes are untouched

Yanki tags the notes it's in charge of with a hidden field, so it will never touch your existing Anki notes. (_But please exercise caution until the 1.0.0 release..._)

### Fancy markdown

An extended palette of markdown syntax is available out of the box:

- Most [GitHub Flavored Markdown](https://github.github.com/gfm/), including `| tables |`, `~~strike-throughs~~`, `- [x] task lists`, and autolinks.
- Syntax highlighting via [Shiki](https://shiki.style).
- GitHub-style [Alerts](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts).
- [WikiLinks](https://github.com/Python-Markdown/markdown/blob/master/docs/extensions/wikilinks.md)
- [LaTeX formatted mathematical expressions](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/writing-mathematical-expressions) via [MathJax](https://www.mathjax.org)
- Support for the [`==highlights==`](https://github.com/ipikuka/remark-flexible-markers) syntax.
- Support for the compact [furigana](https://en.wikipedia.org/wiki/Furigana) / [Ruby](https://en.wikipedia.org/wiki/Ruby_character) syntax specified by [DenDen Markdown](https://conv.denshochan.com/markdown#ruby), for example: `{東京|とうきょう}` renders as `東京(とうきょう)`.

### Custom styles

Yanki uses Anki's built-in CSS stylesheet to style cards by default, but it makes it simple to set a custom stylesheet for all of your Yanki-managed notes without having to go on a click-quest in the Anki user interface.

### Filename management

The "one Markdown file = one Anki note" can make for a lot of individual files, and thinking up and renaming files as content is revised can be tedious. So, if you want, Yanki can manage the names of your note files based on their content.

Yanki looks inside each note, and extracts either the text of the "prompt" (e.g. the front of the card in most cases), or the "response" (e.g. the back of the card in most cases) to use as the filename. Truncation, deduplication, and sanitization are all taken care of.

Edge cases are carefully managed to ensure that there's always _some kind_ of best-effort semantically valuable file name assigned.

### Media asset synchronization

Yanki can sync images, videos, and audio files embedded in your notes with Anki's media asset management system. At your option, it can sync local assets, or assets linked via URL, or both, or none.

Yanki automatically manages clean-up of synced media assets when you delete your notes, or when specific assets are removed from your notes.

Both wiki-style `![[something.png]]` and `![markdown](style.png)` asset embedding syntaxes are supported.

## Markdown note types

Yanki automatically infers the _type_ of Note you'd like to create in Anki based on the presence or absence of certain elements in your Markdown files.

The rules were designed with the semantic and visual nature of Markdown in mind.

The most minimal examples to "trigger" different note types are shown below, but the implementation can handle additional weirdness and will generally do the right thing if it encounters elements that might indicate conflicting note types.

You're free to use additional Markdown in your note files to style and structure the front and back of your flashcards.

### Basic

A **basic** card is created from any file with a `---`:

```md
This is the front of the card

---

This is the back of the card
```

### Basic (and reversed card)

Doubling up the `---` identifies the note as being **reversible** (and will result in the generation of two cards in Anki).

_Mnemonic: Twice the `---` for twice the cards._

```md
Sometimes the answer is the question

---

Sometimes the question is the answer
```

Yanki also supports adding "extra" content that will appear on the the back of both generated cards:

```md
Sometimes the answer is the question

---

Sometimes the question is the answer

---

This will appear on the back of both generated cards
```

### Basic (type in the answer)

If the last statement in the Markdown file is `_emphasized like this_`, it becomes the type-in-the-answer text in Anki.

Mnemonic: The syntax resembles a `_blank to be filled in_`.

```md
Jazz isn't dead

_It just smells funny_
```

---

### Cloze

Text that is `~~struck through~~` with the [somewhat esoteric double-tilde syntax](https://github.github.com/gfm/#strikethrough-extension-) will be hidden in the resulting _cloze_ card:

_Mnemonic: The `~~strike through~~` implies redaction._

```md
All will be ~~revealed~~.
```

Multiple clozes are supported, which will create additional cards. You can add a `---` to include back-of-card information as well. Hints are also supported, and are indicated by giving the hint text `_emphasis_` at the end of the cloze strike-through:

```md
~~All~~ will be ~~revealed _here's a hint_~~.

---

Additional revelations on the back of the card.
```

By default, clozes are numbered incrementally if there are more than one on a card, for example the Markdown:

```md
~~All~~ will be ~~revealed _here's a hint_~~.
```

Is turned into the following Anki syntax behind the scenes:

```text
{{c1::All}} will be {{c2::revealed::here's a hint}}
```

In rare cases, you might want to take control over cloze numbering — perhaps you want to reveal multiple clozes simultaneously on a single card, or group certain clozes together on a particularly cloze-heavy note.

To support this, Yanki offers some optional extra syntax. A leading one- or two-digit a number at the front of your clozed content will be interpreted as the cloze number:

For example:

```md
~~1 All~~ will be ~~1 revealed _here's a hint_~~.
```

Becomes the following Anki syntax.

```text
{{c1::All}} will be {{c1::revealed::here's a hint}}
```

The difference is subtle, but note the matching `{{c1`s. This markup yields a single card where both `All` and `revealed` are revealed simultaneously.

_Note: While you can encloze images, math equations, and other inline-styled syntax, clozing over multiple lines or block elements is not currently supported._

## Getting started

### Dependencies

The `yanki` CLI tool requires Node 18+. The exported TypeScript / JavaScript APIs are isomorphic, and can run in both browser-based and Node runtime environments. The Yanki library is ESM-only, is implemented in TypeScript, and bundles a complete set of type definitions.

The tool has been tested on Windows, macOS, and Linux.

#### Prerequisites:

- The [Anki desktop app](https://apps.ankiweb.net)
- The [Anki-Connect](https://foosoft.net/projects/anki-connect/) add-on

If you need to install it, select _Tools → Add-ons_ from the menu, click _Get Add-ons..._, and then enter the code `2055492159` in the field to get Anki-Connect.

Anki-Connect may ask for your permission in the Anki application to connect to Obsidian on the first sync.

If the automatic permission request fails, you might need to configure Anki-Connect to accept connections from your origin.

In Anki, select _Tools → Add-ons_ from the menu, then select _AnkiConnect_ from the list, and click the _Config_ button in the lower right. In the ensuing modal, add the host and port from which you're attempting to connect to to the `webCorsOriginList` array.

### Installation

Invoke directly:

```sh
npx yanki ./folder-to-sync/**/*.md
```

...or install globally:

```sh
npm install --global yanki
```

...or install locally in your JavaScript or TypeScript project to use the exported APIs:

```sh
npm install --save-dev yanki
```

## Usage

### Basics

#### Setup

Create a folder of Markdown files that you'd like to use as Anki notes. (See the [section on Markdown notes](#markdown-note-types) for details on how to structure your document to create different card types in Anki.)

Launch the Anki desktop app. Ensure that the [Anki-Connect](https://foosoft.net/projects/anki-connect/) add-on is installed and set up.

#### Create

Pass the path to a folder of Markdown notes to turn them into Anki notes and send them to the Anki database:

```sh
yanki ./your-deck-folder
```

You'll now see your Markdown files as HTML-rendered notes in the Anki desktop app.

#### Update

Edit the Markdown file locally (not in Anki!) and run `yanki ./your-deck-folder` again.

#### Delete

Delete the Markdown file locally (not in Anki!) and run `yanki ./your-deck-folder` again.

### CLI

All available commands and options for advanced use cases are described below, but shouldn't typically be necessary.

#### Command: `yanki`

Run a Yanki command. Defaults to `sync` if a command is not provided.

This section lists top-level commands for `yanki`.

If no command is provided, `yanki sync` is run by default.

Usage:

```txt
yanki [command]
```

| Command | Argument | Description |
| -------- | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `sync` | `` `[options]` | Perform a one-way synchronization from a local directory of Markdown files to the Anki database. Any Markdown files in subdirectories are included as well. _(Default command.)_ |
| `list` | `[options]` | Utility command to list Yanki-created notes in the Anki database. |
| `delete` | `[options]` | Utility command to manually delete Yanki-created notes in the Anki database. This is for advanced use cases, usually the `sync` command takes care of deleting files from Anki Database once they're removed from the local file system. |
| `style` | `[options]` | Utility command to set the CSS stylesheet for all present and future Yanki-created notes. |

_See the sections below for more information on each subcommand._

#### Subcommand: `yanki sync`

Perform a one-way synchronization from a local directory of Markdown files to the Anki database. Any Markdown files in subdirectories are included as well.

Usage:

```txt
yanki sync [options]
```

| Positional Argument | Description | Type |
| ------------------- | ------------------------------------------------------------------------ | -------- |
| `directory` | The path to the local directory of Markdown files to sync. _(Required.)_ | `string` |

| Option | Description | Type | Default |
| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ | ------------------------- |
| `--dry-run`
`-d` | Run without making any changes to the Anki database. See a report of what would have been done. | `boolean` | `false` |
| `--namespace`
`-n` | Advanced option for managing multiple Yanki synchronization groups. Case insensitive. See the readme for more information. | `string` | `"Yanki"` |
| `--anki-connect` | Host and port of the Anki-Connect server. The default is usually fine. See the Anki-Connect documentation for more information. | `string` | `"http://127.0.0.1:8765"` |
| `--anki-auto-launch`
`-l` | Attempt to open the Anki desktop app if it's not already running. (Experimental, macOS only.) | `boolean` | `false` |
| `--anki-web`
`-w` | Automatically sync any changes to AnkiWeb after Yanki has finished syncing locally. If false, only local Anki data is updated and you must manually invoke a sync to AnkiWeb. This is the equivalent of pushing the "sync" button in the Anki app. | `boolean` | `true` |
| `--manage-filenames`
`-m` | Rename local note files to match their content. Useful if you want to feel have semantically reasonable note file names without managing them by hand. The `"prompt"` option will attempt to create the filename based on the "front" of the card, while `"response"` will prioritize the "back", "Cloze", or "type in the answer" portions of the card. Truncation, sanitization, and deduplication are taken care of. | `"off"` `"prompt"` `"response"` | `"off"` |
| `--max-filename-length` | If `manage-filenames` is enabled, this option specifies the maximum length of the filename in characters. | `number` | `60` |
| `--sync-media`
`-s` | Sync image, video, and audio assets to Anki's media storage system. Clean up is managed automatically. The `all` argument will save both local and remote assets to Anki, while `local` will only save local assets, `remote` will only save remote assets, and `off` will not save any assets. | `"off"` `"all"` `"local"` `"remote"` | `"local"` |
| `--strict-line-breaks`
`-b` | Set to false to treat single newlines in Markdown as line breaks. | `boolean` | `true` |
| `--json` | Output the sync report as JSON. | `boolean` | `false` |
| `--verbose` | Enable verbose logging. | `boolean` | `false` |
| `--help`
`-h` | Show help | `boolean` | |
| `--version`
`-v` | Show version number | `boolean` | |

#### Subcommand: `yanki list`

Utility command to list Yanki-created notes in the Anki database.

Usage:

```txt
yanki list [options]
```

#### Subcommand: `yanki delete`

Utility command to manually delete Yanki-created notes in the Anki database. This is for advanced use cases, usually the `sync` command takes care of deleting files from Anki Database once they're removed from the local file system.

Usage:

```txt
yanki delete [options]
```

| Option | Description | Type | Default |
| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ------------------------- |
| `--dry-run`
`-d` | Run without making any changes to the Anki database. See a report of what would have been done. | `boolean` | `false` |
| `--namespace`
`-n` | Advanced option to list notes in a specific namespace. Case insensitive. Notes from the default internal namespace are listed by default. If you've synced notes to multiple namespaces, Pass `'*'` to delete all Yanki-created notes in the Anki database. | `string` | `"Yanki"` |
| `--anki-connect` | Host and port of the Anki-Connect server. The default is usually fine. See the Anki-Connect documentation for more information. | `string` | `"http://127.0.0.1:8765"` |
| `--anki-auto-launch`
`-l` | Attempt to open the Anki desktop app if it's not already running. (Experimental, macOS only.) | `boolean` | `false` |
| `--anki-web`
`-w` | Automatically sync any changes to AnkiWeb after Yanki has finished syncing locally. If false, only local Anki data is updated and you must manually invoke a sync to AnkiWeb. This is the equivalent of pushing the "sync" button in the Anki app. | `boolean` | `true` |
| `--json` | Output the list of deleted notes as JSON to stdout. | `boolean` | `false` |
| `--verbose` | Enable verbose logging. | `boolean` | `false` |
| `--help`
`-h` | Show help | `boolean` | |
| `--version`
`-v` | Show version number | `boolean` | |

#### Subcommand: `yanki style`

Utility command to set the CSS stylesheet for all present and future Yanki-created notes.

Usage:

```txt
yanki style [options]
```

| Option | Description | Type | Default |
| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ------------------------- |
| `--dry-run`
`-d` | Run without making any changes to the Anki database. See a report of what would have been done. | `boolean` | `false` |
| `--css`
`-c` | Path to the CSS stylesheet to set for all Yanki-created notes. If not provided, the default Anki stylesheet is used. | `string` | |
| `--anki-connect` | Host and port of the Anki-Connect server. The default is usually fine. See the Anki-Connect documentation for more information. | `string` | `"http://127.0.0.1:8765"` |
| `--anki-auto-launch`
`-l` | Attempt to open the Anki desktop app if it's not already running. (Experimental, macOS only.) | `boolean` | `false` |
| `--anki-web`
`-w` | Automatically sync any changes to AnkiWeb after Yanki has finished syncing locally. If false, only local Anki data is updated and you must manually invoke a sync to AnkiWeb. This is the equivalent of pushing the "sync" button in the Anki app. | `boolean` | `true` |
| `--json` | Output the list of updated note types / models as JSON to stdout. | `boolean` | `false` |
| `--verbose` | Enable verbose logging. | `boolean` | `false` |
| `--help`
`-h` | Show help | `boolean` | |
| `--version`
`-v` | Show version number | `boolean` | |

### Library

#### API

This package also exposes an API for integrating syncing capability programmatically in other contexts. (For example, in the [`yanki-obsidian`](https://github.com/kitschpatrol/yanki-obsidian) plugin.)

The primary functions of interest are:

```ts
function getNoteFromMarkdown(
markdown: string,
options?: Partial,
): Promise

function syncNotes(
allLocalNotes: YankiNote[],
options?: PartialDeep,
): Promise

function syncFiles(
allLocalFilePaths: string[],
options?: PartialDeep,
): Promise

function listNotes(options?: PartialDeep): Promise

function cleanNotes(options?: PartialDeep): Promise

function setStyle(options?: PartialDeep): Promise
```

See the [source code](https://github.com/kitschpatrol/yanki/blob/main/src/lib/index.ts) for additional exports and inline documentation.

## Advanced features

### Namespaces

For simplicity's sake, Yanki anticipates syncing one folder of notes on one machine as its primary use case. Every note uploaded to Anki has a "namespace" string in a hidden field. Yanki uses this field to identify the notes it's in charge of, and to identify notes for deletion if they are present in the Anki database but missing in the collection of local markdown notes.

For example, if you run:

```sh
yanki sync ./important-cards
```

Followed by:

```sh
yanki sync ./more-important-cards
```

Any notes synced from the `important-cards` folder _will be deleted_ from Anki by the second command to sync `more-important-cards`, because they share the same default namespace, and because your local notes are a single source of truth for the sync system.

If you don't want this behavior, then you can pass the `--namespace` flag to explicitly state that you want the commands to execute in separate namespaces:

```sh
yanki sync ./important-cards --namespace "Foo"
yanki sync ./more-important-cards --namespace "Bar"
```

This will let both directories sync and co-exist.

But in general, a better solution would be to give them a common parent directory and, just sync that:

```sh
# Move to a common parent
mv ./important-cards ~/cards/imporant-cards
mv ./more-important-cards ~/cards/more-important-cards

# Sync the parent
yanki sync ~/cards
```

This makes `~/cards` the single source of truth, and spares the cognitive overhead of namespaces.

Yanki will put the cards in eponymous decks, so you'll still have a clean separation of the two groups of cards in Anki.

### Media asset synchronization

By default, Yanki will automatically copy local image, media, and audio media linked in your notes' markdown to Anki's media storage system. With an option, it can do the same for remote assets.

Note that there Anki's underlying implementation requires media assets to be less than 100 MB in size. There are also internal limits around filename length, but Yanki manages the filename for you internally, so this is not a concern.

Support file formats / codecs is a bit nuanced, and some variations have been observed between what is officially supported according to the Anki source code and what actually works in practice on different platforms.

The subset of the officially supported formats that have shown the broadest compatibility in testing Yanki are:

- Image: `jpeg`, `png`, `svg`
- Audio: `mp3`
- Video: `mp4`, `gif`

See the [document on file formats](./docs/file-formats.md) for additional details and a full compatibility matrix.

### Styles

The [`yanki style`](#subcommand-yanki-style) command lets you assign a CSS stylesheet to all Yanki-managed notes.

Because of how styles work in Anki and how Yanki manages card models, assigned style is a _global_ operation to _all_ Yanki-managed cards. (Though your other Anki cards, as always, will be untouched.)

Your custom stylesheets can take advantage of several CSS classes added to the top-level `

` of each card by Yanki.

The classes include:

- `yanki`: Shared by all cards generated by Yanki
- `namespace-$name`: The namespace associated with the card
- `front` | `back`: The "side" of the card"
- `model-$name`: The name of the card type / model, one of the following. They're wordy, but consistent with Anki's default model naming scheme:
- `model-yanki-basic`
- `model-yanki-basic-and-reversed-card`
- `model-yanki-basic-type-in-the-answer`
- `model-yanki-cloze`

For example, the front of a basic card would look like:

```html

```

### Browser environments

The Yanki TypeScript / JavaScript library is idempotent, so you can run it in a browser you'd like.

There's one exception, the `syncFiles(...)` function, which by default relies on file system access to work.

To retain `syncFiles(...)`'s utility in a browser environment, has the optional arguments `readFile`, `writeFile`, and `rename`, which are implemented by `node:fs/promises` by default in Node environments.

Running Yanki in a browser environment requires implementing and passing `readFile`, `writeFile`, and `rename` implementations to `syncFiles(...)` that are suited to your particular use case. (A warning will be provided if you neglect to do so.)

The rest of the library should work fine in both contexts without special measures.

## Background

### Implementation notes

The excellent [unified](https://unifiedjs.com) / [remark](https://remark.js.org) / [rehype](https://github.com/rehypejs/rehype) libraries are used extensively to traverse and render the underlying Markdown ASTs.

[Anki-Connect](https://foosoft.net/projects/anki-connect/) provides access to Anki's database.

For type safety, access to Anki-Connect is managed through my wrapper library, [yanki-connect](https://github.com/kitschpatrol/yanki-connect).

Behind the scenes, Yanki creates new note type models to match the four default Anki types. It keeps track of the notes it has ownership of via a hidden `YankiNamespace` field in each note.

Linux testing was performed on a Debian 12 arm64 virtual machine. Anki does not officially support arm64 linux, but a [workaround](https://github.com/ankitects/anki/issues/2302#issuecomment-1374374155) was able to get Anki up and running.

### Other projects

- Luke Murray's [markdown-anki-decks](https://github.com/lukesmurray/markdown-anki-decks)
- Oleksandr Shlinchak's [mdanki](https://github.com/ashlinchak/mdanki).
- Ben Weinstein-Raun's [ankidown](https://github.com/ankicommunity/ankidown/)
- Alex Biosa's [Markdown2Anki](https://github.com/Mochitto/Markdown2Anki)
- Pradhyo Bijja's [anki-markdown-notes](https://github.com/Pradhyo/anki-markdown-notes)
- langfield's [ki](https://langfield.github.io/ki/)

## Known issues

- [ ] Intra-note links _do not update_ after automatic renaming, e.g. via the `--manage-filenames` flag, potentially resulting in broken links.

## The future

Possible features on the horizon:

- [ ] Command to convert markdown notes to Anki packages (`.apkg` files), instead of syncing directly with Anki.
- [ ] Sync and store Anki's review statistics to the Markdown file's frontmatter. This could be useful to both "back up" progress made in Anki, and to afford integration with other local tools. (In exchange for some extra noise in the frontmatter.)
- [ ] Model migrations.
- [ ] Include a built-in CSS stylesheet, since Anki's defaults can't always anticipate the kinds of HTML you're likely to generate from Markdown.
- [ ] Mermaid diagrams support. (Unlikely since rendering to an SVG seems to require a browser. See [rehype-mermaid](https://github.com/remcohaszing/rehype-mermaid) and [remark-mermaidjs](https://github.com/remcohaszing/remark-mermaidjs).)
- [ ] It would be nice to find a way to talk to the Anki database that doesn't require the Anki app to be running, but my research hasn't yet turned up anything as robust and reliable as Anki-Connect for this purpose.

## Maintainers

[@kitschpatrol](https://github.com/kitschpatrol)

## Acknowledgments

Thanks to Alex Yatskov for creating [Anki-Connect](https://foosoft.net/projects/anki-connect/).

Thanks to the [unified team](https://github.com/orgs/unifiedjs/people) for their superb ecosystem of AST tools.

## Contributing

[Issues](https://github.com/kitschpatrol/yanki/issues) and pull requests are welcome.

## License