---
publish: true
title: urlref
created: 2026-01-19T18:15:38.889-07:00
modified: 2026-01-19T18:40:10.504-07:00
tags:
  - web
  - note_taking
cssclasses: ""
---

As an avid user of pen and paper for note taking I have had endless trouble figuring out how to store url's without having to write them out in full. I seem to have found a solution to this issue with [urlref](https://benjaminhollon.com/musings/urlref/) from the fantastic [Benjamin Hollon](https://polymaths.social/@amin). I did have a little bit of fun setting up for myself though so I am documenting here in case it is helpful to anyone, including future me.
## Installation
### Install Nim
**Arch Linux:**
```bash
sudo pacman -S nim nimble
```
**Other distributions:**
See https://nim-lang.org/install.html
### Build
```bash
cd urlref
nimble build
```
### Install system-wide (optional)
```bash
nimble install
```
This installs the binary to `~/.nimble/bin/`. Ensure it's in your PATH:
```bash
export PATH="$HOME/.nimble/bin:$PATH"
```
## Usage
### Create a short reference
```bash
urlref create "https://example.com/some/long/url"
# Output: ABC
```
### Start the redirect server
```bash
urlref
```
The server runs on port 9873. Visiting `http://localhost:9873/ABC` redirects to the original URL.
## Examples
### systemd service
```bash
[Unit]
Description=URL Reference Redirect Server
After=network.target

[Service]
ExecStart=%h/.nimble/bin/urlref
Restart=on-failure
RestartSec=5

[Install]
WantedBy=default.target
```
### qutebrowser Integration
This [[qutebrowser]] integration works for me, you are on your own for other browsers!
#### Userscript
Should live at `~/.local/share/qutebrowser/userscripts`
```bash
#!/bin/bash
# Qutebrowser userscript to shorten the current URL using urlref

shortcode=$(~/.nimble/bin/urlref create "$QUTE_URL")

if [ -n "$shortcode" ]; then
    echo "message-info 'Shortcode: $shortcode'" >> "$QUTE_FIFO"
    echo "yank inline $shortcode" >> "$QUTE_FIFO"
else
    echo "message-error 'Failed to create shortcode'" >> "$QUTE_FIFO"
fi
```

Bind it to a key
```python
config.bind('ar', 'spawn --userscript urlref-shorten')
```

Add a custom search engine
```python
c.url.searchengines['r'] = 'http://localhost:9873/{}'
```
