📚 Kindle Highlights — VS Code Sync & Note Manager Hero Banner

📚 Kindle Highlights — VS Code Sync & Note Manager

Sync Kindle Highlights from My Clippings.txt into Workspace Markdown Files with Customizable Nunjucks Templates. No login required.

Overview • Features • My Clippings Guide • Code Architecture • System Flow • Structure • Quick Start • License

📌 Overview

A feature-rich VS Code extension (LoNebula9.kindle-highlights) inspired by the Obsidian Kindle Plugin. It parses your Kindle device's My Clippings.txt file — no Amazon login needed — extracts highlights, annotations, and bookmarks, and formats them into structured Markdown files using customizable Nunjucks templates.

✨ Features (Key Outcomes & Capabilities)

Icon	Feature	Outcome & Real Proof
📥	My Clippings.txt Parser	Extracts highlights, notes, locations, and timestamps from any Kindle device file
📄	Custom Nunjucks Templates	Full control over Markdown structure, frontmatter metadata, and citation layout
🔄	Smart Idempotent Merge	Appends new highlights without erasing your personal annotations or edits
🎨	Interactive Webview UI	Browse books and highlights with dedicated search and filter panels

🔬 Code Architecture & Implementation

🔬 Code Implementation (`src/`)

clippingsParser.ts: Regular expression parser for multilingual Kindle clippings format (========== delimiter, Title (Author), Location/Page, Timestamp, Highlight Text).
fileManager.ts: Handles idempotent Markdown file generation, creating one file per book with YAML frontmatter and merging new highlights without overwriting user notes.
templateEditorPanel.ts: Interactive Webview panel for customizing Nunjucks templates ({{title}}, {{author}}, {% for highlight in highlights %}).
highlightsPanel.ts: Visual book shelf and highlight explorer inside VS Code.

📊 System Flow

graph TD
  Clippings[📖 My Clippings.txt] --> Parser[⚙️ ClippingsParser Engine]
  Parser --> Data[📚 Structured BookHighlight Object]
  Data --> Template[📝 Nunjucks Template Formatter]
  Template --> FileMgr[💾 FileManager: Smart Markdown Merge]
  FileMgr --> Notes[(📁 Workspace Markdown Notes)]
  Data --> Webview[💻 Highlights Explorer Webview Panel]

  classDef primary fill:#f97316,stroke:#ea580c,stroke-width:2px,color:#fff;
  classDef accent fill:#3b82f6,stroke:#2563eb,stroke-width:2px,color:#fff;
  class Parser,Template primary;
  class Notes,Webview accent;

📁 Project Structure

kindle-highlights/
├── 📁 assets/                 # Marketplace PNG hero banners
│   └── 🎨 hero.png
├── 📁 src/
│   ├── 📄 clippingsParser.ts  # Kindle clippings regex parsing engine
│   ├── 📄 fileManager.ts      # Markdown generation & smart merge
│   ├── 📄 templateEditorPanel.ts # Nunjucks template editor webview
│   └── 📄 extension.ts        # Main commands & lifecycle
├── 📄 package.json            # Extension manifest
└── 📄 README.md               # Documentation

📥 How to Get My Clippings.txt (Step by Step)

No Amazon login is needed. All data comes from a text file stored on your Kindle device.

Step 1 — Connect your Kindle via USB

Connect your Kindle to your computer with a USB cable.
If your Kindle asks, tap Allow / Transfer files (or enter your device passcode).
Wait until a new removable drive named Kindle appears on your computer.

Step 2 — Find the file

Open the Kindle drive and go to the documents folder. The file you want is:

Kindle/documents/My Clippings.txt

OS-specific examples (the drive letter / mount point varies):

OS	Typical path
Windows	`E:\documents\My Clippings.txt` (drive letter `E:`, `F:`… varies — look for the Kindle drive)
macOS	`/Volumes/Kindle/documents/My Clippings.txt`
Linux	`/media/<username>/Kindle/documents/My Clippings.txt`

Can't find it? Open the Kindle drive in Explorer / Finder and use search for My Clippings.

Step 3 — Copy it to your computer (recommended)

The file stays on your Kindle, but copying it to your PC makes future syncs one-click:

Documents/Kindle/My Clippings.txt

Suggested locations:

OS	Suggested copy destination
Windows	`C:\Users\<you>\Documents\Kindle\My Clippings.txt`
macOS	`~/Documents/Kindle/My Clippings.txt`
Linux	`~/Documents/Kindle/My Clippings.txt`

Step 4 — Sync in VS Code

Open the VS Code workspace where you want your notes.
Run Kindle Highlights: Sync from My Clippings.txt from the Command Palette (Ctrl+Shift+P / Cmd+Shift+P).
In the file picker, select the My Clippings.txt you copied in Step 3 (or pick it directly on the Kindle drive).
Done — one Markdown file is created per book in your configured highlights folder. The file path is remembered, so next time you just run the command again (no picker).

Good to know

Append-only file: Kindle only ever appends to My Clippings.txt, so re-syncing is safe — new highlights are merged, your own edits are preserved.
Device-only books: only books/periodicals actually opened on that Kindle device appear. Books you read solely in the phone/tablet app are not in this file.
Japanese / multilingual: the parser handles BOM, CRLF, and Japanese/Chinese metadata lines (メモ, ハイライト, しおり, 位置, ページ…).
Refresh: after highlighting on your Kindle, reconnect via USB and copy the file over the old one, then sync again.

Troubleshooting

Symptom	Fix
Kindle drive doesn't appear	Try another USB cable/port (charge-only cables don't work); unlock the Kindle screen
`My Clippings.txt` is missing	Open any book on the Kindle and add one highlight — the file is created on first highlight
Sync says 0 books	Make sure you selected the real file, not an empty copy; check it opens in a text editor and contains `==========` separators
Wrong books synced	You picked an old copy — re-copy from the Kindle drive over it and sync again

🚀 Quick Start

# Install from Marketplace:
ext install LoNebula9.kindle-highlights

# Or build locally:
npm install
npm run compile

Released under the MIT License. Crafted with precision by LoNebula

Kindle Highlights

LoNebula9