bao-tg

obsidian-kindle-vocab

3 min read

Developer Documentation – Obsidian Kindle Vocabulary Builder Plugin

Welcome to the developer documentation for the Obsidian Kindle Vocabulary Builder. This guide will help you understand the architecture, extend functionality, and contribute effectively to the plugin.

1. Overview

  • Plugin Name: kindle-vocab
  • Project Origin: Originally developed as a Spring 2025 course project at VinUniversity. It emerged from a personal pain point — the lack of a simple way to export Kindle Vocabulary Builder data into Markdown for use in Obsidian.

I decided to open-source this tool to learn from the developer community. Building in public is the best way to grow and get feedback.

  • Key Features:

    • Generate Markdown from your Kindle lookups (vocab.db)
    • Integrate your own dictionary files (CSV)
    • Mark words as “Learned/Unlearned” with checkbox interactivity
    • View stats like % learned
    • Sort words by timestamp or unlearned-first

  • Target Users: Users of both Kindle and Obsidian.

Demo

2. Getting Started

Based on the Obsidian Plugin Development Guide

2.1 Prerequisites

Make sure you have the following installed:

2.2 Local Development Setup

⚠️ Important: Always use a separate development vault. Do not develop plugins in your main Obsidian vault.

Create the plugins directory inside your vault

cd path/to/your-dev-vault
mkdir -p .obsidian/plugins
cd .obsidian/plugins

Clone the repository

git clone https://github.com/bao-tg/kindle-vocab
cd kindle-vocab

Install dependencies and build/run

npm install
npm run dev

Then:

  • Reload your plugins.
  • Open Developer Tools in Obsidian and load the plugin.
  • Enable the plugin under Settings > Community Plugins.
  • Reload the plugin in Settings after making updates.

3. Plugin Architecture

src/                            
├── commands/                  
│   └── CommandsHandlers.ts     # Registers and defines custom plugin commands
├── data/                      # (Empty or reserved) For future data storage or constants
├── modals/                    
│   ├── DatabaseUploadModal.ts   # Modal to upload Kindle's vocab.db file
│   ├── DictionaryUploadModal.ts # Modal to upload custom dictionary CSV
│   └── SyncDatabaseModal.ts     # Modal for syncing database and generating Markdown
├── ribbon/                    
│   └── RibbonHandlers.ts       # Adds and handles ribbon icon behavior
├── settings/                  
│   ├── Settings.ts             # Defines the plugin's settings schema and defaults
│   └── SettingTab.ts           # Renders the settings tab UI in Obsidian
├── utils/                    
│   ├── MarkdownFormat.ts       # Generates interactive Markdown output and listeners
│   └── PathHelper.ts           # Path resolution for vault, plugin data, etc.
└── main.ts                   # Entry point: initializes plugin, settings, and features

4. Contributing

We welcome community contributions! Follow the steps below to contribute:

  1. Fork the repository.
  2. Create a feature branch:
git checkout -b feature/my-feature
  1. Write clear and meaningful commit messages.
  2. Run linting before committing:
npm run lint
  1. Submit a Pull Request with a detailed description of your changes.

5. Licensing & Credits

This project is licensed under the MIT License.

  • Author: Truong Gia Bao
  • GitHub: @bao-tg

If you find this plugin useful and would like to support its development:

Buy Me A Coffee

6. References & Resources