A Python tool to convert Kindle's "My Clippings.txt" file into organized Markdown files, creating separate documents for each book with optional WebDAV upload functionality.

Features

Parse Kindle clippings: Extract highlights and notes from "My Clippings.txt"
Organize by book: Create separate Markdown files for each book
Page references: Include page numbers or positions with each citation
Safe filenames: Automatically sanitize book titles for filesystem compatibility
WebDAV upload: Optional upload to cloud storage via WebDAV
Batch operations: Clear and update entire collections

Installation

Clone this repository:

git clone <repository-url>
cd KindleClippingsParser

Install Python dependencies:
```
pip install requests
```

Usage

Basic Usage

Convert your Kindle clippings to Markdown files:

python main.py "My Clippings.txt"

Advanced Options

# Specify custom output directory
python main.py "My Clippings.txt" -d custom_output_folder

# Upload to WebDAV server
python main.py "My Clippings.txt" --upload

# Upload clearing existing files
python main.py "My Clippings.txt" --upload --clear

# Auto parse with a Kindle attached
python main.py --direct

WebDAV Configuration

For WebDAV uploads, create a config.json file:

{
  "webdav": {
    "base_url": "https://your-webdav-server.com/path",
    "username": "your-username",
    "password": "your-password"
  }
}

Alternatively, use environment variables:

export WEBDAV_BASE_URL="https://your-webdav-server.com/path"
export WEBDAV_USERNAME="your-username"
export WEBDAV_PASSWORD="your-password"

Output Format

Each book generates a Markdown file with citations formatted as blockquotes:

> "Your highlighted text here" (p. 42)

> "Another highlight from the same book" (pos. 1234)

Requirements

Python 3.6+
requests library for WebDAV functionality

To-Do

Auto-parse Kindle clippings directly from Kindle device

License

This project is licensed under the MIT License - see the LICENSE file for details.

v1.2

New in this release:

Advanced merging of local and remote citations with character-by-character resolution
Conflict resolution: keep the remote version for minor changes and the local version for major changes
Preservation of empty lines and automatic removal of unwanted backslashes around [[…]]
Handling of URL-encoded filenames for correct matching
New CLI flag --clear to explicitly delete remote files before uploading