yanki

# 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.**   ## 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 [Anki-Connect](https://ankiweb.net/shared/info/2055492159) 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 them automatically synchronized to the Anki database. Frontmatter is also used to store the Anki note's ID after an initial synchronization. Nested tags are supported, and you may use `/` in addition to `::` as a delimiter in the Markdown frontmatter for compatibility with tools like Obsidian. ### Intelligent synchronization Your local Markdown files are the single point of truth for what will end 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 recreate 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. If you accidentally delete the frontmatter with the associated Anki `noteId` in your local Markdown note, Yanki will do its best to repair the frontmatter and re-associate your Markdown notes with your existing Yanki notes. ### Existing notes are untouched Yanki keeps track the notes it manages with a hidden field in the Anki note model, so it will never touch your existing Anki notes. ### 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-through~~`, `- [x] task lists`, and auto-links. - 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 `<ruby>東京<rp>(</rp><rt>とうきょう</rt><rp>)</rp></ruby>`. ### 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. _Linux users should note that the Flatpak / Flathub version of Anki is not recommended, because of reported issues with media asset sync and `obsidian://` URI links. Linux systems might require [extra steps](https://amir.rachum.com/obsidian-uri-linux/) to register Obsidian URI links._ #### Prerequisites: - The [Anki desktop app](https://apps.ankiweb.net) - The [Anki-Connect](https://ankiweb.net/shared/info/2055492159) 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://ankiweb.net/shared/info/2055492159) add-on is installed and set up. #### Create Pass the path to a folder of Markdown notes to turn into Anki notes and send 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` | `<directory>` `[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 <directory> [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-matching` | Consider notes to be a "match" only if the local Markdown frontmatter `noteId` matches the remote Anki database `noteId` exactly. When disabled, Yanki will attempt to reuse existing Anki notes whose content matches a local Markdown note, even if the local and remote `noteId` differs. This helps preserve study progress in Anki if the local Markdown frontmatter is lost or corrupted. In Yanki 0.17.0 and earlier, `--strict-matching` was the default behavior. Starting with version 0.18.0, it is disabled by default and may be enabled via this flag. | `boolean` | `false` | | `--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] ``` | Option | Description | Type | Default | | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ------------------------- | | `--namespace` `-n` | Advanced option to list notes in a specific namespace. Case insensitive. Notes from the default internal namespace are listed by default. Pass `'*'` to list 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` | | `--json` | Output the list of notes as JSON to stdout. | `boolean` | `false` | | `--help` `-h` | Show help | `boolean` | | | `--version` `-v` | Show version number | `boolean` | | #### 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<GetNoteFromMarkdownOptions>, ): Promise<YankiNote> function syncNotes( allLocalNotes: YankiNote[], options?: PartialDeep<SyncOptions>, ): Promise<SyncNotesResult> function syncFiles( allLocalFilePaths: string[], options?: PartialDeep<SyncFilesOptions>, ): Promise<SyncFilesResult> function listNotes(options?: PartialDeep<ListOptions>): Promise<ListResult> function cleanNotes(options?: PartialDeep<CleanOptions>): Promise<CleanResult> function setStyle(options?: PartialDeep<StyleOptions>): Promise<StyleResult> ``` 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 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 `<div>` 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 <div class="yanki namespace-yanki front model-yanki-basic">  </div> ``` ### Browser environments The Yanki TypeScript / JavaScript library is isomorphic, 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://ankiweb.net/shared/info/2055492159) 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 with Debian 12 and Ubuntu 22, both running on an 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://ankiweb.net/shared/info/2055492159). 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 [MIT](license.txt) © Eric Mika