An Obsidian plugin for ultra-simple automated flashcard syncing from a folder in your vault to Anki. Pure Markdown syntax. Minimal configuration. No fuss.
Important
The Yanki Obsidian plugin 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.
The plugin is currently available for download and installation directly from GitHub for advanced users. It will be submitted for review and potential inclusion as an Obsidian community plugin once I am completely confident in its design and reliability. (Expected in July, 2024.)
Any testing and feedback by adventurous users is extremely welcome.
- Overview
- Quick start
- Features
- Markdown note types
- Usage
- FAQ
- The future
- Background
- Maintainers
- Acknowledgments
- Contributing
- License
The Yanki plugin automatically syncs a folder (or folders) of notes from your Obsidian vault 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:
-
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.
This also means that your flashcard notes remain nice and legible in Obsidian, and you don't have to deal with the cognitive switch of
```fenced```regions and Anki's rather noisy templating syntax. -
The parent folder of your notes in your Obsidian vault determines their deck name in Anki, with any intermediate hierarchies created as needed.
- Prerequisites
-
The Anki desktop app
-
The 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
2055492159in 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 you encounter trouble with Anki-Connect, please see the manual configuration procedure.
-
Plugin installation
For now, download the latest release from GitHub and drag it in your vault's
.obsidian/plugins.Restart Obsidian.
-
Setup
Enable the plugin, and go to its settings tab to select which folders of notes you'd like to sync to Anki. See the section [Markdown note types]](#markdown-note-types) on how to format your notes to create different Anki card types.
-
Sync
Syncing happens automatically by default whenever notes in your watched flashcard folders change. Or you can force a sync using
Yanki: Sync flashcard notes to Ankicommand or the button in the Yanki settings tab. -
Study
Pop over to the Anki app, and you should see the Obsidian notes from your selected folders organized into decks in Anki that match your vault's folder hierarchy.
Avoid the complexity of mixing and matching multi-note and single-note syntaxes. One note in Obsidian always yields one Anki note.
Yanki uses your Obsidian note's parent folder 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 your vault.
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.
Since the number of supported note types is small, the type of Anki note to create from a given Obsidian note 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:
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.
The values in the tags array of your note's properties will be added as tags in Anki. This gives nice interoperability with Obsidian's tag system, which treats frontmatter tags as first-class tag citizens.
Detecting Obsidian #tags in the document body is not currently supported, but plugins like Victor Tao's Obsidian Linter can automate tag migration from the document body to frontmatter, where Yanki (and thus Anki) can see it.
Jump back to sources in Obsidian while studying in Anki.
The Yanki plugin detects your vault's name, and automatically turns any internal [[WikiLinks]] in your notes into obsidian:// protocol links, which you can click through in Anki to get back to the source in Obsidian.
An extended palette of markdown syntax is available out of the box:
- GitHub Flavored Markdown, including
| tables |,~~strike-throughs~~,- [x] task lists, and autolinks. - Syntax highlighting via Shiki.
- GitHub-style Alerts.
- The aforementioned WikiLinks.
- LaTeX formatted mathematical expressions via MathJax.
- Support for the
==highlights==syntax.
Your local Obsidian markdown notes 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 Obsidian note, Yanki makes every effort to update rather than delete it in the Anki database so that review progress is preserved.
But when you do want to delete something, it's as simple as deleting it from Obsidian, and it will be removed from the Anki database on the next sync. Protections are in place to prevent deleting Anki notes that weren't initially created by Yanki.
If you use AnkiWeb 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. (Configurable via a setting.)
When the Automatic Sync option is enabled, Yanki will automatically updated notes to Anki whenever flashcard notes are created, deleted, or updated in Obsidian.
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 release...)
The "one Obsidian note = one Anki note" premise can make for a lot of individual note files, and thinking up and renaming notes as their 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.
Yanki automatically infers the type of Note you'd like to create in Anki based on the presence or absence of certain element in your Markdown notes.
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 notes to style and structure the front and back of your flashcard notes. Image markup will work, but currently assets must be hosted externally and are not copied into Anki's media storage system.
A basic card is created from any file with a ---:
This is the front of the card
---
This is the back of the cardDoubling 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.
Sometimes the answer is the question
---
---
Sometimes the question is the answerMnemonic: The syntax resembles a _blank to be filled in_.
If the last statement in the Markdown file is _emphasized like this_, it becomes the type-in-the-answer text in Anki.
Jazz isn't dead
_It just smells funny_Text that is ~~struck through~~ with the somewhat esoteric double-tilde syntax will be hidden in the resulting cloze card:
Mnemonic: The ~~strike through~~ implies redaction.
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:
~~All~~ will be ~~revealed _but here's a hint_~~.
---
Additional revelations on the back of the card.Clozing a block element is not currently supported.
The Yanki plugin provides a single command, which works as advertised:
Yanki: Sync flashcard notes to Anki
But you shouldn't need to sync manually if automatic sync is enabled.
Yanki will sync notes in the vault folders specified here to Anki.
Folder syncing is always recursive.
Anki decks will be created automatically to match the hierarchy of your Obsidian folders.
Selecting multiple folders from different parts of your vault is fine, they'll just end up in different Anki decks.
Use care when editing or deleting folders from this list, since notes will be deleted from Anki (along with their review statistics) on the next sync.
When enabled, notes matching the name of their parent folder will not be synced. This is useful if you use the folder notes plugin to keep a top-level note per folder.
Default: Enabled
When enabled, local note files will be renamed to match their content. This is useful if you want to feel have semantically reasonable note file names without managing them by hand.
If the prompt or response has multiple lines, only the first line is considered.
The file renaming pass runs as part of every sync to Anki, and only affects notes in side a watched folder. Even if the Anki application is closed, attempting a sync will still update the local flashcard note file names.
There are some great community plugins dedicated to content-driven file naming, like Rey Christian's Auto Filename plugin, but the feature is built into Yanki since the renaming process can be more precise when it understands the structure of flashcard notes.
Default: Off
If Automatic note names is enabled, this setting allows you to prioritize which part of the flashcard note should be used for the automatic note file name.
The "Prompt" option will attempt to create the filename based on the what Anki would show you first — usually the front of the card. The while "Response" option will prioritize whatever Anki would show you second — usually the back of the card, or the elided text in the case of a cloze card, or the type-in part of a type in the answer card.
For edge cases, like notes with empty prompt content or no response content, Yanki will fall back to the other parts of the card to try to . If, after every effort, no reasonable title can be identified, then "Untitled" will be used.
Default: Prompt
Yanki will truncate long automatic file names with ellipses. This setting allows you to specify, in characters, how long of an automatic title you would like (exclusive of the truncation ellipses and file extension). Note that a (generous) upper limit is enforced to comply with operating system limitations.
Default: 60 characters
Yanki watches the notes in your flashcard folders for changes, additions, deletions, etc, and will trigger a sync to Anki (almost) immediately after it sees a change.
If you disable this, syncing must be initiated manually either via a command or the "Sync now" button in the setting tab.
Default: Enabled
There are (potentially) three places your note data lives:
- The Obsidian application — Markdown notes, the single source of truth.
- The Anki application — The local database of notes.
- AnkiWeb — Anki's first-party note syncing service, which brings your notes to the browser and the Anki mobile app.
"Syncing" in Yanki is focused on going from 1 → 2, but when the "Push to AnkiWeb" option is enabled, Yanki will ask the Anki Desktop application to take care of syncing from 2 → 3. (Basically the equivalent of pushing the "Sync" button in the Anki Desktop app.)
This happens on a best-effort basis, and Yanki doesn't get any feedback on whether syncing forward to AnkiWeb worked or not, so your mileage may vary.
Default: Enabled
These are advanced settings to accommodate custom Anki-Connect configurations. The defaults are almost certainly fine.
You don't! Enable the automatic note naming setting.
No, and it probably never will since it needs to communicate with a running instance of the Anki desktop app. (It's technically feasible with some network contortions, but that's not anything I'd wish on anyone.)
Yes, unfortunately. There are other ways to talk to the Anki database, but none are as robust as what's provided by Anki-Connect, which is where this requirement comes from.
Yes, as long as they stay within a folder registered in the Yanki plugin's settings, they will continue to sync. Yanki simply moves the cards to whatever deck reflects the new parent folder in Obsidian on the next sync.
Not sure, let me know. There's room for optimization in the current sync implementation.
Just delete it from Obsidian, or move it to a folder than Yanki isn't set up to watch. It will be deleted from Anki on the next sync. (You can re-add it, but any history about the note in Anki will have been lost.)
No, Obsidian is the source of truth. Any changes to or deletions of Yanki-managed notes in in Anki will be overwritten on the next sync.
Not yet, at least not using Obsidian's asset model. Remote-linked images work fine for the time being.
No, Yanki only supports the four note types described in the Markdown note types section. If you need fancy note types and custom templates, the other Obsidian Anki plugins have you covered.
No, it only touches the notes it creates. However, it's recommended to avoid deck name collisions between your existing Anki notes and notes synced by Yanki. (Though even then Yanki should leave your existing notes alone.)
It's Anki's internal ID for the note, which is saved after the first sync.
Don't. If it goes missing, Yanki will consider the ID-less note in Anki to be an orphan, and it will be deleted on the next sync, and a new ID will be created. You won't lose your note, because it's safe in Obsidian, but you will lose stats in Anki, so touching the noteID is not recommended.
Shield your eyes with a CSS snippet:
div.metadata-property[data-property-key='noteId'] {
display: none;
}Yes, frontmatter is fine, as long as it's valid YAML. Yanki just ignores all of it except for the tags and noteId fields.
Yanki will try to preserve the noteId of the note that matches what's been synced to Anki in the past, and will create new noteIds for the remaining duplicates. But this is a bit risky and not super-recommended.
If I use the folder notes plugin, will my folder notes become Anki notes?
The Yanki Plugin has a settings option to ignore folder notes. It's enabled by default.
If the automatic permission request fails, you might need to configure Anki-Connect to accept connections from Obsidian.
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 "app://obsidian.md" to the webCorsOriginList array, like so:
{
"apiKey": null,
"apiLogPath": null,
"ignoreOriginList": [],
"webBindAddress": "127.0.0.1",
"webBindPort": 8765,
"webCorsOrigin": "http://localhost",
"webCorsOriginList": ["http://localhost", "app://obsidian.md"]
}A few features are under consideration:
- Integration with Obsidian's image asset system.
- Links back to the Obsidian source note on each card in Anki.
- Nicer stylesheets / theming for notes in both Anki and Obsidian.
- Sync Anki's review statistics back to Obsidian.
- Render Markdown → HTML with Obsidian's pipeline + stylesheets.
If you have others in mind, feel free to open an issue with a suggestion.
The Yanki plugin is built on yanki, a command line tool and TypeScript library that handles all the Markdown wrangling and communication with Anki. If you want to sync Markdown like the Yanki plugin does from outside of Obsidian, yanki implements the same features (plus a few extras). Using the yanki CLI tool will not interfere with syncing from the Yanki Obsidian plugin.
In turn, yanki is built on top of yanki-connect, which is a layer of TypeScript over the Anki-Connect API.
- Export to Anki / Obsidian_to_Anki
- AnkiBridge
- Flashcards
- Anki Sync
- Note Synchronizer
- Awesome Flashcard
- Auto Anki
- text2anki-openai
- AnkiSync+
Thanks to Alex Yatskov for creating Anki-Connect.
PJ Eby's Hot-Reload Obsidian plugin is a huge help during development.
Figuring out Obsidian's AbstractInputSuggest class for the folder selection settings depended on examples in projects by Daniel Rodríguez Rivero and Liam Cain.
Issues and pull requests are welcome.
MIT © Eric Mika