Capture quick notes while reading with Markdown support and Obsidian compatibility.
- Auto-Save: Notes are automatically saved as you type - first keystroke creates the file
- Save & New: One tap to save current note and immediately start a new one
- Quick Note Capture: Create notes without leaving your book
- Markdown Support: Full Markdown syntax with toolbar buttons
- Obsidian Compatible: Notes saved as timestamped
.mdfiles - E-ink Optimized: Designed for E-ink displays
- Color UI Support: Color-coded buttons on color e-readers (optional)
The plugin automatically detects color e-readers and adds color-coded buttons:
- Bold: Blue
- Italic: Green
- Code: Amber/Yellow
- Headings: Purple
- Lists: Orange
- Link: Teal
- Wiki Link: Cyan
- Done/Save: Green (primary action)
- Save & New: Blue (secondary action)
- Delete: Red (destructive action)
Supported Color Devices:
- Kindle Oasis (10th gen+), Kindle Paperwhite (11th gen+)
- Kobo Elipsa, Libra 2, Sage, Clara Colour
- PocketBook Color, InkPad Color
- Cervantes Color
E-ink Devices: Color support is automatically disabled on grayscale E-ink devices - buttons use standard styling.
User Preference: You can disable color UI even on color devices (see User Settings below).
- First keystroke creates a timestamped
.mdfile (e.g.,2026-01-14-16-56-30.md) - Every keystroke updates the existing file in real-time
- Done button confirms the note and closes the editor
- Save & New button saves current note and opens a fresh editor
- Delete button prompts to delete the auto-saved file
This means your notes are never lost - even if you accidentally close the editor or your device crashes, your note is already saved to disk.
-
Find your KOReader plugins directory on your device:
Device Plugins Directory Kobo .adds/koreader/plugins/Kindle koreader/plugins/Android <storage>/koreader/plugins/Windows C:\Users\<User>\App\Local\koreader\plugins\macOS ~/.config/koreader/plugins/Linux ~/.config/koreader/plugins/ -
Copy the plugin folder to the plugins directory:
# Make sure the folder name ends with .koplugin cp -r fleeting-notes.koplugin /path/to/koreader/plugins/ -
Restart KOReader (fully close and reopen the app)
-
Access the plugin: Go to ☰ → More tools → Fleeting Notes
For development or easy updates, create a symbolic link:
# On Kobo/Kindle (over SSH)
cd /mnt/onboard/.adds/koreader/plugins/
ln -s /path/to/development/fleeting-notes.koplugin
# On macOS/Linux
cd ~/.config/koreader/plugins/
ln -s ~/Projects/fleeting-notes.kopluginClone directly into the plugins directory:
cd /path/to/koreader/plugins/
git clone https://github.com/yourusername/fleeting-notes.koplugin.git- Enable SSH on your Kobo (search for "Kobo SSH enable")
- Connect to your Kobo:
ssh root@192.168.2.2(or similar IP) - Copy the plugin:
scp -r fleeting-notes.koplugin root@192.168.2.2:/mnt/onboard/.adds/koreader/plugins/
- Restart KOReader
- Install KOReader if not already installed
- Copy
fleeting-notes.koplugintokoreader/plugins/via USB - Eject and restart KOReader
- Using a file manager, navigate to your internal storage
- Go to
koreader/plugins/ - Copy
fleeting-notes.kopluginthere - Restart KOReader
- Navigate to your KOReader configuration directory (see table above)
- Copy
fleeting-notes.kopluginto theplugins/subdirectory - Restart KOReader
After restarting KOReader:
- Tap the ☰ menu
- Scroll to "More tools" section
- Look for "Fleeting Notes"
- Tap it to open the editor
Notes are stored in:
<KOReader data directory>/fleeting-notes/
Default data directory locations:
- Kobo:
/mnt/onboard/.adds/koreader/data/ - Kindle:
/mnt/us/koreader/data/ - Android:
<storage>/koreader/data/ - Desktop:
~/.config/koreader/data/(Linux/macOS) or%APPDATA%\koreader\data\(Windows)
- Open "Fleeting Notes" from the main menu (☰ → More tools)
- Type your note - the file is automatically created on your first keystroke
- Use toolbar buttons for Markdown formatting
- When done, choose:
- Done - Close the editor (note already saved)
- Save & New - Save this note and immediately create a new one
- Delete - Remove this note
Note: The note is continuously auto-saved as you type. You won't lose your work even if you accidentally close the editor.
Use Save & New to rapidly capture multiple thoughts:
- Type your first note
- Tap "Save & New"
- Immediately start typing your next note
- Repeat as needed
Perfect for capturing multiple fleeting notes while reading without leaving the editor.
| Button | Action | Example |
|---|---|---|
| B | Bold | **text** |
| I | Italic | *text* |
| </> | Code | `code` |
| H1, H2, H3 | Headings | # Text, ## Text, ### Text |
| •- | Bullet list | - item |
| 1. | Numbered list | 1. item |
| [L] | Link | [text](url) |
| [[]] | Wiki link | [[note]] |
Wiki Links: The [[]] button creates Obsidian-style links. Use these to link between your notes in Obsidian. For example, select "Character Analysis" and click [[]] to create [[Character Analysis]], which will link to a note named "Character Analysis" in your Obsidian vault.
Notes are saved with timestamp-based filenames:
2026-01-14-16-56-30.md
2026-01-14-17-45-00.md
Each file contains standard Markdown content.
Link the KOReader notes folder into your Obsidian vault:
# On macOS/Linux
ln -s ~/.config/koreader/data/fleeting-notes ~/Documents/ObsidianVault/FleetingNotes
# On Windows (mklink requires admin prompt)
mklink /D "C:\Path\To\ObsidianVault\FleetingNotes" "C:\Users\YourName\AppData\Local\koreader\data\fleeting-notes"Use rsync, git, or a cloud sync tool:
# Sync via rsync
rsync -av ~/.config/koreader/data/fleeting-notes/ ~/Documents/ObsidianVault/FleetingNotes/
# Or use a git repo
cd ~/.config/koreader/data/fleeting-notes
git init
git remote add origin https://github.com/yourusername/notes.gitIn Obsidian Settings → Files & Links → Attachment Folder Path:
- Set path to your KOReader
fleeting-notesdirectory
# Install dependencies
luarocks install busted
# Run all tests
busted
# Run specific test file
busted spec/file_storage_spec.lua
# Watch mode
busted --auto-watch
# Or use the convenience script
./run-tests.sh# Install luacheck
luarocks install luacheck
# Run linting
luacheck *.luafleeting-notes.koplugin/
├── main.lua # Plugin entry point
├── _meta.lua # Plugin metadata
├── file_storage.lua # File I/O operations
├── note_manager.lua # Note CRUD operations
├── markdown_formatter.lua # Markdown syntax helpers
├── markdown_editor.lua # Editor UI widget
├── spec/ # Test directory
│ ├── file_storage_spec.lua
│ ├── note_manager_spec.lua
│ ├── markdown_formatter_spec.lua
│ ├── markdown_editor_spec.lua
│ └── main_spec.lua
├── .busted # Test configuration
├── .luacheckrc # Linting configuration
├── run-tests.sh # Test runner script
├── CLAUDE.md # Development guidelines
└── README.md # This file
Plugin doesn't appear in menu:
- Verify the folder name ends with
.koplugin - Check that
main.luaand_meta.luaexist in the folder - Restart KOReader completely (close fully, not just suspend)
Notes not saving:
- Check that the data directory is writable
- Look for error messages in KOReader's crash.log
Toolbar buttons don't work:
- Make sure you've selected text before clicking (for formatting)
- Some buttons insert at cursor position if no text is selected
MIT License
Contributions welcome! Please read CLAUDE.md for development guidelines and TDD workflow.