Syncing Kobo Highlights to Markdown

Oct 16, 2026 · 4 min read
A woman holding a Kobo Libra Colour e-reader

kobo2md turns the highlights and notes on your Kobo into Markdown files, one file per highlight. It’s free, open source, and runs on Linux, macOS and Windows.

Why I Built It

I read a lot, and my Kobo fills up with highlights: the ideas I want to revisit and act on.

I keep my notes as plain-text Markdown, organised with Tiago Forte’s PARA method. Markdown files belong to me, open in any editor, and will still be readable decades from now, whether I open them in vi, vim or nvim.

Getting highlights from my Kobo into those notes meant copying them by hand after every book. It was tedious, and the more I read, the bigger the backlog grew. The ideas I cared about most were stuck on my e-reader instead of in my second brain (Tiago Forte’s term for a system that organises your ideas and information).

I couldn’t find an existing tool that did this the way I wanted, so I wrote one, built to fit that system:

  • One note per highlight, so each idea can be moved, linked and reused on its own.
  • Readable note names: <Book> - <first words of the highlight>.md, valid on Linux, macOS and Windows.
  • Authors as [[wiki-links]], so editors that support them link each highlight to a note about its author.
  • Your own tags, added with --tag (repeat it for several), so new highlights land where your system expects them.

I point it at my Inbox folder, so new highlights wait there until I sort them with PARA.

What You Get

Connect your Kobo and run one command:

$ kobo2md --output ~/notes/inbox
✓ /home/you/notes/inbox/Atomic Habits - You do not rise to the level of your goals. You fall to.md
1 note(s) from 1 book(s) on N418180000001.

Each highlight becomes an ordinary Markdown file, with YAML front matter that any editor or notes app can read:

---
title: "Atomic Habits"
author:
  - "[[James Clear]]"
type: note
highlighted: 2026-09-28
created: 2026-10-07
kobo_id: "6f1c…"
tags:
  - "kobo"
---
> You do not rise to the level of your goals. You fall to the level of your systems.

Design the system, not the goal.

The notes you type on your Kobo come along too, below the highlight, and type tells you which is which: highlight for a highlight alone, note when you added a note to it. highlighted is when you made the highlight, created when it was exported.

From there, they’re ordinary Markdown files: open them in your editor, link them from other notes, or move them into the right project or area.

How It Works

  • Each run exports only what you highlighted or changed since the last run, so you can run it after every reading session.
  • Each note records its highlight’s kobo_id, so a highlight already in your notes is never written again, even if you export everything with --all or have the same book on two Kobos. kobo2md looks in the output folder by default; since I move highlights out of my Inbox, I point it at my whole notes folder with --notes ~/notes. --notes replaces the output folder as the place to look, so keep the output folder inside it, or pass it as a second --notes. Hidden folders such as .trash are skipped, so a highlight whose note you deleted to the trash can be exported again.
  • Every connected Kobo is found automatically and recognised by its serial number, so each keeps track of its own new highlights.
  • kobo2md copies the Kobo’s database to a temporary folder and reads the copy. It never writes to your e-reader.

How to Install

kobo2md is a single Python script. It needs Python 3.9 or newer and nothing else. Clone it and link it into your PATH:

git clone https://codeberg.org/mebibite/kobo2md.git && cd kobo2md
mkdir -p ~/.local/bin
ln -sf "$PWD/kobo2md.py" ~/.local/bin/kobo2md

On Windows, skip the link and run py path\to\kobo2md.py instead.

To preview what would be exported without writing anything, add --dry-run. To skip --output and --notes, set them once with export KOBO2MD_OUTPUT=~/notes/inbox and export KOBO2MD_NOTES=~/notes.

To export what changed after a given date instead of since the last run, use --since 2026-09-01 (in UTC). Highlights already in your notes are still skipped.

No Kobo at hand? Point kobo2md at a copy of its database, for example from a backup:

kobo2md --db ~/backup/KoboReader.sqlite --device my-libra --output ~/notes/inbox

--device names the copy, so kobo2md remembers what it already exported from it.

Run It Automatically

Rather than running the command yourself, you can have it run whenever the Kobo is mounted, so highlights reach your notes as soon as you plug it in. On Linux with systemd and an automounter such as udiskie, save this as ~/.config/systemd/user/kobo2md.service, changing the folders:

[Unit]
Description=Export Kobo highlights to Markdown
After=run-media-%u-KOBOeReader.mount
BindsTo=run-media-%u-KOBOeReader.mount

[Service]
Type=oneshot
ExecStart=%h/.local/bin/kobo2md --output "%h/notes/inbox" --notes "%h/notes"

[Install]
WantedBy=run-media-%u-KOBOeReader.mount

Then enable it:

systemctl --user daemon-reload
systemctl --user enable kobo2md.service

systemd doesn’t read your shell’s KOBO2MD_* variables, so the service passes --output and --notes itself. If your Kobo is mounted somewhere else, the README explains how to find the unit name.

Limitations

If you edit a highlight or note on your Kobo after it was exported, its Markdown note isn’t updated. Edit the note itself, or delete it and run kobo2md with --all to export it again.

kobo2md is open source, so anyone is welcome to use it or contribute. Every option is documented in the README.