What is this about?
A CLI tool that exports highlights from Readdeck into markdown files.
I got tired of manually archiving the good nuggets of information from what I read online. So I started using a read-later service. Then I got tired of manually copy-pasting my highlights into my notes. So I streamlined the process!
If you’re like me and have your own knowledge base or digital garden, you probably want or have a streamlined process to gather your source materials. Whether it’s for referencing or just to capturing the knowledge. However, constantly copy-pasting this data into your notes can be quite tedious.
There are many possible solutions for this, from obsidian clipper, to paid options like read wise, and of course many others that I’ve missed.
Lets dive into my process, and the CLI tool that I built to make it a bit smoother.
No time to read some random article, check out the project.
Why readdeck
When I was on my self-hosting spree using nix (since a successful infrastructure is one you forget about and nix is a self documenting system), I chose readdeck as my bookmarking / archiving service. Other options like Wallabag, Shiori and various other self-hosted services came close but usually fell short on some small requirement. As a result I opted for readdeck, but I’m sure there is an alternative for me.
What I want from a read-later service
- Be FOSS
- Be able to highlight
- Be able to tag and quickly capture pages
- Have a decent UI (Readdeck is stretching this 😭)
- Don’t be too complicated to host.
Streamlining my flow
Since I already use glance as my default homepage, it quickly shows me what I saved in my read-later application, it felt natural to start reading and nudge myself to consume media by my choices.
QUOTE
Reading by choice, not by algorithm.
For the people curious, this is how my glance-widget looks like
Now I just needed to convert my highlights to markdown files.
Requirements
Be atomic
I don’t want this to break when you run the command again and again. Or on another computer. This means we can also not store any information on readdeck itself.
Not be destructive
You export a highlight, you format it a bit more to your liking or add some other notes to it. It would suck that when you re-run this command it all goes to the trash.
Be informative
When the information is available, I want to know where all this came from. A link to the archived and live URL, author name, article name, publication date and all other meta-information we can gather!
Be additive
You highlighted something extra on something that was already exported, lets add it non destructively to the page.
Colour matters
Readdeck offers it, lets use it. There is a difference if you highlight with red, green, yellow or teal!
Enter highlight-exporter
My highly opinionated CLI tool, written in Go: highlight-exporter will fix this for us.
It will convert, for example, this article (see screenshot of a paragraph) into the markdown file you can see below.
---
id: 1744667075-structured-logging
aliases:
- Structured Logging highlights
tags:
- highlights
- zettelkasten
- fleeting-note
authors:
- sematext
created: 2025-04-14 21:39
media: Structured Logging
media-published: ""
media-type: article
media-url: https://sematext.com/glossary/structured-logging/
readdeck-hash: C38CAQL_gAABDAAA_gEB_4AACxY0MmU3NlNkaDNic2dnRFEySHpEdkFjFjZDeW9CbzlMaTM1UGtVMjU2VFhORXAWOVJIUzlXeXBkUkVjVENleEN5Z0hyaRZNazJxM1dDdFh4N1N6V2lwYUg4cW9LFm9DcGpUWWpXeEMyUFptYUpDc1FkelEWWkhTN1pqSnNxRVNqVlpxV1VxdGVyVxZRZmI3N1lOUEVFZXYyeWF1a01xRlc4FjV6WFdmVGl3S3JzMjRwNlNUZ0ZpOHoWZDNvVFFQbUdocFJ0dkI1UTJHR3g3TBZCQmhmZTR1MnJlYUZacHhlYXBOZFd1FlJBUUV4b0xpc1d5cTZQS0ZTakVvM2s=
readdeck-id: WFabHiaYjNHmkxazSaQQRe
readdeck-url: https://readlater.deraedt.dev/bookmarks/WFabHiaYjNHmkxazSaQQRe
---
# Structured Logging highlights
## Key takeaways
Structured logging is the practice of logging application and server errors or access events in a well-structured and consistent format that can be easily read, searched, and analyzed by any application or an interested individual.
Facilitate easy debugging of production incidents,
Having said that, structured logging has its own set of disadvantages. The major disadvantages of structured logs are the increased size of an event and increased system requirements.
## General highlights
The most common structured logging format is JSON
Unstructured logs are messages in plain text containing information in a linear string
it can be challenging to query and fetch relevant information without parsing the linear string.
You can also easily drill down to individual parameters and aggregated values,
In contrast to unstructured and structured logs, semi-structured logs contain both objects and strings. They are easily understood by humans and machines alike. However, their formats are not standardized, making them less convenient than standardized logs
Structured logs can have the same format even if they are produced by different sources, which improves the readability and maintainability of logs
Since structured logging can be parsed quickly, organizations can use them for analytics and business intelligence purposes.
Modern organizations produce huge amounts of log data. You can make sense of them only by structuring the logs with the help of a proper log monitoring solution.
## References
[Structured Logging](https://sematext.com/glossary/structured-logging/)
[Archived article](https://readlater.deraedt.dev/bookmarks/WFabHiaYjNHmkxazSaQQRe)Lets go over it.
Zoom in
Lets zoom in on some frontmatter properties!
readdeck-hash: C38CAQL_gAABDAAA_gEB_4AACxY0MmU3NlNkaDNic2dnRFEySHpEdkFjFjZDeW9CbzlMaTM1UGtVMjU2VFhORXAWOVJIUzlXeXBkUkVjVENleEN5Z0hyaRZNazJxM1dDdFh4N1N6V2lwYUg4cW9LFm9DcGpUWWpXeEMyUFptYUpDc1FkelEWWkhTN1pqSnNxRVNqVlpxV1VxdGVyVxZRZmI3N1lOUEVFZXYyeWF1a01xRlc4FjV6WFdmVGl3S3JzMjRwNlNUZ0ZpOHoWZDNvVFFQbUdocFJ0dkI1UTJHR3g3TBZCQmhmZTR1MnJlYUZacHhlYXBOZFd1FlJBUUV4b0xpc1d5cTZQS0ZTakVvM2s=
readdeck-id: WFabHiaYjNHmkxazSaQQReI think most of the front matter explains itself, but two stands out, why do we need them, what are they and what do they want?
readdeck-hash: This hash is used to calculate which highlights are exported onto this document. This means, if you remove or edit it, the tool will once again re-calculate the hash and add all missing highlights. It is also used to know which if there are new highlights for this document.
The readdeck-id is also worth mentioning, this is the identifier that the tool uses to scan for all exported documents inside the output directory. If it cannot find the id in the frontmatter, a new one will be generated, if it does, it will look at the hash.
Highlights
We can see some distinct groups, we can see the Key takeaways and General highlights. The default colour to header is as follows:
| Colour | Header |
|---|---|
| Red | Thought-provoking insights |
| Green | Key takeaways |
| Yellow | General highlights |
| Teal | Important references |
Give me the deeds
Never forget the help text, it gives us important clues how to use this tool.
@thieu ➜ highlight-exporter --help
Readdeck Highlight Exporter is a CLI tool that exports highlights
from Readdeck (a read-it-later service) to your Zettelkasten note-taking system.
The tool reads from Readdeck without modifying it and tracks exported
highlights through the generated notes themselves, ensuring idempotent operation.
To get started, run the 'config' command to set up your configuration:
highlight-exporter config --help
Usage:
highlight-exporter [flags]
highlight-exporter [command]
Available Commands:
completion Generate the autocompletion script for the specified shell
config Configure readdeck-highlight-exporter
export Export highlights from Readdeck to Zettelkasten notes
help Help about any command
Flags:
--config string config file (default is $XDG_CONFIG_HOME/readdeck-exporter/settings.yaml)
-h, --help help for highlight-exporter
-v, --version Print version information and exit
Use "highlight-exporter [command] --help" for more information about a command.
Lets look at my configuration using the config command, if you want to set up yours take a look at the highligh-exporter config --help output.
@thieu ➜ highlight-exporter config
Current Configuration:
======================
Readdeck:
Base URL: https://readlater.deraedt.dev
Token: eyJh*...*7lBg
Bookmarks per page: 100 (default)
Request timeout: 30s (default)
Export:
Fleeting path: /home/thieu/notes/Obsidian/fleeting
Configuration file: /home/thieu/.config/readdeck-exporter/settings.yaml
Heads up: The API token is stored as plain text. Make sure you only give it read access to your instance!
Once configured, you can export the highlights, lets take a look.
@thieu ➜ highlight-exporter export
Saving to: /home/thieu/notes/Obsidian/fleeting
Starting export from Readdeck...
Requesting page 1, offset: 0
Requesting page 2, offset: 100
Export Summary
===================================
Processed 17 notes (1 created, 0 updated, 16 unchanged)
Total highlights: 121 (+1 new added)
Time: 540ms
✅ Export completed successfully!
That’s it! Feel free to add some things to your highlights, I for one like to add block references when I use them ^60ccb1, and they will not be removed!
Try it out yourself
Feel free to try out the project, and give feedback. It is highly opinionated though, but I might be able to make some abstractions when the needs arises.
Currently it’s only built using a nix flake. If you are on nix, no sweat, just import the flake and add it to your packages. If you’re not on nix (boo!) you can build the go application yourself, if you don’t want or know how to, put up an issue and I’ll create a release on Github for you!
ps You can also run it using nix run github:MathieuDR/readdeck-highlight-exporter, but I’m not sure how that will behave.