# VocabWeave
**Write vocabulary in Obsidian. Study it in Anki. Let AI do the busywork.**
[](https://github.com/stoic031/vocabweave/releases/latest)
[](https://obsidian.md)
[](#requirements)
[](LICENSE)
[](https://buymeacoffee.com/stoic031)
VocabWeave turns plain Obsidian notes into Anki flashcards. You keep one clean note per
word, with a heading for each field. VocabWeave maps those headings onto your Anki note
type and keeps both sides in sync. If you want, an AI provider of your choice can fill in
definitions and example sentences, and draw a picture for the card.
## Why VocabWeave
- **One source of truth.** Your vocabulary lives in your vault as readable Markdown, not
locked inside Anki.
- **Works with your existing Anki setup.** Any deck, any note type, any field names.
Nothing is hardcoded.
- **AI is optional and yours to choose.** Cloud or fully local, bring your own key, and
review every result before it's written.
- **Your vault stays clean.** Generated images go straight into Anki's media folder,
never into your vault.
## Features
### π Sync
- **Dynamic field mapping.** Each `## Heading` in the note fills the Anki field of the
same name, and common aliases also work (for example `## Word` β `Front`).
- **Sync, rebuild, or delete** the active note from the sidebar in one click.
- **Two-way awareness.** If you edited the card in Anki, VocabWeave notices on the next
sync and asks which version to keep instead of silently overwriting it.
- **Auto sync on save** (off by default) for notes that already have a deck and model.
- **The note name follows the main field**, so your file list reads like a word list.
### βοΈ Create
- **Profiles** bundle a deck, a note type, and a save folder, so switching languages is
one dropdown.
- **Create new note** gives you an empty note with one section per field of the model.
- **Create note from selection** turns highlighted text into a new card note.
### β¨ AI (optional)
- **Generate field text** (meanings, example sentences, translations) into an
editable preview. Nothing touches your note until you press **Write**.
- **Generate images** for a card. They're stored in Anki's media folder and still
display inside Obsidian.
- **Language-aware.** Set your learning language and your own language once, and
results follow them.
## Requirements
- **Obsidian 1.13.0 or newer**, desktop only. VocabWeave talks to Anki on your own
computer, so Obsidian Mobile isn't supported.
- **[Anki](https://apps.ankiweb.net/)** with the
**[AnkiConnect](https://foosoft.net/projects/anki-connect/)** add-on (code
`2055492159`), running while you sync.
## Quick start
1. **Install AnkiConnect** in Anki (_Tools β Add-ons β Get Add-onsβ¦_, code
`2055492159`), then restart Anki.
2. **Install VocabWeave** from _Settings β Community plugins β Browse_, and enable it.
3. Open **Settings β VocabWeave**, press **Connect**, then create a **profile** by
picking a deck, a note type, and a folder for new notes.
4. Run the command **VocabWeave: Create new note**, name it, and fill in the sections.
5. Press **Sync** in the VocabWeave sidebar. The card is now in Anki. π
## What a note looks like
A note is just properties plus one section per Anki field:
```markdown
---
anki_deck: Japanese::N2
anki_model: Basic
---
## Front
θ¬
## Back
medicine; drug
```
After the first sync, VocabWeave adds a few properties of its own (such as
`anki_note_id`) so it can update the same card next time. Leave them in place.
## Commands
| Command | What it does |
| ------------------------------ | ---------------------------------------------------------- |
| `Create new note` | Asks for a name and creates a note from the active profile |
| `Create note from selection` | Creates a note from the selected text in the current note |
| `Open deck and model selector` | Opens the VocabWeave sidebar |
Assign hotkeys to any of them in _Settings β Hotkeys_.
## AI providers
Add providers under **Settings β VocabWeave**. None are configured out of the box.
| Provider | Runs | Text | Image |
| ------------- | ----- | :--: | :---: |
| OpenAI | Cloud | β
| β
|
| Gemini | Cloud | β
| β
|
| OpenRouter | Cloud | β
| β
|
| Anthropic | Cloud | β
| |
| Groq | Cloud | β
| |
| Together | Cloud | β
| |
| Pollinations | Cloud | | β
|
| Ollama | Local | β
| |
| Automatic1111 | Local | | β
|
| ComfyUI | Local | | β
|
Each provider's base URL can be changed, so self-hosted and compatible endpoints work
too. A provider pointing at `localhost` is labelled local.
## Privacy & network use
- **AnkiConnect (local):** VocabWeave connects to AnkiConnect on your computer
(`http://localhost:8765` by default). It reads decks and note types, and creates,
updates, or deletes notes and media.
- **AI providers are off by default.** Nothing leaves your computer until you add a
provider yourself. Each provider is labelled **cloud** or **local** in settings.
- **What is sent:** when you press **Generate** or **Add image**, the active note's word
and fields, your prompt, your language settings, and examples you approved earlier go
to the one provider you picked. No other notes are read.
- **API keys** are stored in Obsidian's secret storage and sent only to their provider.
- **No telemetry, analytics, or ads.**
## Troubleshooting
"Anki is not running" but Anki is open
Check that AnkiConnect is installed (_Tools β Add-ons_) and that Anki was restarted
afterwards. If you changed AnkiConnect's address, set the same URL under
**Settings β VocabWeave β AnkiConnect URL**.
Sync says the note is a duplicate
Anki already has a note with the same first field. Change the first field in your note,
or delete the old card in Anki, then sync again.
An image shows in Anki but not in Obsidian
Images live in Anki's media folder, so Obsidian shows them only while Anki is running.
Open Anki and reopen the note.
Something else? [Open an issue](https://github.com/stoic031/vocabweave/issues). Steps
to reproduce and your Obsidian/Anki versions help a lot.
## Support β
VocabWeave is free and built in spare time. If it saves you time, you can buy me a
coffee to keep it going.
Starring the repo and sharing it with other learners helps too. Thank you! π
## Contributing
Bug reports and pull requests are welcome.
Development setup
```bash
npm i # install dependencies
npm run dev # build in watch mode
npm run build # production build
npm run lint # ESLint
npm run type-check # tsc --noEmit
npm run test:unit # Vitest
npm run format:write # Prettier
```
A change is done when `npm run lint && npm run type-check && npm run test:unit` all pass.
For manual testing, copy `main.js`, `manifest.json`, and `styles.css` into
`/.obsidian/plugins/vocabweave/`, reload Obsidian, and keep Anki + AnkiConnect
running.
- [`docs/design/`](docs/design/README.md): behavior spec, module by module
- [`docs/contracts.md`](docs/contracts.md): TypeScript interfaces and the field-mapping algorithm
- [`AGENTS.md`](AGENTS.md): repo layout and conventions
## License
[0BSD](LICENSE) Β© 2026 Andy Nguyen