urlref: website bookmarking for handwritten notes

I’ve been moving more and more of my notetaking and task management systems to analog, hand-written systems, using my beloved fountain pens, but this presents a problem: how does a terminally-online, technically-minded young adult (me) reference things I see on the web in my notes?

To accomplish this, I built urlref, a lightweight tool purpose-built for the task.

balancing simplicity and ease

To begin, let’s draw a distinction in terms that are often confused: simplicity measures how much expertise or mental effort it takes to understand and implement a process, while ease refers to the actual level of difficulty in using that process.

A process can be simple to understand but difficult to use; for example, the simplest solution to my problem would be to simply copy down URLs verbatim into my notes, but this is not an easy solution, as URLs are long, complicated, and easy to mess up.

For my solution, I traded simplicity for ease of use; in this system, I can easily generate a 3-5 character code representing any webpage, then write it down in place of the URL. Later, I can easily reverse the process in my web browser and get back to the original page. As a trade-off, the design took a lot of intentionality and it was moderately complex to set up.

the conceptual explanation

My system is highly inspired by URL shorteners, which have a very similar goal. That said, I didn’t want to use a commercially-available URL shortener, as they have severe privacy issues, are difficult to back up, and leave all of my links dependent on some third party which could go down or change their terms at any time.

I could host my own URL shortener, but the actual process of copying a URL into a website that shortens it lowers the ease of use of the system, despite the result being easier to write down.

My actual chosen simply uses a short code, like is at the end of a URL shortener’s output, but without any website involved. Everything is stored locally on my laptop, with no external dependencies whatsoever. Even the code of urlref is only 59 lines long.

Here’s how it works:

I find a webpage I want to reference in my notes or journal.
I hit the “a” and “r” keys in sequence in my web browser (Qutebrowser is a modal browser with keybindings similar to vi).
I receive a notification with a short code (in sequential order, so they stay short for a long time), which I write down in my notes in place of the URL. An example code might be A06, which I write as @A06 to make it clear that it’s a link/reference.
When I want to re-open that webpage, I simply type r A06 into my browser’s URL bar and hit enter. The codes are case-insensitive and 0 and O are interchangeable, as are 1, l, and I. My browser automatically takes me to the URL I originally was at.

It’s a cool and easy-to-use system, but how does it work under the hood?

the technical explanation

For this project, I decided to use nim, a straightforward compiled language I was confident would create a lightweight resulting binary with no dependencies.

When fed a URL, urlref simply adds that URL to a sqlite database, stored locally on my device in an easy-to-back-up location. It then returns the sequential ID of the entry encoded in Crockford Base32, a system for creating convenient human-usable codes. As mentioned above, easily-confused characters are interchangeable. It also leaves out letters that might make your codes include swear words (which I appreciate, personally).

urlref can also serve a lightweight HTTP server which redirects requests to /<id> to those IDs’ URLs. I set up my computer to run this server in the background when I’m logged in.

Now comes the clever part: integration with my browser.

Qutebrowser makes it easy to script keybindings, so I made a short script to run when I type “ar” (short for “add reference”) which passes the current URL to urlref and gives me a notification with the short code to write in my notes. This part would need to be implemented differently in different browsers; a relatively-simple browser extension could probably accomplish it, especially if I added an API path to the urlref HTTP server to add references via API requests instead of the CLI.

Using the codes, though, can easily be set up in any browser worth its salt. I simply set up a custom search engine. This was the fundamental realization that inspired the project: with a custom search engine in the browser, it can use custom behavior to handle urlref IDs, without caring about the ease of typing the underlying URL. When I type r a03 into the URL bar (“r” being the trigger word telling the browser to use the custom search engine) gets interpreted by my browser as https://localhost:9873/a03, which is urlref’s local HTTP server.

urlref then simply looks up the code in the database and sends a redirect to my browser. Since it all happens on my own computer, it happens extremely fast and there’s no noticeable overhead. Additionally, since it’s all on my computer in an ordinary file, it’s easy to back up my bookmarks to ensure I never lose them.

conclusion

I’ve been using this system for five months now and haven’t had to edit urlref’s code a single time. It just works, which is the best kind of software. It’s simple and straightforward, with no sign of scope creep or external dependencies. Best, it should keep working indefinitely, and even if something makes my code impossible to run in the future, sqlite databases are ubiquitous, so it should be simple to recover the underlying URLs that I bookmarked even then.

Of course, I built this system for my own use, so it’s highly opinionated. You’ll likely need to do some of your own work to integrate it onto your own computer, especially if you’re not using Qutebrowser.

That said, if this system interests you, I’d love to hear your thoughts! If you have ideas to improve it, I’d love to hear those as well. I’d also be willing to help you adapt this to your own needs or figure out how to set up the project.

For any of those purposes, my email address is below; I look forward to your messages.