kindle2notes/README.md

kindle2notes

kindle2notes is a small C++17 command-line utility that converts Amazon Kindle My Clippings.txt exports into structured notes.

Supported output formats:

• LaTeX (--type=latex)
• Markdown (--type=md)
• Org mode (--type=org)
• AsciiDoc (--type=adoc)

Highlights are grouped by book title while preserving the order in which books first appear in the input file.

Input format

Each Kindle clipping is expected to have the following structure:

Book Title
- Your Highlight on Location 123-125 | Added on ...

Highlighted text line 1
Highlighted text line 2
==========

The final clipping is processed even when the file does not end with the ========== separator. Incomplete clipping blocks are ignored.

Output formats

LaTeX

Books become sections, clipping metadata becomes subsections, and every highlight receives an empty notes subsection:

\section {Book Title}
  \subsection {- Your Highlight on Location 123-125 | Added on ...}
    Highlighted text line 1
    Highlighted text line 2
      \subsubsection{notes}

LaTeX special characters are escaped automatically.

Markdown

Books and clipping metadata become headings. Highlight text is emitted as a Markdown block quote, followed by an empty notes heading:

# Book Title

## - Your Highlight on Location 123-125 | Added on ...

> Highlighted text line 1
> Highlighted text line 2

### Notes

Empty lines inside highlights are preserved as > lines, and Markdown syntax characters are escaped automatically.

Org mode

Books and clipping metadata become Org headings. Highlight text is placed in a quote block followed by an empty notes heading:

* Book Title

** - Your Highlight on Location 123-125 | Added on ...

#+begin_quote
Highlighted text line 1
Highlighted text line 2
#+end_quote

*** Notes

AsciiDoc

Books and clipping metadata become section headings. Highlight text is placed in a quote block followed by an empty notes section:

== Book Title

=== - Your Highlight on Location 123-125 | Added on ...

[quote]
____
Highlighted text line 1
Highlighted text line 2
____

==== Notes

Architecture

Input parsing is implemented as a stage-driven pipeline with one handler for each stage: title, metadata, and body. Handlers are registered and created through the generic TypeFactory template, then cached for reuse while the input is read.

Output generation uses a common abstract Converter interface. Concrete converters are registered in another TypeFactory under their command-line type names. The selected converter is created at runtime and invoked through the common virtual save() method. Adding a new output format requires a new Converter subclass and a corresponding factory registration.

Build

The project has no Qt dependency. It requires a C++17 compiler and CMake 3.16 or newer.

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --parallel

The resulting executable is:

build/kindle2notes

Debian package

On Debian or a Debian-based distribution, install the package build tools and build the binary package with:

sudo apt install build-essential cmake dpkg-dev
dpkg-buildpackage --build=binary --no-sign

The .deb, .changes, and .buildinfo files are written to the parent directory. To create a Debian source package instead, run:

dpkg-buildpackage --build=source --no-sign

When the source is built from Git, CMake obtains the version from git describe. A build made exactly from a release tag reports only that tag (for example, 1.0). Later commits include their distance from the tag and the abbreviated commit hash (for example, 1.0-3-gabc1234). A modified working tree also receives the -dirty suffix.

Usage

Generate LaTeX:

./build/kindle2notes \
  --input "My Clippings.txt" \
  --output notes.tex \
  --type=latex

Generate Markdown:

./build/kindle2notes \
  --input "My Clippings.txt" \
  --output notes.md \
  --type=md

Generate Org mode:

./build/kindle2notes \
  --input "My Clippings.txt" \
  --output notes.org \
  --type=org

Generate AsciiDoc:

./build/kindle2notes \
  --input "My Clippings.txt" \
  --output notes.adoc \
  --type=adoc

Short options are also available:

./build/kindle2notes -i input.txt -o notes.md -t md

Show the version compiled into the executable:

./build/kindle2notes --version

Argument	Short form	Description
--input	-i	Path to the Kindle clippings file
--output	-o	Path to the generated file
--type	-t	Output format: latex, md, org, or adoc
--version	-v	Show the compiled version and exit
--help	-h	Show usage information

If an unsupported output type is requested, the program prints the list of available formats and exits without creating an output file.