Jonas Hietala

Planning my Kubernetes homelab

2026-05-05T08:16:39+00:00

The Kubernetes iceberg.

If I’d have to describe my homelab setup via analogy I guess it would be similar to me on a unicycle carrying plates with both of my hands, or maybe a leaking barrel with water that I try to patch up with silver tape.

I’ve also been Kubernetes-curious so I decided to completely redesign my homelab, centered around Kubernetes. It was a bit painful but at least it fulfilled my need for procrastination very well.

Overarching goals

I’ve got three goals with the setup:

Declarative, reproducible, and automated

The big goal is to have everything declarative in a single git repository and to easily be able to bootstrap from nothing to a fully working setup.

I want to use Infrastructure as Code to create the Kubernetes cluster and GitOps to populate it with all my services automatically from the repo. It should be really easy to make a change; I want to move away from having to ssh into the correct repo and manually do stuff.
Backups, backups, backups

While a proper GitOps setup means that infrastructure and configuration files are inherently backed up, a proper backup setup is still crucial.

Ask me how I know.
No, please don’t.

I haven’t had a proper (as in working) backup solution for years and this time I should have it from the start.
Documentation

What if I could document my setup, so future me has a chance to understand what’s happening? Writing documentation is boring, so I’ll write some blog posts instead.

I’m a bit skeptical that I can fulfill all three goals, but if I manage 2/3 or even 1/3 it’s still a big win compared to my old setup.

Kubernetes, too complicated?

It’s a fair question and the most common critique towards Kubernetes is that’s just too complicated (especially for a homelab). Discussions online are filled with comments such as:

Kubernetes has to be most complex software I’ve ever tried to learn. I eventually gave up and decided to stick with simple single machine docker-compose deployments.

trinovantes

“Let’s use Kubernetes!”
Now you have 8 problems

Itamar Turner-Trauring

So why would I choose Kubernetes?

Because, for whatever reason, Kubernetes is very popular and for every comment complaining about complexity you have comments extolling it’s virtues:

I was skeptical about Kubernetes but I now understand why it’s popular. The alternatives are all based on kludgy shell/Python scripts or proprietary cloud products.

zelly

Kubernetes is the biggest quality-of-life improvement I’ve experienced in my career

anchochilis

Having experienced the single machine docker-compose deployments, kludgy shell scripts, and proprietary cloud products; I think I need to use Kubernetes myself to be able to form an opinion on it.

And in some ways, isn’t experimentation a core part homelabbing?

Tech stack

There are many valid tech choices for this kind of setup and many of them are reasonable. I don’t know if my choices are reasonable—most were chosen because they sounded cool, others because I just picked one.

Here’s list of some of the choices I made, which we’ll setup in this series:

Talos Linux for Kubernetes nodes.

The coolest way to run Kubernetes. Lightweight and secure, what’s not to like?
Terraform to provision VMs on Proxmox and to initialize Talos Linux.
Cilium for proxying, CNI, load balancer, and Gateway API provider.

I opted for Cilium as it’s one dependency replacing several alternatives (such as kube-proxy, Metallb, and Traefik, which I was leaning towards at first). Gateway API is the new thing you “should” use instead of ingress, and I wanted to try it out.
ArgoCD for GitOps.

If it was purely for myself FluxCD might have been the better, simpler, choice but we might use ArgoCD at work and I don’t want to deal with two separate systems at the moment.
Renovate to keep dependencies up-to-date.
CloudNativePG for Postgres on Kubernetes.

I’ll also setup timescaledb, although we won’t use it in this series. It’s just to prepare for the future migration of long-term statistics from Home Assistant.
Longhorn on NVMEs for persistent storage.

Data is backed up using VolSync and Restic.
Sanoid, Syncoid and Kopia for backup archive management.

Backups are snapshotted and stored in ZFS, which are also encrypted and shipped off-site to Backblaze for storage in the cloud. Backups from Longhorn and Postgres arrives to ZFS via Garage, a self-hosted S3 service.
Authentik as an identity provider and single-sign-on platform.

It’s nice to not have to login manually everywhere.

Huh. Displayed like this it looks like a lot, but fear not! It’ll be worth it in the end.

In the next part we’ll start by creating VMs and getting a Kubernetes cluster up and running.

From GitHub to Codeberg/Forgejo

2026-05-04T18:29:32+00:00

Respect your users and their confidence in you, “Microsoft” GitHub.

Ethkuil, Updates to your GitHub Feed #65343

After years of waffling around I finally bit the bullet and migrated away from GitHub onto Codeberg and a private Forgejo instance. If Codeberg is good enough for Gentoo then it’s good enough for me.

What’s the problem with GitHub?

One part of my GitHub aversion is me being anti the big American tech corporations for ideological reasons. I’d like to reduce my usage and dependence of Google/Facebook/Apple/Microsoft/Amazon etc where I can and moving away from GitHub fits that goal nicely.

The other reason is GitHub’s enshittification. GitHub has been slow and slightly buggy for years and it’s not getting better. They push out badly planned features while shipping this kind of code in GitHub actions runner:

#!/bin/bash

SECONDS=0
while [[ $SECONDS != $1 ]]; do
    :
done

(This apparently broke Zig and caused them to leave for Codeberg.)

You may not like it but this is what peak vibe coding looks like

mawkler

I know it’s a snarky comment, but with a CEO that says “embrace AI or get out” then it’s hard to resist.

There’s empirical data to back up GitHub’s unreliability; just check out these uptime logs (taken 2026-04-27 from third party sites since the official status page predictably lies):

Screenshot from https://mrshu.github.io/github-statuses/

Screenshot from https://damrnelson.github.io/github-historical-uptime/

They don’t call it “Microslop” for nothing.

Self-hosted + managed

Codeberg is based on Forgejo, which is great to self-host. I’ve had it running a few weeks when I’ve been playing with my homelab and it feels exceptionally fast. The web UI is super responsive and I frequently have to double-check that I pushed as it finished so quickly.

I would love to have the speed and privacy for all my repositories but I’ve got some that I want to be public (the source for this site for example). I considered a few different setups:

Sync back changes to GitHub via Forgejo’s built-in GitHub sync?

(Keeping GitHub active would defeat the point a little though.)
Sync changes from my Forgejo instance to Codeberg?

(Maybe annoying to manage multiple repos?)
Only use Codeberg?

(I’d lose speed and privacy for my private repos.)
Expose my Forgejo instance running in my homelab?

(The internet is a scary place.)
Setup a public Forgejo on my Hetzner VPS?

(I’d still have to protect it and manage traffic.)

In the end I decided to use Codeberg as for my public-facing repositories and Forgejo as my main interface (for both public and private repos).

Some of my public repos are close to read-only (this site’s source for instance) so I’ve setup a mirror where Forgejo will push changes to Codeberg automatically. However, it’s weird to also pull changes from Codeberg to Forgejo. I guess I could setup a script to do it, but pull requests from others are rare enough that I can do it manually. Other repos (such as tree-sitter-djot) are left alone as they’re more collaborative in nature and I can’t be bothered to keep two sources in sync.

Is it good?

Yes, both Codeberg and Forgejo are very good. They are snappy and speedy and there are no features I miss from either GitHub or GitLab (and plenty I’m glad to avoid—getting AI shoved into every crevice for instance).
(Yes, I used an em-dash on purpose.)

At the moment Codeberg is admittedly having periods with pretty bad performance issues. This is because they’ve been under a DDOS attack for quite some time, which has been frustrating.

The migration

The migration wasn’t difficult, just a bit repetitive.

For private repositories I just deleted them from GitHub and pushed them to Forgejo.

Public repositories had a few more steps:

Push them to Forgejo
Push them to Codeberg
Add a header redirecting to Codeberg similar to this:

This repository has moved to https://codeberg.org/treeman/jonashietala.

This GitHub copy is a frozen archive. New commits, issues, and pull requests should go to Codeberg.
Archive them on GitHub

A work week one bag travel

2026-03-31T05:07:39+00:00

Life begins at the end of your comfort zone.

Neale Donald Walsch

I’m lucky that I have a job where I can work remotely as it allows me to live in a small community where there are no tech jobs anywhere close. It does require me to travel a few weeks per year to the office but I don’t mind that much as I appreciate minor dozes of socializing occasionally.

I recently spent five nights on a trip with only a single backpack and it was a surprisingly great experience.

How I used to travel

I’ve previously used these two bags for my trips.

I’ve had these work trips for years and I didn’t put too much thought into how to travel. Like most people I simply filled a suitcase that I checked in together with a backpack that I brought on the airplane.

I didn’t quite know how much to pack so I always packed a little more than I needed. For example, if I’m away 5 nights then I brought 7 pairs of underwear (if disaster strikes twice). When I returned I always had a bunch of unused clothes, but that felt better than having to little.

Because I had so much space I could bring a lot of things; my own pillow, a handful of books, gigantic boardgames, and I still had space left to bring back lots of gifts.

What bags?

I’ve had two backpacks that I used to travel with:

Datsusaru Battlepack Core

It’s a really sturdy backpack that’s great to bring to BJJ training, but it’s very heavy and it’s not ideal as a traveling bag.
M-Tac Backpack Urban Line

I bought this bag recently but I wasn’t too impressed. It was too small for a traveling bag and the zipper broke after just a few trips.

The zipper breaking made me go online and research new traveling backpacks, which gave me the idea to try out one bag travel.

I’ve had a few suitcases that have broken down but I can’t remember the brand of. Most recently I’ve been using the Samsonite Essens 69cm that have held out great so far.

One bag travel

I’ve been spending five nights away 4–5 times a year on business travels. It’s not a crazy amount but also not negligible, so I figured it’s worth trying to optimize them a bit.

Enter one bag travel.

While I was reasonably comfortable during my travels there’s a few things that intrigued me about one bag travel:

I wouldn’t have to roll around a big suitcase.
The trip would be more streamlined without having to check-in and wait for the luggage during flights.
I wouldn’t have to worry about lost luggage (although to be fair, so far I haven’t had that happen to me).
No more trying to find space for my suitcase on the train, or worrying that I won’t see if someone decides to grab it and walk off the train.

In short, the actual trip would be more convenient and less worrisome…
If I could make it fit.

The packing list

All the stuff I packed into a bag for a week of travel.

Water bottle

I later decided not to bring it.
5 pair of socks and underwear
3 t-shirts, 1 long-sleeve t-shirt
1 slightly thicker long-sleeve shirt
Training gear for Submission Wrestling

Shorts, rashguard, spats, knee pads, and mouth guard.
1 pair of pants
Mobile phone charger
A Framework 13 laptop + charger
Laptop–headphone cable

I also brought the Sony WH-1000X M3 noise canceling headphones that I wore during the trip.
Remarkable 2
A bag for dirty clothes
Toothbrush & toothpaste
Power bank
Vitamins & medicine
Nail clippers, tape, Whoop body holder
Earbuds & sleep mask
A book—the first two books in the Murderbot Diaries series.

Things to wear

Clothes I wore during the travel.

I saw the advice that the clothes you travel with is also very important. They have a point.

Pants with large pockets with zippers.

I could use the pants the whole week if I wanted to.

I saw the advice that one bag travel is dead and that 1.5 bag travel is the future, where you should bring a sling and put things like your wallet and phone there. Meh, I brought a pair of pants with bigger pockets instead.
A Houdini hoodie.

Really warm and cozy, should last the whole week.
A thin jacket.

Paired with the hoodie it provides a decent enough protection against the weather. I’m not going on a hiking trip; I’ll be moving between the office, the hotel, and restaurants.

It’s also thin enough so I can fit it into the fully packed backpack.
A cap and gloves.

I’m traveling in Sweden, it’s still fairly cold here.

What I wish I brought

It was a bit too cold on some days. A warmer jacket, long-johns, or a nudge would’ve been good.
The next Murderbot book. The first was fantastic! I had to visit a local book store where I bought Lock In. Loved that too.

Gearing up

Before I could try out one bag travel I had to get a new backpack. I ended up with the Fyro Levo 30L backpack mostly because the creator had a bunch of cool videos about bags… As shipping was expensive I also got their packing cubes, the retractable key leash, and a 1L sling (that I didn’t use).

This isn’t a review of their stuff; there’s probably better options out there but I’m too inexperienced to say. Maybe I should’ve gotten the 36L backpack, and the sling was an unnecessary purchase, but other than that I’ve been very happy with the Fyro products.

Packing in

Will it fit?

All clothes are packed into the packing cubes. One cube with the Submission Wrestling training clothes, one with underwear, and the largest with the rest of the clothes.

The packing cubes fits into the main compartment perfectly.

Medicine, earplugs, mouth guard, and other stuff went into these pockets in the main compartment.

Laptop, Remarkable goes in the back. The electronics compartment is a little tight with the charger, power bank, and some other stuff, but it closes.

The quick access compartment in the front with toothpaste and mobile charger.

One of the biggest critiques against the bag is that the pockets here are very loose as things might fall out. When the bag is fully packed this has not been my experience—almost the reverse. Fully packed, it’s a bit too tight. But empty they’re too loose.

Keys and travel documents in the “passport” pocket right next to the back.

The fully packed bag.

I did fit everything I wanted to bring. Although I skipped the water bottle it would’ve fit into the water bottle holder on the side. Maybe I’ll bring it next time.

The fully packed bag weighed in at 7.3 kg.

On the road

I managed to push down my jacket, gloves, cap, and book into the front pocket.

I do love the large front compartment.

The Levo has a small loop to hang up the bag in the bathroom. Nice.

With some force I could fit the bag under the seat in front of me in the train.

The bag under the seat in the domestic SAS flight.

I was a bit worried that the bag wouldn’t fit under the front seat but it worked out well. I didn’t take a picture of it but it fit in the overhead compartment during the flight too.

Although the extra space of the 36L backpack would’ve been greatly appreciated I fear that it might have made the bag too large to fit under the seat. In the end I think I prefer the convenience of having the bag under the seat over the extra 6L of space.

From hotel to office

Bag without packing cubes.

The bag was also used to transport the laptop and other electronics between the hotel and office. I was worried that a huge bag would be a chore to bring but that’s been a non-issue. The only minor problem is that the bag doesn’t stand by itself without the packing cubes.

Pros and cons

One’s destination is never a place, but a new way of seeing things.

Henry Miller

Overall I’ve really enjoyed my one bag traveling experience. I managed to fit into a single bag and the trip was a lot easier and more streamlined.

There are however some downsides that bothers me quite a bit:

I couldn’t bring Luthier, my new favorite boardgame on the trip.

My work trips have been one of the best ways to reduce my boardgame list-of-shame (bought and unplayed boardgames). Or to play my favorite games again.
There’s not enough space to bring back gifts, such as clothes or LEGO.

Then again, maybe I don’t need to always bring back gifts? Or maybe small gifts are good enough?
I can’t go nuts in the local book stores.

Last time I brought back five new fantasy and sci-fi books. This time I bought a small book that I could fit at the back above the laptop.

I haven’t yet decided if I shall continue with the one bag travel, or if I shall start checking in a suitcase again. Either way it’s been eye opening how much you can do with a regular backpack.

2025 in review

2026-01-08T10:49:16+00:00

It’s time for a yearly review again. Time flies.

Nerdy things I enjoyed

I read a few books this year.

The whole Dungeon Crawler Carl series was absolutely amazing and it quickly jumped up to one of my favorite series of all time.

I can’t be held accountable for everything I’ve ever said to a stripper.

Princess Donut
Board games are great.

I still don’t play nearly as much as I’d like to but my kids are quickly growing up and to my eternal joy they’re all interested in board games! Isidor (8) has been loving Radlands, Loke (5) likes Chronicles of Avel, and Freja (3) loves Dragon’s Breath. My personal favorite is Luthier and I think it might be my absolute favorite game right now.
Computer games have made a small comeback.

As my kids have been gaming more I’ve regained a little bit of interest in gaming too. I’ve been playing a little Core Keeper and Beyond All Reason with Isidor and it felt really fun.
Migrated my Neovim config to Fennel.

Eh, it was fun to play with a new language.

Things I accomplished

I wrote 12 blog posts, not great, not terrible.
I managed to push back my fantasy writing ambitions to the future.

It’s important as I tend to get stuck on things, preventing me from making progress in other parts. I really don’t have the time or energy to try to write a fantasy book right now, but making my brain see that wasn’t easy.
2025 was the first full year running my company.

I’m still consulting for the same company I started out with and I enjoy it. It feels good to say that I haven’t blown it completely just yet.
Switched to GrapheneOS.

I took a big step forward in de-Googling and to increase my personal security by moving to GrapheneOS. I’m super happy about it.
Built my second 3D-printer, a VORON 0.

My VORON 0.

It’s good! It’s fun! And I’m already planning my next printer…
We migrated away from Sonos in our Kitchen.

We got tired of buggy vendor lock-in and now we use my own Music Assistant based setup. If things break we can now blame me instead of Sonos.
I built my server first rack to host a new homelab server.

A server rack with homelab stuff.

I still need to cleanup the cables and write a blog post about it.

Tentative plans/goals/wishes for 2026

Go on some roller coasters with the family.

We’re planning to go to Liseberg in Göteborg and I know the kids will love it.
Lose weight and build muscle.

I’ve been having a rough year training and health wise. Not being able to get a consistent strength training routine, inconsistent sleep, and spouts of depression has made me gain too much weight again.

Getting it sorted should (must) be a high priority this year.
Get our own training space for our martial arts club.

I’ve been wanting to get our own place for quite a while and I feel that we need to make it happen sooner rather than later.
Develop a company product MVP.

While I enjoy the consulting work I do at the moment my goal is to one day have a project of my own that can earn me money. I have a couple of ideas I want to pursue and I was going to do it in 2025 but I didn’t get far enough for that.
Migrate my homelab to the recently built server and expand on it.

I have this newly built server that’s just sitting idle. I need to migrate my old services to it and I’ve got ideas for lots of stuff I want to put there.

3D printer repairing and modding

2026-04-01T06:39:23+00:00

I’ve had my VORON Trident for 2 years and I’ve run it for 2600 hours. Overall I’m happy with the printer but I’ve been itching to make some more mods to it. Having finally finished the VORON 0 (with mods) I now have a backup printer I can use to rescue myself when I screw up.

As the printer was starting to crap out with a leadscrew starting to grind down again, the chamber thermistor stopped working, and PLA clogging up the Rapido hotend again it was time for a bit of a rebuild.

The plan

Besides fixing the printer I also wanted to prepare for a multi-color solution such as the Box Turtle and make some quality of life changes.

Replace the problematic leadscrew with a replacement part I received from LDO and replace the POM nuts on the other leadscrews.
Install the Inverted electronics mod.

I’ve been using the RockNRoll mod to give access to the electronics compartment by tilting the printer backwards. The Inverted electronics mod would instead allow me to lift the bottom plate to access the electronics compartment and I want to do it before installing a Box Turtle on top of the printer.
Replace the Stealthburner with the Jabberwocky toolhead.

This introduced a series of changes:
1. Move to an umbilical setup with the Nitehawk36 toolboard.
2. Use sensorless homing to get rid of the Y drag chain.
3. Replace TAP with the Beacon probe.
4. Finally, install the Jabberwocky.

Replacing the POM nuts

I’ve had issues before where one of the POM nuts were ground down and I felt it was happening again. The printer didn’t completely fail like before but it was sometimes getting really bad first layers in that same corner and the Z probe was occasionally failing to configure Z tilt.

I replaced all three POM nuts together with the whole lead screw (I got a new one sent to me by LDO the first time it failed but I hadn’t installed it yet).

Dust on the lead screw and all three nuts show signs of damage, although the leftmost is clearly worse off.

This is apparently a common problem with some LDO kits that have coated lead screws. I still have two of the old ones that I may have to replace in the future.

Inverted electronics

I’ve been looking at the Inverted electronics mod even before finishing my Trident printer. But it wasn’t possible with the Print It Forward service I used to print parts for my first 3D printer, and after the printer was completed I didn’t feel the need to redo the wiring again.

Wiring before ripping it all out.

Underside of the printer with the inverted rails installed.

Installing the first components on the rails.

The electronics are reinstalled and up and running. This is not the final configuration, just a snapshot of when I got it running.

The electronics with cables cleaned up a little.

Overall it was surprisingly easy to reinstall all the electronics. It was made easier by the move to umbilical and a single USB cable to the toolhead as it removed quite a bit of wiring:

Heap of things I removed from the printer when moving to umbilical and sensorless homing.

One issue I had with the mod is that the cutouts for the Z motors were a bit large, with gaps where stray filament or heat can escape through. I tried to cover them up by placing some foam tape around the motors:

The Z motor mounts have a gap between them and the electronics cover. I tried to fill them in with foam tape from below.

Why the Jabberwocky?

I’ve been wanting to replace the Stealthburner toolhead a long time:

The cooling for PLA is quite bad.
PLA has a tendency to clog (seems like a decently common problem with Rapido and Stealthburner).
Resolving a clog when it happens is a pain in the ass.
It lacks a filament sensor and a cutter (for multi-color).

But what to choose? There are quite a few interesting toolheads I considered:

Dragon Burner

I use the Dragon Burner in my VORON 0 and using the same toolhead is boring.
Archetype

A pretty fun toolhead and I was considering the Mjölnir version. It does require you to flip your XY joints to hang upside down and I couldn’t find a filament sensor or filament cutter for it, so I ended up skipping it.
XOL

XOL seems like a very well regarded and mature option with tons of support. It boasts much better cooling for PLA, which is one of the main reasons I want to migrate away from the Stealthburner.
A4T-toolhead

A4T seems similar to XOL, while having even better cooling and a slightly simpler assembly. It would also make use of the Dragon hotend I’ve got lying here, gathering dust.
Jabberwocky

An all-in-one toolhead solution with filament sensors and a filament cutter that seems to have some quality of life features I think I’d really enjoy:

Flip up Extruder. Probably an industry first, a tool-less easy to access toolhead design so that one can access the blade or the filament path for servicing and troubleshooting. This allows a user, in the event of hopefully a rare problem during a filament changing print the ability to access the filament path to clear it of issues and continue with a print job.

Jabberwocky Beta test, TheKittieKatt

The A4T-toolhead is interesting but the (supposedly) easier maintenance and multi-color consistency of the Jabberwocky really appealed to me.

Building the Jabberwocky

The bottom of the extruder with a piece of filament sticking through.

I struggled a bit to get the filament to load/unload consistently by hand. I rebuilt the toolhead but in the end I believe I just didn’t have enough grip on the filament to guide it past the gears down into bottom hole.

The bottom part of the toolhead with fans installed.

The back with Nitehawk36 but without the hotend installed.

The front but without the cover for the upper LED. (I forgot to print it before the printers went uncooperative.)

Beacon wiring

Beacon is installed.

Most of the wiring came as-is except for the cable between the Beacon and the Nitehawk36. I got the Nitehawk36 side of the cable pre-made in the Nitehawk36 kit but I had to pin the Beacon side myself.

The colors of the wires in cable were all over the place but there’s a description on the PCB of both the Nitehawk36 and Beacon so I just had to take care to match them. I also referenced the Nitehawk36 documentation and the Beacon documentation.

The wire between the Beacon and Nitehawk36.

Cutter installation woes

I had real difficulties installing the blade into the blade holder. There was some filament in the hole (likely due to poor print tuning) and I managed to break the holder when I tried to install the blade:

I broke the blade holder when I tried to force in the blade.

The lower part of the extruder where the blade will cut the filament.

As I didn’t have a working printer when it broke I had to make it work without the filament cutter initially. Luckily I didn’t break anything crucial…

Software setup

I had to make some software changes but luckily they were quite straightforward:

Use sensorless homing.

I just followed the VORON documentation.
Setup the Nitehawk36 toolboard.

LDO has setup instructions and the Jabberwocky GitHub contains klipper settings.
Setup Beacon for Z offset and mesh calibration.

Their quickstart documentation was fast and easy. I did not setup Beacon Contact; maybe I’ll get to it one day.

What’s next?

The printer is finally printing again!

After months of not having a working 3D printer I’ve gotten renewed energy to play around with the printer again. I’ve got some loose plans for some mods to make on this printer:

Reprint the Jabberwocky and try to get the filament cutter up and running.
Build and test the A4T-toolhead.
Install a nozzle scrubber.
Build a Box Turtle.

… Or maybe something else? Who knows!

Packing Neovim with Fennel

2026-04-27T15:24:47+00:00

I’ve got lots of stuff to do but I ended up rewriting my Neovim config instead.

… anyone can do any amount of work, provided it isn’t the work he is supposed to be doing at that moment.

Robert Benchley, in Chips off the Old Benchley, 1949

My partner Veronica is amazing as she’ll listen to my bullshit and random whims (or at least, pretend to). That’s a big benefit to having a blog: so I have an outlet for rambling about my weird projects and random fixations and spare Veronica’s sanity a little.

I know that Veronica won’t be impressed by another Neovim config rewrite (even when done in Lisp!) so I’ll simply write a big blog post about it.

The rewrite

I wanted to rewrite my Neovim configuration in Fennel (a Lisp that compiles to Lua) and while doing so I wanted to migrate from lazy.nvim to Neovim’s new built-in package manager vim.pack.

This included bootstrapping Fennel compilation for Neovim; replicating missing features from lazy.nvim such as running build scripts and lazy loading; modernizing my LSP and treesitter config; and trying out some new interesting plugins.

Please see my new Neovim config here.

Why Fennel?

Lua has been a fantastic boon to Neovim and it’s a significant improvement over Vimscript, yet I can’t help but raise an eyebrow when I hear people describe Lua as a great language. It’s definitely great at being a simple and fast embeddable language but the language itself leaves me wanting more.

Fennel doesn’t solve all issues as some of Lua’s quirks bleeds through but it should make it a little bit nicer. I particularly like the destructuring; more functional programming constructs; macros for convenient DSL; and the amazing pipe operator.

But the biggest reason is that I’m simply a bit bored and trying out new programming languages is fun.

Why vim.pack?

I don’t rewrite my config often. But when I do, I do it properly.

Ancient Neovim wisdom

Folke, maker of many popular plugins such as lazy.nvim and snacks.nvim, recently had a ~5 month break from working on his plugins. Of course, they continued to work and anyone working on open source projects can (and should) take a break whenever they want.

But it exemplifies that core Neovim features will likely be better maintained than standalone plugins and should probably be preferred (if they provide the features you need).

While Neovim’s built-in plugin manager is a work in progress and still a bit too simplistic for my needs I wanted to try it out.

Structuring the config

If you’ve got a small configuration having it all inside a single init.lua is probably fine. Somehow I’ve gathered almost 6k lines of Lua code under ~/.config/nvim so showing it all in one file isn’t that appealing.

I first wanted to separate the configuration into a core/plugin split, where non-plugin configuration happens in core and plugin configuration lives under plugin. However, to support lazy loading with a single call to vim.pack.add I decided to go back to letting the files under plugin/ return plugin specs, like lazy.nvim does for you.

With Fennel support under fnl/ this is how my configuration is structured:

init.lua                ; Minimal bootstrap to load Fennel files
fnl                     ; All Fennel source in the `fnl/` folder
├── config
│   ├── init.fnl        ; Loaded by `init.lua` and loads the rest
│   ├── colorscheme.fnl
│   ├── keymaps.fnl
│   ├── lsp.fnl         ; Config may reference plugins
│   └── ...
├── macros.fnl          ; Custom Fennel macros goes here
└── plugins
    ├── init.fnl        ; Loads everything under `plugins/`
    ├── appearance.fnl
    ├── coding.fnl
    └── ...
lua                     ; Lua stuff is still loaded transparently
ftplugin
└── djot.lua            ; nvim-thyme doesn't load `ftplugin/`

It’s not a perfect system as I’d ideally want the plugins/ to only add packages while I would configure the plugins in config/. But some plugins use lazy loading making it more convenient to do it together with the plugin spec.

Bootstrapping Fennel

There are a handful of different plugins that allows you to easily write your Neovim config in Fennel. I ended up choosing nvim-thyme because it’s fast (it hooks into require and only compiles on-demand) and it allows you to mix Fennel and Lua source files.

nvim-thyme contains installation instructions for lazy.nvim and it references a bootstrapping function to run git to manually clone packages. But we’re going to use vim.pack and it makes the bootstrap a bit cleaner:

vim.pack.add({
  -- Fennel environment and compiler.
  "https://github.com/aileot/nvim-thyme",
  "https://git.sr.ht/~technomancy/fennel",
  -- Gives us some pleasant fennel macros.
  "https://github.com/aileot/nvim-laurel",
  -- Enables lazy loading of plugins.
  "https://github.com/BirdeeHub/lze",
}, { confirm = false })

(I added lze to my bootstrapping too as I’ll use it later when adding lazy loading support, it was simpler having it in the bootstrap.)

nvim-thyme also instructs us to override require() calls (so it can compile on demand) and to setup the cache path (where it’ll store the compiled Lua files):

-- Override package loading so thyme can hook into `require` calls
-- and generate lua code if the required package is a fennel file.
table.insert(package.loaders, function(...)
  return require("thyme").loader(...)
end)

-- Setup the compile cache path for thyme.
local thyme_cache_prefix = vim.fn.stdpath("cache") .. "/thyme/compiled"
vim.opt.rtp:prepend(thyme_cache_prefix)

And now we’re ready to write the rest of the config with Fennel!

-- Load the rest of the config with transparent fennel support.
require("config")

Now we can continue with Fennel fnl/config.fnl or fnl/config/init.fnl:

;; Load all plugins
(require :plugins)

;; Load the other config files
(require :config.colorscheme)
(require :config.keymaps)
(require :config.lsp)
;; etc...

There’s one last thing we should do to make the bootstrap complete: we should call :ThymeCacheClear when nvim-laurel or nvim-thyme changes. The recommended way is to use the PackChanged event, with something like this:

vim.api.nvim_create_autocmd("PackChanged", {
  callback = function(event)
    local name = event.data.spec.name

    if name == "nvim-thyme" or name == "nvim-laurel" then
      require("thyme").setup()
      vim.cmd("ThymeCacheClear")
    end
  end,
  group = vim.api.nvim_create_augroup("init.lua", { clear = true }),
})

vim.pack.add(...)

But if we for example force an update for nvim-laurel (by deleting it with vim.pack.del({"nvim-laurel"}) and restart Neovim) we get this error:

Error in /home/tree/code/nvim-conf/init.lua..PackChanged Autocommands for "*":
Lua callback: /home/tree/code/nvim-conf/init.lua:12: module 'thyme' not found:
        no field package.preload['thyme']
        cache_loader: module 'thyme' not found
        cache_loader_lib: module 'thyme' not found
        no file './thyme.lua'
        ...

There is no order guarantee for the packages and so PackChanged for nvim-laurel may run before thyme has been loaded. I worked around this with a variable that I check after vim.pack.add, which will guarantee that all packages have been added before we try to require a package:

local rebuild_thyme = false

vim.api.nvim_create_autocmd("PackChanged", {
  callback = function(event)
    local name = event.data.spec.name

    if name == "nvim-thyme" or name == "nvim-laurel" then
      rebuild_thyme = true
    end
  end,
  group = vim.api.nvim_create_augroup("init.lua", { clear = true }),
})

vim.pack.add(...)

table.insert(package.loaders, function(...)
  return require("thyme").loader(...)
end)

local thyme_cache_prefix = vim.fn.stdpath("cache") .. "/thyme/compiled"
vim.opt.rtp:prepend(thyme_cache_prefix)

require("thyme").setup()

-- Rebuild thyme cache after `vim.pack.add` to avoid dependency issues
-- and to make sure all packages are loaded.
if rebuild_thyme then
  vim.cmd("ThymeCacheClear")
end

Building a convenient plugin management system

I wanted to migrate to vim.pack but it’s missing a few key features from lazy.nvim:

It can’t automatically require all files under a directory.
There’s no lazy loading support.
It can’t run build scripts (such as make after install or update).

I could’ve given up and gone back to lazy.nvim but that just wouldn’t do.

Source pack specs from files

I want to be able to create a file under plugins/, have it return a vim.pack.Spec, and have it automatically added. This is similar to the structured plugins approach of lazy.nvim.

To build this I first list all files under plugins/ like so:

;; List all files, with absolute paths.
(local paths (-> (vim.fn.stdpath "config")
                 (.. "/fnl/plugins/*")
                 (vim.fn.glob)
                 (vim.split "\n")))

This uses Fennel’s -> threading macro, Fennel’s version of the pipe operator. It’s one of my favorite features of Elixir and was stoked to discover that Fennel has it too. (Fennel actually has even more power with the ->>, -?>, and -?>> operators!)

Now we need to loop through and transform the paths to relative paths and evaluate the files to get our specs. (I’m using accumulate to explicitly build a list instead of collect as we’ll soon expand on it):

;; Make the paths relative to plugins and remove extension, e.g. "plugins/snacks"
;; and require those packages to get our pack specs.
(local specs (accumulate [acc [] _ abs_path (ipairs paths)]
               (do
                 (local path (string.match abs_path "(plugins/[^./]+)%.fnl$"))
                 (if (and path (not= path "plugins/init"))
                     (do
                       (local mod_res (require path))
                       (table.insert acc mod_res))
                       acc)
                     acc))))

Now we can populate specs from files under plugins/, for example like this that returns a single spec:

{:src "https://github.com/romainl/vim-cool"}

But I also want to be able to return multiple specs:

[{:src "https://github.com/nvim-lua/popup.nvim"}
 {:src "https://github.com/nvim-lua/plenary.nvim"}]

To support this we can match on the return value to see if it’s a list, and then loop and insert each spec in the list, otherwise we do as before:

(local specs (accumulate [acc [] _ abs_path (ipairs paths)]
               (do
                 (local path (string.match abs_path "(plugins/[^./]+)%.fnl$"))
                 (if (and path (not= path "plugins/init"))
                     (do
                       (local mod_res (require path))
                       (case mod_res
                         ;; Flatten return if we return a list of specs.
                         [specs]
                         (each [_ spec (ipairs mod_res)]
                           (table.insert acc spec))
                         ;; Can return a string or a single spec.
                         _
                         (table.insert acc mod_res))
                       acc)
                     acc))))

Now all that’s left is to call vim.pack.add with our list of specs and our plugins are now automatically added from files under plugins/:

(vim.pack.add specs {:confirm false})

Lazy loading with lze

lze is a nice and simple plugin to add lazy-loading to vim.pack.

We’ve already added it as a dependency in our init.lua so all we need to do is modify the load parameter to vim.pack.add like so:

;; Override loader when adding to let lze handle lazy loading
;; when specified via the `data` attribute.
(vim.pack.add specs {:load (fn [p]
                             (local spec (or p.spec.data {}))
                             (set spec.name p.spec.name)
                             (local lze (require :lze))
                             (lze.load spec))
                     :confirm false})

Now we can specify lazy loading via the data parameter in our specs:

{:src "https://github.com/romainl/vim-cool"
 :data {:event ["BufReadPost" "BufNewFile"]}}

It relies on wrapping configuration under data but that’s annoying, so let’s simplify things a little.

Simplified specifications

The idea here is to transform the specs before we call vim.pack.add.

We can do it easily when we collect our specs by calling the transform_spec function:

(local specs (accumulate [acc [] _ abs_path (ipairs paths)]
               (do
                 (local path (string.match abs_path "(plugins/[^./]+)%.fnl$"))
                 (if (and path (not= path "plugins/init"))
                     (do
                       (local mod_res (require path))
                       (case mod_res
                         [specs]
                         (each [_ spec (ipairs mod_res)]
                           (table.insert acc (transform_spec spec)))
                         _
                         (table.insert acc (transform_spec mod_res)))
                       acc)
                     acc))))

I want transform_spec to transform this:

{:src "https://github.com/romainl/vim-cool"
 :event ["BufReadPost" "BufNewFile"]}

Into this:

{:src "https://github.com/romainl/vim-cool"
 :data {:event ["BufReadPost" "BufNewFile"]}}

By storing keys other than src, name, and version under a data table. This is what I came up with:

(λ transform_spec [spec]
  "Transform a vim.pack spec and move lze arguments into `data`"
  (case spec
    {}
    (do
      ;; Split keys to vim.pack and rest into `data`.
      (local pack_args {})
      (local data_args {})
      (each [k v (pairs spec)]
        (if (vim.list_contains [:src :name :version] k)
            (tset pack_args k v)
            (tset data_args k v)))
      (set pack_args.data data_args)
      pack_args)
    ;; Bare strings are valid vim.pack specs too.
    other
    other))

Another quality of life feature I’d like is to make it simpler to call setup functions. lazy.nvim again does this well and it’s pretty convenient.

For example, this is how it looks like with lze to add an after hook and call a setup function:

{:src "https://github.com/A7Lavinraj/fyler.nvim"
 :on_require :fyler
 :after (λ []
          (local fyler (require :fyler))
          (fyler.setup {:icon_provider "nvim_web_devicons"
                        :default_explorer true}))}

What if we could instead do:

{:src "https://github.com/A7Lavinraj/fyler.nvim"
 :on_require :fyler
 :setup {:icon_provider "nvim_web_devicons" :default_explorer true}}]

But this is just data and we can transform the second case to the first one fairly easily. In the transform_spec function:

(λ transform_spec [spec]
  "Transform a vim.pack spec and move lze arguments into `data`
   and create an `after` hook if `setup` is specified."
  (case spec
    {}
    (do
      ;; Split keys to vim.pack and rest into `data`.
      (local pack_args {})
      (local data_args {})
      (each [k v (pairs spec)]
        (if (vim.list_contains [:src :name :version] k)
            (tset pack_args k v)
            (tset data_args k v)))

      (λ after [args]
        ;; Call `setup()` functions if needed.
        (when spec.setup
          (local pkg (require spec.on_require))
          (pkg.setup spec.setup))
        ;; Load user specified `after` if it exists.
        (when spec.after
          (spec.after args)))

      (set data_args.after after)
      (set pack_args.data data_args)
      pack_args)
    ;; Bare strings are valid vim.pack specs too.
    other
    other))

How to figure out the package name to require (since it may differ from the path)? lazy.nvim has a bunch of rules to try to figure this out automatically but I chose to be explicit. lze uses the on_require argument so it can load on a require call (on (require :fyler) for example), which seems like a good idea to reuse.

And just to prevent me from making mistakes, I added a sanity check:

;; `:setup` needs to know what package to require,
;; therefore we use `:on_require`
(when (and spec.setup (not spec.on_require))
  (error (.. "`:setup` specified without `on_require`: "
             (vim.inspect spec))))

(λ after [args]
  ;; ...

Build scripts via PackChanged events

There’s one last feature I really want from lazy.nvim and that’s to automatically run build scripts after a package is installed or updated.

I basically want to specify this in my specs:

{:src "https://github.com/eraserhd/parinfer-rust"
 :build ["cargo" "build" "--release"]}

Again, we’ll rely on PackChanged for this:

;; Before `vim.pack.add` to capture changes.
(augroup! :plugin_init (au! :PackChanged pack_changed))

The above code uses macros from nvim-laurel to define an autocommand that calls the pack_changed function. That function will then run pack_changed when the package is updated or installed:

(λ pack_changed [event]
  (when (vim.list_contains [:update :install] event.data.kind)
    (execute_build event.data))
  ;; Return false to not remove the autocommand.
  false)

(λ execute_build [pack]
   ;; `?.` will prevent crashing if any field is nil.
  (local build (?. pack :spec :data :build))
  (when build
    (run_build_script build pack)))

To run the scripts I use vim.system with some simple printing:

(λ run_build_script [build pack]
  (local path pack.path)
  (vim.notify (.. "Run `" (vim.inspect build) "` for " pack.spec.name)
              vim.log.levels.INFO)
  (vim.system build {:cwd path}
              (λ [exit_obj]
                (when (not= exit_obj.code 0)
                  ;; If I use `vim.notify` it errors with:
                  ;; vim/_editor.lua:0: E5560: nvim_echo must not be called in a fast event context
                  ;; Simply printing is fine I guess, it doesn't have to be the prettiest solution.
                  (print (vim.inspect build) "failed in" path
                         (vim.inspect exit_obj))))))

This will now allow us to run build scripts like cargo build --release or make after a package is installed or updated. It’s a bit too basic as there’s no visible progress bar for long running builds (Rust, I’m looking at you!) and it doesn’t handle build errors that well but it works well enough I guess.

But what about user commands or requiring a package? For example with nvim-treesitter you’d want to run :TSUpdate after an update, something like this:

{:src "https://github.com/nvim-treesitter/nvim-treesitter"
 :version :main
 :build #(vim.cmd "TSUpdate")}

Let’s try it by allowing functions in the build parameter (and bare strings because why not):

(λ execute_build [pack]
  (local build (?. pack :spec :data :build))
  (when build
    (case (type build)
      ;; We can specify either "make" or ["make"]
      "string" (run_build_script [build] pack)
      "table" (run_build_script build pack)
      ;; Run a callback instead.
      "function" (call_build_cb build pack))))

(λ call_build_cb [build pack]
  (vim.notify (.. "Call build hook for " pack.spec.name) vim.log.levels.INFO)
  (build pack))

If we run this though it doesn’t work:

Error in /home/tree/code/nvim-conf/init.lua..PackChanged Autocommands for "*":
Lua callback: vim/_editor.lua:0: /home/tree/code/nvim-conf/init.lua..PackChanged Autocommands for "*"..script nvim_exec2() called
at PackChanged Autocommands for "*":0, line 1: Vim:E492: Not an editor command: TSUpdate

The problem is that PackChanged is run before the pack is loaded. Maybe we could work around this by calling packadd ourselves but that would shortcut lazy loading. In this instance we’d like to run TSUpdate after the pack is loaded but only if it’s been updated or installed so we don’t run it after every restart.

What I did was introduce an after_build parameter to the spec that’s run after load if a PackChanged event was seen before:

{:src "https://github.com/nvim-treesitter/nvim-treesitter"
 :version :main
 :after_build #(vim.cmd "TSUpdate")}

Then in plugins/init.fnl I use a local variable packs_changed that’s updated on PackChanged like so:

;; Capture packs that are updated or installed.
(g! :packs_changed {})

(λ set_pack_changed [name event]
  ;; Maybe there's an easier way of updating a table global...?
  (var packs vim.g.packs_changed)
  (tset packs name event)
  (g! :packs_changed packs))

(λ pack_changed [event]
  (when (vim.list_contains [:update :install] event.data.kind)
    (local pack event.data)
    (set_pack_changed pack.spec.name event)
    (execute_build pack))
  false)

Then we’ll call after_build from the after hook we setup before:

(λ transform_spec [spec]
  (case spec
    {}
    (do
      ;; Split keys to vim.pack and rest into `data`.
      ;; ...

      (λ after [args]
        (local pack_changed_event (. vim.g.packs_changed args.name))
        (set_pack_changed args.name false)
        (when spec.setup
          (local pkg (require spec.on_require))
          (pkg.setup spec.setup))
        ;; Run `after_build` scripts if a `PackChanged` event
        ;; was run with `install` or `update`.
        (when (and spec.after_build pack_changed_event)
          (spec.after_build args))
        (when spec.after
          (spec.after args)))

      (set data_args.after after)
      (set pack_args.data data_args)
      pack_args)
    other
    other))

With this we can finally specify build actions such as these:

{:build "make"
 :build ["cargo" "build" "--release"]
 :after_build #(vim.cmd "TSUpdate")}

While the build system mostly works, once in a while it’ll break and fail to run the build scripts. Maybe there was a weird build error or something. For these cases I have a :BuildPacks user command that runs build and after_build for all packs like so:

(command! :BuildPacks
          (λ []
            (each [_ pack (ipairs (vim.pack.get))]
              (execute_build pack)
              (local after_build (?. pack :spec :data :after_build))
              (when after_build
                (execute_after_build after_build pack.spec.name)))))

I really hope that proper build script support will land in core Neovim one day so I can rid myself of my crappy implementation. It makes me feel icky.

Some Fennel examples

You’ve already seen how Fennel code looks like but what about configuration with Fennel? One of the negative things of moving my configuration from Vimscript to Lua was that simple things such as settings options or simple keymaps is more verbose.

So how does Fennel compare for the simpler, more declarative stuff?

Options

set relativenumber
set clipboard^=unnamed,unnamedplus
set backupdir=~/.config/nvim/backup
let mapleader=" "

vim.opt.relativenumber = true
vim.opt.clipboard:append({ "unnamed", "unnamedplus" })
vim.opt.backupdir = vim.fn.expand("~/.config/nvim/backup")
vim.g.mapleader = [[ ]]

(set! :relativenumber true)
(set! :clipboard + ["unnamed" "unnamedplus"])
(set! :backupdir (vim.fn.expand "~/.config/nvim/backup"))
(g! :mapleader " ")

With nvim-laurel macros I think Fennel is decent. Slightly better than Lua but not as convenient as Vimscript.

Keymaps

local map = vim.keymap.set
map("n", "<localleader>D", vim.lsp.buf.declaration,
  { silent = true, buffer = buffer, desc = "Declaration" }
)
map("n", "<leader>ep", function() find_org_file("projects") end,
  { desc = "Org projects" }
)
map("n", "]t", function()
  require("trouble").next({ skip_groups = true, jump = true })
end, {
  desc = "Trouble next",
  silent = true,
})

(bmap! :n "<localleader>D" vim.lsp.buf.declaration
       {:silent true :desc "Declaration"})
(map! :n "<leader>ep" #(find_org_file "projects")
      {:desc "Org projects"})
(map! :n "]t" #(do
                 (local trouble (require :trouble))
                 (trouble.next {:skip_groups true :jump true}))
      {:silent true :desc "Trouble next"})

Not a huge difference to be honest. I like the #(do_the_thing) shorthand for anonymous functions fennel has. Having to (sometimes) split up require and method calls on separate lines in Fennel is annoying.

Update 2025-10-29

A comment on Reddit pointed out that you can simplify require and method calls with a macro:

(fn m [m func ...]
  "Call a function on a module"
  (assert-compile (sym? m) "expected module name")
  (assert-compile (sym? func) "expected function name")
  `((. (require ,(tostring m)) ,(tostring func)) ,...))

And then use it like so:

(map! :n "]t" #(m trouble next {:skip_groups true :jump true})
      {:silent true :desc "Trouble next"})

Overriding highlight groups

One example that was a big step up with Fennel is overriding highlight groups. I’m using melange which is a fantastic and underrated color scheme but I’ve collected a fair bit of overrides for it.

In Lua you use nvim_set_hl to add an override, for example like this:

vim.api.nvim_set_hl(0, "@symbol.elixir", { link = "@label" })

When you do this 100 times this is annoying so I made an override table to accomplish the job:

local overrides = {
  { name = "@symbol.elixir", val = { link = "@label" } },
  { name = "@string.special.symbol.elixir", val = { link = "@label" } },
  { name = "@constant.elixir", val = { link = "Constant" } },
  -- And around 100 other overrides...
}

for _, v in pairs(overrides) do
  vim.api.nvim_set_hl(0, v.name, v.val)
end

In Fennel with the hi! macro this all becomes as simple as:

(hi! "@symbol.elixir" {:link "@label"})
(hi! "@string.special.symbol.elixir" {:link "@label"})
(hi! "@constant.elixir" {:link "Constant"})

Autocommands

Here are some autocommands to enable cursorline only in the currently active window (while skipping buffers such as the dashboard):

local group = augroup("my-autocmds", { clear = true })
autocmd({ "VimEnter", "WinEnter", "BufWinEnter" }, {
  group = group,
  callback = function(x)
    if string.len(x.file) > 0 then
      vim.opt_local.cursorline = true
    end
  end,
})
autocmd("WinLeave", {
  group = group,
  callback = function()
    vim.opt_local.cursorline = false
  end,
})

(augroup! :my-autocmds
          (au! [:VimEnter :WinEnter :BufWinEnter]
               #(do
                  (when (> (string.len $1.file) 0)
                    (let! :opt_local :cursorline true))
                  false))
          (au! :WinLeave #(do
                            (let! :opt_local :cursorline false)
                            false)))

Plugin specs

One thing I like more in Lua compared to Fennel is how readable tables are. The Fennel formatter fnlfmt might be partly to blame as it has a tendency to use very little whitespace. Regardless, I prefer this Lua code:

return {
  "https://github.com/stevearc/conform.nvim",
  { src = "https://github.com/mason-org/mason.nvim", dep_of = "mason-lspconfig.nvim" },
  { src = "https://github.com/neovim/nvim-lspconfig", dep_of = "mason-lspconfig.nvim" },
  "https://github.com/mason-org/mason-lspconfig.nvim",
  {
    src = "https://github.com/nvim-treesitter/nvim-treesitter",
    version = "main",
    after = function()
      vim.cmd("TSUpdate")
    end,
  },
}

Over this corresponding Fennel code:

["https://github.com/stevearc/conform.nvim"
 {:src "https://github.com/mason-org/mason.nvim" :dep_of :mason-lspconfig.nvim}
 {:src "https://github.com/neovim/nvim-lspconfig" :dep_of :mason-lspconfig.nvim}
 "https://github.com/mason-org/mason-lspconfig.nvim"
 {:src "https://github.com/nvim-treesitter/nvim-treesitter"
  :version :main
  :after #(vim.cmd "TSUpdate")}

To me the Lua code is for some reason easier to read.

Similarly I don’t have a problem with this lazy.nvim spec:

return {
  "folke/snacks.nvim",
  priority = 1000,
  lazy = false,
  opts = {
    indent = {
      indent = {
        enabled = true,
        char = "┆",
      },
      scope = {
        enabled = true,
        only_current = true,
      },
    },
    scroll = {
      animate = {
        duration = { step = 15, total = 150 },
      },
    },
    explorer = {},
  },
}

But with this new Fennel spec I use—even though it’s simpler in some ways—it’s harder for me to quickly see what table the keys belong to:

{:src "https://github.com/folke/snacks.nvim"
 :on_require :snacks
 :lazy false
 :setup {:indent {:indent {:enabled true :char "┆"}
                  :scope {:enabled true :only_current true}}
         :scroll {:animate {:duration {:step 15 :total 150}}}
         :explorer {}}}

Maybe it’s something you’ll get used to?

Notable plugin updates

Neovim is moving quickly and I’ve had a bit of catching up to do in the plugin department. I won’t bore you with an exhaustive list; just a few highlights.

Native undotree

I’ve been using undotree a long time and it’s excellent. This feature was recently merged into Neovim:

;; It's optional so we need to use packadd to activate the plugin:
(vim.cmd "packadd nvim.undotree")
;; Then we can add a keymap to open it:
(map! :n "<leader>u" #(: (require :undotree) :open {:command "topleft 30vnew"}))

Simplified LSP config

Neovim routinely gets shit on for LSPs being so hard to setup. Yes, it could probably be easier but Neovim has recently made some changes to streamline LSP configuration and it’s not nearly as involved as it used to be.

Here’s how my base config looks like:

(require-macros :macros)

;; Convenient way of installing LSPs and other tools.
(local mason (require :mason))
(mason.setup)

;; Convenient way of automatically enabling LSPs installed via Mason.
(local mason-lspconfig (require :mason-lspconfig))
(mason-lspconfig.setup {:automatic_enable true})

;; Show diagnostics as virtual lines on the current line.
;; It's pretty cool actually, you should try it out.
(vim.diagnostic.config {:virtual_text false
                        :severity_sort true
                        :virtual_lines { :current_line true })

;; I like inlay hints.
(vim.lsp.inlay_hint.enable true)

(augroup! :my-lsps
          (au! :LspAttach
               (λ [_]
                 (local snacks (require :snacks))
                 (bmap! :n "<localleader>D" snacks.picker.lsp_declarations
                        {:silent true :desc "Declaration"})
                 (bmap! :n "<localleader>l"
                        #(vim.diagnostic.open_float {:focusable false})
                        {:silent true :desc "Diagnostics"})
                ;; etc

I also use nvim-lspconfig but it doesn’t do anything magical (anymore). It’s basically a collection of LSP configs, so I don’t have to fill my config with things like this:

(vim.lsp.config "expert"
                {:cmd ["expert"]
                 :root_markers ["mix.exs" ".git"]
                 :filetypes ["elixir" "eelixir" "heex"]})

(vim.lsp.enable "expert")

If you don’t want to change the keymaps (Neovim comes with defaults that I personally dislike) or customize specific LSPs then there’s not that much left. Mason is also totally optional and if you want to manage your LSPs outside of Neovim you can totally do that. The only thing missing is autocomplete, which blink.cmp provides out of the box.

Automatically install and enable treesitter grammars

Another thing that has changed since my last config overhaul is nvim-treesitter being rewritten and is now a much simpler plugin. The new version lives on the main branch and the old archived one on master and it contains a bunch of breaking changes.

For example, it no longer supports installing and activating grammars automatically. I think I saw a plugin for that somewhere but here’s some Fennel code that sets it up:

(require-macros :macros)

(local nvim-treesitter (require :nvim-treesitter))

;; Ignore auto install for these filetypes:
(local ignored_ft [])

(augroup! :treesitter
          (au! :FileType
               (λ [args]
                 (local bufnr args.buf)
                 (local ft args.match)
                 ;; Auto install grammars unless explicitly ignored.
                 (when (not (vim.list_contains ignored_ft ft))
                   (: (nvim-treesitter.install ft) :await
                      (λ []
                        ;; Enable highlight only if there's an installed grammar.
                        (local installed (nvim-treesitter.get_installed))
                        (when (and (vim.api.nvim_buf_is_loaded bufnr)
                                   (vim.list_contains installed ft))
                          (vim.treesitter.start bufnr))))))))

If you use nvim-treesitter-textobjects (which you should) remember to migrate to the main branch there too.

Some new fun plugins

fyler.nvim, edit a file explorer like a buffer

oil.nvim is a great plugin that allows you to manage files by simply editing text. fyler.nvim takes it to the next level by combining it with a tree-style file explorer.
You may wonder, how in the world does it work?

It’s both smart and simple: the plugins use unique identifiers together with Neovim’s conceal feature to hide them. If you go into an oil.nvim or fyler.nvim buffer and remove the conceal with :set conceallevel=0 you can see this for yourself:
```
/00008 drafts
  /00037 my_first_homelab_rack.dj
  /00038 nvim_fennel_pack_rewrite.dj
  /00041 leftie.dj
```
So if I would rename leftie to rightie in the buffer above and save:
```
/00041 rightie.dj
```
The plugin would see the /00041 identifier and recognize the rename.
blink.cmp, faster autocomplete

I’ve been using nvim-cmp as my completion plugin but I migrated to blink.cmp as it’s faster and more actively maintained. It’s too bad that it broke my custom nvim-cmp source for my blog but it wasn’t too hard to migrate.
snacks.nvim, a better picker

telescope.nvim has been a solid picker but it’s no longer actively developed and the snacks.nvim is the replacement I settled on.

I tried fff.nvim for file picking but surprisingly it felt really slow compared to snacks.nvim. fzf-lua is another great alternative that I haven’t given enough attention to.
grug-far.nvim, global query replace

I’ve been happy with Neovim’s regular %s/foo/bar for single files (aided by search-replace.nvim for easy population). But query replace in multiple files has always felt lacking. I used to use telescope.nvim to populate the quickfix window and then use replacer.nvim to make it editable, updating multiple files.

It worked but was a bit annoying so now I’m trying grug-far.nvim as a more “over engineered” solution. I haven’t used it that long to say for sure but I’m hopeful.

Yes, LSP backed rename exists and it’s great. But sometimes you want to operate on text.

Ending thougths

It would be better to gradually evolve your Neovim config over time instead of doing these large rewrites. But afterwards it feels pretty good as I can once more try to claim with a straight face that I know what’s in my configuration and what it’s doing.

The vim.pack migration was more painful than I had expected. It’s still an experimental nightly feature and it’s missing a lot of nice features that lazy.nvim has. I’ll keep using vim.pack as I think I’ve gotten it to a state of good enough but I’m looking forward to vim.pack becoming more feature complete.

Fennel is fun to write in and I will keep using it where I can. To be honest though, for basic configuration I was expecting Fennel to make a bigger difference than it did. It’s nicer for sure but it’s nothing revolutionary.

Then again, it’s the little things in life that matters.

Link to my new Neovim config on Codeberg

Automating the Hue Tap Dial Switch in Elixir via MQTT

2025-09-01T12:14:57+00:00

I recently bought a couple of Hue Tap Dial switches for our house to enhance our smart home. We have quite a few smart lights and I figured the tap dial—with it’s multiple buttons and rotary dial—would be a good fit.

Since I’ve been moving away from standard Home Assistant automations to my own automation engine in Elixir I had to figure out how best to integrate the tap dial.

At first I tried to rely on my existing Home Assistant connection but I realized that it’s better to bypass Home Assistant and go directly via MQTT, as I already use Zigbee2MQTT as the way to get Zigbee devices into Home Assistant.

This post walks through how I set it all up and I’ll end up with an example of how I control multiple Zigbee lights from one dial via Elixir.

The direct zigbee binding is good but not great

I’m a huge fan of using direct bindings in Zigbee to directly pair switches to lights. This way the interaction is much snappier; instead of going through:

device 1 -> zigbee2mqtt -> controller -> zigbee2mqtt -> device 2

The communication can instead go:

device 1 -> device 2

It works if my server is down, which is a huge plus for important functionality such as turning on the light in the middle of the night when one of the kids have soiled the bed. That’s not the time you want to debug your homelab setup!

The Hue Tap Dial can be bound to lights with Zigbee2MQTT and dimming the lights with the dial feels very smooth and nice. You can also rotate the dial to turn on and off the light, like a normal dimmer switch.

Unfortunately, if you want to bind the dimmer it also binds the hold of all of the four buttons to turn off the light, practically blocking the hold functionality if you use direct binding. There’s also no way to directly bind a button press to turn on or toggle the light—dimming and hold to turn off is what you get.

To add more functionality you have to use something external; a Hue Bridge or Home Assistant with a Zigbee dongle works, but I wanted to use Elixir.

Communicating with MQTT in Elixir

The first thing we need to do is figure out is how to receive MQTT messages and how to send updates to Zigbee devices.

Connecting and subscribing to changes

I found the tortoise311 library that implements an MQTT client and it was quite pleasant to use.

First we’ll start a Tortoise311.Connection in our main Supervisor tree:

{Tortoise311.Connection,
 [
   # Remember to generate a unique id if you want to connect multiple clients
   # to the same MQTT service.
   client_id: :my_unique_client_id,
   # They don't have to be on the same server.
   server: {Tortoise311.Transport.Tcp, host: "localhost", port: 1883},
   # Messages will be sent to `Haex.MqttHandler`.
   handler: {Haex.MqttHandler, []},
   # Subscribe to all events under `zigbee2mqtt`.
   subscriptions: [{"zigbee2mqtt/+", 0}]
 ]},

I’ll also add Phoenix PubSub to the Supervisor, which we’ll use to propagate MQTT messages to our automation:

{Phoenix.PubSub, name: Haex.PubSub},

When starting Tortoise311.Connection above we configured it to call the Haex.MqttHandler whenever an MQTT message we’re subscribing to is received. Here we’ll simply forward any message to our PubSub, making it easy for anyone to subscribe to any message, wherever they are:

defmodule Haex.MqttHandler do
  use Tortoise311.Handler
  alias Phoenix.PubSub

  def handle_message(topic, payload, state) do
    payload = Jason.decode!(payload)
    PubSub.broadcast!(Haex.PubSub, Enum.join(topic, "/"), {:mqtt, topic, payload})
    {:ok, state}
  end
end

Then in our automation (which in my automation system is a regular GenServer) we can subscribe to the events the Tap Dial creates:

defmodule Automation.TapDialExample do
  use GenServer
  alias Phoenix.PubSub

  @impl true
  def init(_opts) do
    # `My tap dial` is the name of the tap dial in zigbee2mqtt.
    PubSub.subscribe(Haex.PubSub, "zigbee2mqtt/My tap dial")
    {:ok, %{}}
  end

  @impl true
  def handle_info({:mqtt, _topic, payload}, state) do
    dbg(payload)
    {:noreply, state}
  end
end

If everything is setup correctly we should see messages like these when we operate the Tap Dial:

payload #=> %{
  "action" => "button_1_press_release",
  ...
}

payload #=> %{
  "action" => "dial_rotate_right_step",
  "action_direction" => "right",
  "action_time" => 15,
  "action_type" => "step",
  ...
}

Controlling devices

To change the state of a device we should send a json payload to the “set” topic. For example, to turn off a light named My hue light we should send the payload {"state": "OFF"} to zigbee2mqtt/My hue light/set.

Here’s a function to send payloads to our light:

def set(payload) do
  Tortoise311.publish(
    # Important that this id matches the `client_id`
    # we gave to Tortoise311.Connection.
    :my_unique_client_id,
    "zigbee2mqtt/My hue light/set",
    Jason.encode!(payload)
  )
end

Button presses

With the MQTT communication done, we can start writing some automations.

Normal press

Here’s how we can toggle the light on/off when we click the first button on the dial in our GenServer:

def handle_info({:mqtt, _topic, %{"action" => "button_1_press_release"}}, state) do
  set(%{state: "TOGGLE"})
  {:noreply, state}
end

(Remember that we subscribed to the "zigbee2mqtt/My tap dial" topic during init.)

Hold

You can also hold a button, which generates a hold and a hold_release event. Here’s how to use them to start moving through the hues of a light when you hold down a button and stop when you release it.

def handle_info({:mqtt, _topic, %{"action" => "button_3_hold"}}, state) do
  set(%{hue_move: 40, color: %{saturation: 100}})
  {:noreply, state}
end

def handle_info({:mqtt, _topic, %{"action" => "button_3_hold_release"}}, state) do
  set(%{hue_move: 0})
  {:noreply, state}
end

Double clicking

How about double clicking?
You could track the timestamp of the presses in the GenServer state and check the duration between them to determine if it’s a double click or not; maybe something like this:

def handle_info({:mqtt, _topic, %{"action" => "button_2_press_release"}}, state) do
  double_click_limit = 350

  now = DateTime.utc_now()

  if state[:last_press] &&
       DateTime.diff(now, state[:last_press], :millisecond) < double_click_limit do
    # If we double clicked.
    set(%{color: %{hue: 60}})
    {:noreply, Map.delete(state, :last_press)}
  else
    # If we single clicked.
    set(%{color: %{hue: 180}})
    {:noreply, Map.put(state, :last_press, now)}
  end
end

This however executes an action on the first and second click. To get around that we could add a timeout for the first press by sending ourselves a delayed message, with the downside of introducing a small delay for single clicks:

def handle_info({:mqtt, _topic, %{"action" => "button_2_press_release"}}, state) do
  double_click_limit = 350

  now = DateTime.utc_now()

  if state[:last_press] &&
       DateTime.diff(now, state[:last_press], :millisecond) < double_click_limit do
    set(%{color: %{hue: 180}})

    # The double click clause is the same as before except we also remove `click_ref`
    # to signify that we've handled the interaction as a double click.
    state =
      state
      |> Map.delete(:last_press)
      |> Map.delete(:click_ref)

    {:noreply, state}
  else
    # When we first press a key we shouldn't execute it directly,
    # instead we send ourself a message to handle it later.
    # Use `make_ref` signify which press we should handle.
    ref = make_ref()
    Process.send_after(self(), {:execute_single_press, ref}, double_click_limit)

    state =
      state
      |> Map.put(:last_press, now)
      |> Map.put(:click_ref, ref)

    {:noreply, state}
  end
end

# This is the delayed handling of a single button press.
def handle_info({:execute_single_press, ref}, state) do
  # If the stored reference doesn't exist we've handled it as a double click.
  # If we press the button many times (completely mash the button) then
  # we might enter a new interaction and `click_ref` has been replaced by a new one.
  # This equality check prevents such a case, allowing us to only act on the very
  # last press.
  # This is also useful if we in the future want to add double clicks to other buttons.
  if state[:click_ref] == ref do
    set(%{color: %{hue: 60}})
    {:noreply, Map.delete(state, :click_ref)}
  else
    {:noreply, state}
  end
end

You can generalize this concept to triple presses and beyond by keeping a list of timestamps instead of the singular one we use in :last_press, but I personally haven’t found a good use-case for them.

Dimming

Now, let’s see if we can create a smooth dimming functionality. This is surprisingly problematic but let’s see what we can come up with.

Rotating the dial produces a few different actions:

dial_rotate_left_step
dial_rotate_left_slow
dial_rotate_left_fast
dial_rotate_right_step
dial_rotate_right_slow
dial_rotate_right_fast
brightness_step_up
brightness_step_down

Let’s start with dial_rotate_* to set the brightness_step attribute of the light:

def handle_info({:mqtt, _topic, %{"action" => "dial_rotate_" <> type}}, state) do
  speed = rotate_speed(type)
  set(%{brightness_step: speed})
  {:noreply, state}
end

defp rotate_speed("left_" <> speed), do: -rotate_speed(speed)
defp rotate_speed("right_" <> speed), do: rotate_speed(speed)
defp rotate_speed("step"), do: 10
defp rotate_speed("slow"), do: 20
defp rotate_speed("fast"), do: 45

This works, but the transitions between the steps aren’t smooth as the light immediately jumps to a new brightness value.

With a transition we can smooth it out:

# I read somewhere that 0.4 is standard for Philips Hue.
set(%{brightness_step: speed, transition: 0.4})

It’s actually fairly decent (when the stars align).

As an alternative implementation we can try to use the brightness_step_* actions:

def handle_info(
      {:mqtt, _topic,
       %{
         "action" => "brightness_step_" <> dir,
         "action_step_size" => step
       }},
      state
    ) do
  step =
    case dir do
      "up" -> step
      "down" -> -step
    end

  # Dimming was a little slow, adding a factor speeds things up.
  set(%{brightness_step: step * 1.5, transition: 0.4})
  {:noreply, state}
end

This implementation lets the tap dial itself provide the amount of steps and I do think it feels better than the dial_rotate_* implementation.

Note that this won’t completely turn off the light and it’ll stop at brightness 1. We can instead provide brightness_step_onoff: step to allow the dimmer to turn on and off the light too.

Other types of transitions

One of the reasons I wanted a custom implementation was to be able to do other things with the rotary dial.

For example, maybe I’d like to alter the hue of light by rotating? All we have to do is set the hue instead of the brightness:

set(%{hue_step: step * 0.75, transition: 0.4})

(This produces a very cool effect!)

Another idea is to change the volume by rotating. Here’s the code that I use to control the volume of our kitchen speakers (via Home Assistant, not MQTT):

rotate: fn step ->
  # A step of 8 translates to a volume increase of 3%
  volume_step = step / 8 * 3 / 100

  # Clamp volume to not accidentally set a very loud or silent volume.
  volume =
    # HAStates stores the current states in memory whenever a state is changed.
    (HAStates.get_attribute(kitchen_player_ha(), :volume_level, 0.2) + volume_step)
    |> Math.clamp(0.05, 0.6)

  # Calls the `media_player.volume_set` action.
  MediaPlayer.set_volume(kitchen_player_ha(), volume)
  # Prevents a possible race condition where we use the old volume level
  # stored in memory for the next rotation.
  HAStates.override_attribute(kitchen_player_ha(), :volume_level, volume)
end

A use-case: the boys bedroom

We’ve got a bunch of lights in the boys bedroom that we can control and it’s a good use-case for a device such as the Tap Dial.

Lights to control

These are the lights we can control in the room:

A ceiling light with color ambiance
A window light with white ambiance
A floor lamp with white ambiance
Night lights for both Loke and Isidor, with color ambiance
A lava lamp for Loke, connected to a smart plug

(Yes, I need to get a lava light for Isidor too. They’re awesome!)

The window light isn’t controlled by the tap dial and there are other automations that controls circadian lighting for most of the lights.

Use Zigbee direct binding

I’m opting to use direct binding because of two reasons:

Direct binding allows us to dim the light even if the smart home server is down.
Despite my efforts, the dimming automation has some latency issues.

Even though it overrides the hold functionality I think direct binding for lights is the way to go.

The functionality

These are the functions for the tap dial in the boys room:

Rotate: Dim brightness of ceiling light (direct binding)
Hold any: Turns off the ceiling light (direct binding)
Click 1: Toggle ceiling light on/off
Double click 1: Toggle max brightness for ceiling light on/off
Click 2: Each click goes through different colors for the ceiling light
Click 3: Toggle floor lamp on/off
Double click 3: Toggle Isidor’s night light on/off
Hold 3: Loop through the hue of Isidor’s night light
Click 4: Toggle Loke’s lava lamp on/off
Double click 4: Toggle Loke’s night light on/off
Hold 4: Loop through the hue of Loke’s night light

There’s many different ways you can design the interactions and I may switch it up in the future, but for now this works well.

A generalized tap dial controller

The code I’ve shown you so far has been a little simplified to explain the general approach. As I have several tap dials around the house I’ve made a general tap dial controller with a more declarative approach.

For example, here’s how the tap dial in the boys room is defined:

TapDialController.start_link(
  device: boys_room_tap_dial(),
  scene: 0,
  rotate: fn _step ->
    # This disables the existing circadian automation.
    # I found that manually disabling it is more reliable than trying to
    # detect external changes over MQTT as messages may be delayed and arrive out of order.
    LightController.set_manual_override(boys_room_ceiling_light(), true)
  end,
  button_1: %{
    click: fn ->
      Mqtt.set(boys_room_ceiling_light(), %{state: "TOGGLE"})
    end,
    double_click: fn ->
      # This function compares the current light status and sets it to 100%
      # or reverts back to circadian lighting (if setup for the light).
      HueLights.toggle_max_brightness(boys_room_ceiling_light())
    end
  },
  button_2: %{
    click: fn state ->
      # The light controller normally uses circadian lighting to update
      # the light. Setting manual override pauses circadian lighting,
      # allowing us to manually control the light.
      LightController.set_manual_override(boys_room_ceiling_light(), true)
      # This function steps through different light states for the ceiling light
      # (hue 0..300 with 60 intervals) and stores it in `state`.
      next_scene(state)
    end
  },
  button_3: %{
    click: fn ->
      Mqtt.set(boys_room_floor_light(), %{state: "TOGGLE"})
    end,
    double_click: fn ->
      Mqtt.set(isidor_sleep_light(), %{state: "TOGGLE"})
    end,
    hold: fn ->
      Mqtt.set(isidor_sleep_light(), %{hue_move: 40, color: %{saturation: 100}})
    end,
    hold_release: fn ->
      Mqtt.set(isidor_sleep_light(), %{hue_move: 0})
    end
  },
  button_4: %{
    click: fn ->
      Mqtt.set(loke_lava_lamp(), %{state: "TOGGLE", brightness: 254})
    end,
    double_click: fn ->
      Mqtt.set(loke_sleep_light(), %{state: "TOGGLE"})
    end,
    hold: fn ->
      Mqtt.set(loke_sleep_light(), %{hue_move: 40, color: %{saturation: 100}})
    end,
    hold_release: fn ->
      Mqtt.set(loke_sleep_light(), %{hue_move: 0})
    end
  }
)

I’m not going to go through the implementation of the controller in detail. Here’s the code you can read through if you want:

defmodule Haex.Mqtt.TapDialController do
  use GenServer
  alias Haex.Mqtt
  alias Haex.Mock
  require Logger

  @impl true
  def init(opts) do
    # This allows us to setup expectations and to collect what messages
    # the controller sends during unit testing.
    if parent = opts[:parent] do
      Mock.allow(parent, self())
    end

    device = opts[:device] || raise "Must specify `device`, got: #{inspect(opts)}"

    # Just subscribes to pubsub under the hood.
    Mqtt.subscribe_events(device)

    state =
      Map.new(opts)
      |> Map.put_new(:double_click_timeout, 350)

    {:ok, state}
  end

  def start_link(opts) do
    GenServer.start_link(__MODULE__, opts)
  end

  @impl true
  def handle_info({:mqtt, _topic, payload}, state) do
    case parse_action(payload) do
      {:button, button, fun} ->
        # We specify handlers with `button_3: %{}` specs.
        case fetch_button_handler(button, state) do
          {:ok, spec} ->
            # Dispatch to action handlers, such as `handle_hold` and `handle_press_release`.
            fun.(spec, state)

          :not_found ->
            {:noreply, state}
        end

      {:rotate, step} ->
        case fetch_rotate_handler(state) do
          {:ok, cb} ->
            call_handler(cb, step, state)

          :not_found ->
            {:noreply, state}
        end

      :skip ->
        {:noreply, state}
    end
  end

  def handle_info({:execute_single_press, ref, cb}, state) do
    # Only execute the callback for the last action.
    if state[:click_ref] == ref do
      call_handler(cb, Map.delete(state, :click_ref))
    else
      {:noreply, state}
    end
  end

  defp handle_press_release(spec, state) do
    single_click_handler = spec[:click]
    double_click_handler = spec[:double_click]

    cond do
      double_click_handler ->
        now = DateTime.utc_now()

        valid_double_click? =
          state[:last_press] &&
            DateTime.diff(now, state[:last_press], :millisecond) < state.double_click_timeout

        if valid_double_click? do
          # Execute a double click immediately.
          state =
            state
            |> Map.delete(:last_press)
            |> Map.delete(:click_ref)

          call_handler(double_click_handler, state)
        else
          # Delay single click to see if we get a double click later.
          ref = make_ref()

          Process.send_after(
            self(),
            {:execute_single_press, ref, single_click_handler},
            state.double_click_timeout
          )

          state =
            state
            |> Map.put(:last_press, now)
            |> Map.put(:click_ref, ref)

          {:noreply, state}
        end

      single_click_handler ->
        # No double click handler, so we can directly execute the single click.
        call_handler(single_click_handler, state)

      true ->
        {:noreply, state}
    end
  end

  defp handle_hold(spec, state) do
    call_handler(spec[:hold], state)
  end

  defp handle_hold_release(spec, state) do
    call_handler(spec[:hold_release], state)
  end

  defp call_handler(nil, state) do
    {:noreply, state}
  end

  defp call_handler(handler, state) do
    # If a callback expects one argument we'll also send the state,
    # otherwise we simply call it.
    case Function.info(handler)[:arity] do
      0 ->
        handler.()
        {:noreply, state}

      1 ->
        {:noreply, handler.(state)}

      x ->
        Logger.error(
          "Unsupported cb arity `#{x}` for #{state.device} tap dial expecting 0 or 1 args"
        )

        {:noreply, state}
    end
  end

  defp call_handler(nil, _arg1, state) do
    {:noreply, state}
  end

  defp call_handler(handler, arg1, state) do
    case Function.info(handler)[:arity] do
      1 ->
        handler.(arg1)
        {:noreply, state}

      2 ->
        {:noreply, handler.(arg1, state)}

      x ->
        Logger.error(
          "Unsupported cb arity `#{x}` for #{state.device} tap dial  expecting 1 or 2 args"
        )

        {:noreply, state}
    end
  end

  defp parse_action(%{"action" => "brightness_step_" <> dir, "action_step_size" => step}) do
    step =
      case dir do
        "up" -> step
        "down" -> -step
      end

    {:rotate, step}
  end

  defp parse_action(%{"action" => action}) do
    case Regex.run(~r/button_(\d)_(\w+)/, action, capture: :all_but_first) do
      [button, "press_release"] ->
        {:button, String.to_integer(button), &handle_press_release/2}

      [button, "hold"] ->
        {:button, String.to_integer(button), &handle_hold/2}

      [button, "hold_release"] ->
        {:button, String.to_integer(button), &handle_hold_release/2}

      _ ->
        :skip
    end
  end

  defp parse_action(_action) do
    Logger.debug("Skip fallback tap dial action: #{inspect(action)}")
    :skip
  end

  defp fetch_button_handler(button, state) do
    spec = state["button_#{button}" |> String.to_atom()]

    if spec do
      {:ok, Map.put(spec, :button, button)}
    else
      :not_found
    end
  end

  defp fetch_rotate_handler(state) do
    if spec = state[:rotate] do
      {:ok, spec}
    else
      :not_found
    end
  end
end

I'll only buy devices with GrapheneOS

2025-09-05T05:53:47+00:00

Cops say criminals use a Google Pixel with GrapheneOS — I say that’s freedom

Calvin Wankhede

We’re in a dark time period right now.

Authoritarianism is on the rise throughout the globe. Governments wants to monitor your social media accounts so they can make you disappear if you engage in wrongthink such as opposing wars or genocide. This is worsened by misguided laws like Chat control that would mandate scanning of all digital communication, exposing any wrongthink in your “private messages”.

A rational reaction to threats is to “shell up” and try to make your personal space safe. This is increasingly difficult as the devices you buy often doesn’t feel like yours anymore. Files are moved to the cloud without your knowledge; companies are doing everything they can to prevent you from blocking the ads they’re shoving in everywhere; and everything you do will soon be ingested by an LLM in order to present personalized slop to you (even your passwords and screenshots of any nasty porn habits you may have).

While you can avoid most of this crap on computers (try Linux if you haven’t) the situation on smartphones is much bleaker. Apple has been blocking sideloading apps for years and Google will soon follow by only allowing apps from verified developers to be installed on Android, preventing you from installing what you want.

(They claim it’s “for security” but it’s obvious they’re doing this to protect their income stream. Apple takes a ridiculous 30% cut from all sales in their walled garden and Google hates the ability to strip out their ads.)

I like the idea of a “dumb phone” but I unfortunately need and want apps on my phone (I consider banking and authentication apps essential to surviving in the modern world, and sometimes you must run an Android or iOS app). A “degoogled” Android-compatible operating system is the answer I see, with GrapheneOS as the exceptional standout.

The big dragons recognize this as for example Samsung removes bootloader unlocking and the EU age verification app may ban Android systems not licensed by Google. In true Streisand fashion this only makes me more motivated to fight back.

GrapheneOS works and it’s convenient

Installing GrapheneOS on the Pixel Tablet.

When people talk about GrapheneOS they will understandably focus on the privacy and security aspect. I’ll go into it a later but I think it’s important to first dispel the idea that GrapheneOS is only for the hardcore tech savvy user or that you’ll have to sacrifice a lot of functionality.

While GrapheneOS isn’t quite as simple as stock Android (I had to tweak a few settings to get some apps working) the experience has been very smooth.

Installation

The installation was straightforward and worked without a hitch:

Plug in the phone or tablet via an USB
Launch Chrome (or chromium)
Follow the instructions and click some buttons

App compatibility

Some of the apps I’ve got installed. I use the Kvaesitso launcher.

Apps are also just as easy to install as on stock Android. I’ve installed most of the apps from the Play Store just as I would’ve on stock and they work just fine.

So far I’ve had a grand total of two issues with any apps I’ve tried:

At first I couldn’t copy BankID over from my old phone.

I had to tweak some permissions and disable some of the location privacy features of GrapheneOS before the phones recognized each other. Presumably there’s some security measure there so that you can only copy it if the phones are nearby.

I had to play with some of these location settings to be able to copy BankID from my old phone to the new one.
The AI detection feature of MacroFactor refused to work.

MacroFactor is a food tracking app where you can take a photo and it’ll try to infer the food from the picture but uploading the photo simply failed. It’s a pretty cool feature and I instead use the app Cronometer that has the same functionality.

MacroFactor uses Play Integrity which may in some cases break certain apps. I’ve got a few other apps that also uses Play Integrity but they don’t have any issues.

I was worried that I’d run into issues with the banking apps as I know there are some banking apps that have issues, but all the Swedish banking apps I’ve tried work well.

You can of course install apps from other sources such as F-Droid, Accrescent, Obtanium, or manually as well.

No bloatware

Finally, I love that there’s no bloatware bullshit on GrapheneOS. There are no shitty vendor specific apps that you cannot uninstall and it isn’t trying to trick you into installing stupid games via dark patterns. The downside is that GrapheneOS doesn’t come with a lot of customization and lets you install apps for that yourself.

In short, it feels like with GrapheneOS you’re in control, not some mega corporation.

The best privacy & security in a modern phone

While other Android compatible distributions such as CalyxOS and LineageOS all mention privacy and security as benefits they’re nothing like GrapheneOS. In some cases—as with CalyxOS where security updates have seen significant delays—they may provide even less security compared to stock Android.

Everything I’ve read suggests that GrapheneOS takes security and privacy very seriously. I feel that sometimes they may take a too extreme stance but I can respect that, despite being overkill for the threat levels I care about.

See for example this comparison of Android-based Operating Systems.

What about Apple then? Aren’t they great at privacy and security? While I’m sure they’ll respect your privacy more than Google, I just can’t trust a company that shoves ads into their wallet app.

Pixel devices, the big drawback with GrapheneOS

It would’ve been great to have more choices. If I only looked at hardware I might have gotten the Fairphone 5 as I like the idea of repairability, ethically sourced components, and a phone made in the EU. I also like the idea of a smaller phone and a Flip phone would’ve been great. Or maybe a really cheap phone (or tablet) as I don’t care that much about performance and could save some money.

But alas, GrapheneOS only support Pixel devices (for now). There’s a handful of phones to choose from but only a single tablet.

I guess the best way to degoogle right now is to buy from Google… So I got the Pixel 9a for myself and the Pixel Tablet for our family. (Admittedly, they’ve been pretty great.)

Software is more important than hardware

I’ve had an interesting shift when I evaluate mobile devices; instead of comparing phones primarily by hardware I prioritize the software on the phone.

Today, more than ever, hardware upgrades in new phones provide diminishing returns for ever increasing prices. There’s little practical difference between a new phone and a phone from a few years ago and savvy people can save a lot of money by simply avoiding the constant stream of new releases.

Before I bought the Pixel 9a I used the Fairphone 4 for almost 4 years, and it was performing just fine! If I hadn’t gotten the urge of trying out GrapheneOS I would’ve still be happy with the Fairphone hardware (which was a bit underpowered already at release).

Software on the other hand is more important than ever and for me it’s what makes or breaks a phone today.

The right software will protect your privacy and help keep your device secure, while the wrong software will fill your phone with uninstallable bloatware and cripple performance after system updates (if they deign to provide them).

For example, I’ve used a Galaxy Tab A7 Lite as a dashboard for my smart home for a while and it worked great. Then I installed an update and it suddenly became extremely slow, so slow that you barely could interact with the UI without punching the damn device. Even though the hardware is great, Samsung crippled the device for no reason.

With the right software your device works for you, not against you. It’s not a lot to ask for, yet in the modern day that’s very rare indeed, and it’s why I’ll only be buying mobile devices supported by GrapheneOS for the foreseeable future.

Ditching Sonos for Music Assistant

2025-06-04T14:04:31+00:00

My general advice for life is: be a good person, and care for the people around you. And follow this one very specific rule: avoid vendor lock-in.

Sean Boots Rule number one: Avoid vendor lock-in

I’ve always wondered how to setup a sound systems around the house that you can control from your devices, such as your phone. To get a working setup it seemed you had to embrace vendor lock-in; either by committing to an entire ecosystem such as Sonos, or by relying on a service like Spotify and buying amplifiers that supports their particular integration (such as Spotify Connect).

When I wanted to replace and upgrade our old Sonos speaker I did som research and I found a promising alternative: it’s called Music Assistant and it’s great.

The Music Assistant dashboard.

The woes of Sonos

We’ve had a Sonos speaker in our kitchen for more than a decade. At first I was very happy with it; the speaker was easy to use, it integrated well with Spotify, and despite being a single fairly cheap speaker the sound was pretty good.

But gradually the experience got worse:

The speaker sometimes refused to play songs via Spotify.
We couldn’t connect to the speaker via the Sonos app (having to unplug the speaker and pray to the Sonos god that it would be enough to fix it).
Playback randomly paused.
The speaker lost WIFI connection, reconnecting after a while.
Finally, the radio integration stopped working altogether (this is critical for my girlfriend who always listens to the radio).

It could be worse—at least our speaker wasn’t bricked and we (supposedly) dodged a bunch of other issues by never upgrading to the new app.

The new setup

Use Music Assistant as the central controller for streaming music and radio to different players and speakers.
Setup an Arylic A50+ amplifier that Music Assistant can control.

Together with a pair of speakers it replaces the Sonos in the kitchen.
Connect Music Assistant with Home Assistant to control playback via our smart-home dashboard and automations.
Setup more players for Music Assistant to control.

What is Music Assistant and why is it awesome?

Music Assistant is a service that acts as a hub that connects different providers and players, letting you control the sound in your home from one central location.

Image showing how Music Assistant bridges different sources with different players. Taken from this Home Assistant blog post.

So you could have this kind of setup and let Music Assistant connect them together in whatever way you wish, including multi-room setups (if the players are from the same ecosystem, such as Airplay or Squeezebox):

Provider		Player
Spotify		Sonos
Audible		Chromecast
Radio	→	Media player in Home Assistant
Plex		Streaming amplifier (Squeezebox)
Local storage		Computer with Linux (Squeezebox)

Here’s a few reasons why I think Music Assistant is awesome:

Freedom from the limitations of one ecosystem.
Can mix and match music from local storage and Spotify in the same playlist.
One place to control all your speakers of varying types and connections.
Integrates well with Home Assistant.

How to set it up

Install Music Assistant

I host my homelab things using docker compose and it was as simple as:

services:
  music-assistant-server:
    image: ghcr.io/music-assistant/server:latest
    container_name: music-assistant-server
    restart: unless-stopped
    # Network mode must be set to host for MA to work correctly
    network_mode: host
    volumes:
      - ./music-assistant-server/data:/data/
    # privileged caps (and security-opt) needed to mount
    # smb folders within the container
    cap_add:
      - SYS_ADMIN
      - DAC_READ_SEARCH
    security_opt:
      - apparmor:unconfined
    environment:
      - LOG_LEVEL=info

  # And home assistant and other things.

Add providers

A provider is a source of music. There’s a bunch of them but at the moment I only use a few:

The Spotify provider for example should automatically sync all Spotify playlists into Music Assistant and allows you to search and play any song on Spotify.

Radio stations from RadioBrowser won’t show up automatically. You first have to find them under the Browse tab and add them to the library, then they’ll appear in the Radio tab.
Add players

We need players to play our music, here’s what I currently use:

The players should be automatically added as long as they have a matching provider enabled.

Quite a few different providers are supported. I could even add our Sonos speaker as a player and we managed to once more listen to the radio on it. Rejoice!

Open-source music management—particularly on Linux—has a reputation of being notoriously troublesome. But I’ve gotta say, Music Assistant was simple to setup and it works well (except issues with some players that I’ll get to shortly).

Trying out different players

I was fairly lost in what kind of amplifier and music player I should get.

There’s a lot of options out there but I was worried about paying a lot of money for something I wasn’t sure it would integrate well into my smart home setup. Here’s a few options I’ve tried:

Sonos

The Sonos speaker has found new life in our washing room.

It’s pretty funny, the Sonos speaker works better with Music Assistant than with the Sonos app. The radio completely stopped working via the Sonos app, while I can use Music Assistant to play the radio on the Sonos speaker.

The speaker might still disconnect or stop playback at odd times but it’s good enough to raise the mood in the washing room.

Squeezelite on Linux

Our living room setup with a TV, game consoles, speakers, a dumb amplifier, and a computer running Void Linux.

I hate modern smart TVs with a passion so to stream we use a computer running Linux, connected to a dumb amplifier with some speakers. It works well but it makes it a bit more cumbersome to play music.

By installing Squeezelite the computer acts as a squeezebox client, effectively transforming it into a smart player for Music Assistant and Home Assistant to stream music to.

A HifiBerry player

The HifiBerry AMP2 on top of a Raspberry Pi 3, acting as the amplifier and smart music controller. All you need is to connect the passive speakers.

As I had a Raspberry Pi lying around it made sense to try the HifiBerry AMP2 that transforms the Pi into a surprisingly capable amplifier and smart music controller. For simplicity I decided to start with their operating system HifiBerryOS that hopefully should “just work” and be open enough for me to manually fix things if needed.

While it works very well as a Spotify Connect device or to play over Bluetooth I had issues with it acting as a Squeezelite or Airplay client as the volume was super low when I tried to stream to it from Music Assistant.

It might be a software issue with HifiBerryOS but I haven’t had the energy to debug it or try other OS versions. Maybe I’ll revisit it when I want to outfit another room with speakers.

Arylic A50+

I was planning to use the HifiBerry to power two new speakers in the ceiling in the kitchen to replace the Sonos. But I got stressed out by the HifiBerry not working properly and the kitchen renovation was looming ever closer so I bought the Arylic A50+, hoping that it would work better with Music Assistant.

The device supports both Airplay and Squeezebox like the HifiBerry but again there were some issue with the volume being very low. I don’t know if both devices just happen to have similar bugs, if there’s a bug with Music Assistant, or if it’s some weird compatibility issue.

Sigh.

But there’s another way to make it work; the Arylic has an excellent Home Assistant integration and if you go that way then Music Assistant can use the Arylic as a player properly. You need the LinkPlay integration in Home Assistant and then enable the Home Assistant integration in Music Assistant.

(I tried the same with the HifiBerry integration but for some reason the HifiBerry media player exposed from Home Assistant didn’t show up in Music Assistant.)

Home Assistant integration

Music Assistant integrates well with Home Assistant. Setup is straightforward:

Add the Music Assistant integration in Home Assistant:

This will expose all players in Music Assistant to Home Assistant (such as the Squeezebox players running on Linux).
Enable the Home Assistant plugin in Music Assistant:

This will expose all media players in Home Assistant to Music Assistant (such as the Arylic or the Home Assistant Voice Preview Edition).

With this setup you can setup Home Assistant actions to start a particular radio station, add a media player card to start/stop playback, or simply give Music Assistant access to more players.

In Home Assistant how do you…

Play the P4 Norrbotten radio station?

action: music_assistant.play_media
target:
  entity_id: media_player.kitchen
data:
  media_id: P4 Norrbotten

Play the To Hell and Back track?

action: music_assistant.play_media
target:
  entity_id: media_player.kitchen
data:
  media_id: To Hell and Back
  media_type: track

Play the kpop playlist?

action: music_assistant.play_media
target:
  entity_id: media_player.kitchen
data:
  media_id: kpop
  media_type: playlist

Play the kpop playlist randomized?

action: media_player.shuffle_set
target:
  entity_id:
    - media_player.kitchen
data:
  shuffle: true

action: music_assistant.play_media
target:
  entity_id: media_player.kitchen
data:
  media_id: kpop
  media_type: playlist
  enqueue: replace

You get the new music_assistant.play_media action but otherwise you control the media players just as the other media player entities in Home Assistant.

It’s not perfect

Music Assistant is a fairly young open source project so minor bugs are to be expected. There are also two larger feature that I miss:

I’d like to have access to my library even when I’m away from home. Maybe an Android app with native volume controls, notifications, and support for offline listening?
A better widget for Home Assistant.

The mini media player card.

For basic sound controls in the kitchen I use the Mini Media Player card but I’d like a better way to filter through playlists and music via the Home Assistant Lovelace UI. I currently embed the Music Assistant dashboard itself via an iframe but the UI is a bit too clunky for the size of my tablet.

What’s next?

Still, I must admit, I’m stoked about finding a smarter way to control music throughout our house and I’m searching for an excuse to expand the setup in the future. Here are some ideas I have:

Speakers in the kid’s room to play music or audio books before they go to sleep.
More music in my exercise space (it kind of works if I increase the volume of my office speakers, but it’s not ideal).
A proper Hi Fi setup for true music enjoyment somewhere in the house.

Despite some integration issues and us not using Music Assistant to it’s fullest potential it has still improved our setup in a major way.

Why I'm back to Whoop (for now)

2025-06-02T11:55:00+00:00

I recently started to subscribe to Whoop again after I canceled it around a year ago. I was partly dissatisfied with my Garmin watch as a fitness and health tracker and I also wanted a new tech device to tinker with.

The plan was to write a short post about what I like and don’t like about Whoop but as usual I’m struggling with writing shorter posts.

If I had more time I would write a shorter letter.

Attributed to Blaise Pascal

The TLDR is that Whoop is still expensive and imperfect; yet it’s the most helpful smart device I’ve used and a Whoop in your underwear is the best way to track your heart rate while hugging spandex-wearing adults.

A brief history of my experiences with smart devices

I’m not an elite athlete, not even close; I’m just a programmer who struggles to stay active. As I also like to play with tech I’ve tried out various smart devices in the hopes that they can help me to live a healthier life (with various levels of success).

Here’s the devices I’ve used, in purchase order:

Fitbit, -2020

I had some smartband from Fitbit that I liked. When that bugged out I bought the Fitbit Versa, with a square display.

Oura ring, 2020-2021

I wanted to track my sleep better, so I bought a ring. It worked well.

Garmin Venu Sq, 2020-2023

The Fitbit kept disconnecting, so I abandoned it for a Garmin.

Oura ring Gen 3, 2021-2023

I had to recharge the ring all the time so I upgraded to the newer version. (The battery of the new ring also deteriorated and I stopped using it when I had to charge it every 1–3 days.)

Withings Body+, 2022-

I wanted to track my weight so I bought a smart scale.

Polar Verity Sense, 2022-2023

I can’t track my Submission Grappling training with a watch or a ring, so I bought a heart rate monitor you put on the bicep. It was okay.

Fossil Gen 6 Wellness Edition, 2022

Maybe I should try a real smartwatch with lots of smart features…? I use Android so maybe a watch with WearOS is good?

Jokes on me, WearOS was garbage and having to charge the watch every day is a nightmare. I went back to the Garmin.

Garmin vivosmart 5, 2023-2024

I wasn’t happy with the Garmin Venu Sq (can’t remember why) and disappointed with smart watches I figured a simple smart band would suffice.

Whoop 4.0, 2023-2024

The battery of my Oura was failing again so I tried Whoop for a year. Tracking Submission Grappling with a device in my underwear is so next level!

Garmin Instinct 2X Solar, 2024-

Charging the devices got annoying; I found the Garmin Instinct you only charge once a month and it comes with a flashlight.

Seriously, you haven’t truly lived before you’ve had a flashlight on your watch—it’s glorious. (Jokes aside, it’s awesome.)

Eight Sleep Pod 4, 2024

Sleep is important so I tried (and returned) a ludicrously expensive smart mattress.

Whoop MG, 2025

I was feeling down and I needed something to help me get back to prioritizing fitness and health, and I just happened to check back on Whoop right when Whoop MG was released…

So I threw financial responsibility out the window and ordered the MG on release day.

Gosh, I’ve been good about not changing my phone that often but I didn’t realize I’ve wasted so much time and money on smart devices…

Anyway, I’m currently using the Garmin Instinct 2X Solar as a “don’t glance at my phone” device and Whoop as my fitness and health tracker, ignoring the Garmin’s health and fitness tracking features.

The point is to change behaviours

While it’s fun to play with new things, the main point of these smart devices is to (hopefully) help me change my behaviours in a positive way. It doesn’t matter if the device is super accurate or produces the most beautiful graphs God has created; if it doesn’t help me do things differently then the device is a failure.

Here are two examples:

My first Fitbit smartband was great.

It’s true that it was quite limited in what it could do, the tracking of steps/calories/steps/etc was wildly inaccurate, and it disconnected from my phone all the time making notifications completely unreliable.

However, it presented the daily steps/calories/steps as pretty bars on the screen—bars that I should fill over the course of the day—and that caused me to move more than I’d have done otherwise.

(This is a feature in most smartwatches today but nothing I’ve tried captured the feeling as well as my very first Fitbit device.)
The Garmin Instinct is useful, but not as a fitness or health device.

I think the watch is very nice; it’s got a fantastic battery life, it’s not bothering me when I sleep, I don’t have to reach for my phone to see if I have any notifications, and the flashlight is amazing.

It [the flashlight] is just super effin’ functional and useful day-to-day, with just as much utility as the flashlight on your phone (if not more, since your hands are still free).

DCRainmaker

The Garmin also has lots of various measurements (and with much more accuracy than my old Fitbit); I can see the daily steps; I can follow how my “body battery” is doing; I can track walks or runs very well (although I don’t run); and I can follow my stress and heart rate throughout the day…

But that doesn’t do anything for me. I have all these bars and graphs and circles on the watch that I should fill to meet my daily step count for example… But I just don’t. Maybe my neanderthal brain needs more colors or something.

The Garmin app is also not designed in a way to help me get motivated. Maybe it’s more geared towards runners or athletes that already train hard every day, instead of middle-aged programmers who need that extra push to get out there?

For whatever reason, as a device to improve my fitness and health, the Garmin is a failure.

Why I left Whoop last year

About a year ago I chose to not renew my Whoop subscription and I made a post on Reddit explaining why.

Here’s a quick summary of my issues with Whoop:

If I had the Whoop in my boxers it thinks I’m sleeping when I sit in front of the computer or lie in the sofa.
(This is still a big issue.)
No custom insights for the journal.
(Still nothing.)
The UI for the strength trainer portion of the app sucked.
(You can now add exercises after the training—a big step forward.)
It’s too expensive if all it provides is tracking for Submission Grappling.
(I realized I’m missing some of the other stuff.)

What made me change my mind?

When I quit Whoop I was in a pretty good place in my life; I was feeling good, I was training consistently, and I didn’t need external stimuli to keep going.

But things have been different recently. I’ve been struggling with depression, haven’t been able to get back to a regular training routine, and I feel that I need all help I can get to get back on track.

During the 10 months without Whoop I relied on my Garmin watch and I realized that the watch simply wasn’t helping me to improve my fitness or health the way I wanted from a smart device.

I looked at alternatives but in the end I couldn’t find an alternative that matched Whoop’s feature set, so here I am.

Whoop screwed over their customers

It was an interesting feeling to visit r/whoop after having placed my order and see it overrun by people extremely upset about how Whoop was treating their existing subscribers.

I agree that Whoop displayed some real corporate bullshit by telling people to pay an upgrade fee despite claiming for years that upgrades would be free (then walking back on the upgrade fee somewhat), claiming that the 6-month subscription requirement for new hardware was “a mistake on their blog”, and by breaking compatibility with the 4.0 bands.

Some people claim that Whoop broke the band compatibility intentionally but as I’ve experienced the same at work I think incompetence is more likely.

I don’t want to be constrained by the old design!

Programmer, before corporate disaster

It sucks but corporations screwing us over in various ways is more or less expected. This whole situation made me regret resubscribing to Whoop immediately, before letting the dust settle.

Thoughts on Whoop in 2025

Here are my first impressions after using the Whoop MG for almost a month after resubscribing.

Battery life is excellent

Some people don’t mind charging their devices a few times a week but I personally loath it. With the new Whoop and its battery life of ~2 weeks I can finally leave the battery pack when I go on my one week work trips and it’s super nice.

The app UI is great

Maybe it’s “just” pretty UI but I find Whoop’s presentation much more helpful than the rawer presentation that Garmin has.

For example I’ve always liked to look at sleep information ever since I started wearing an Oura ring and Whoop’s (recently redesigned) presentation is very good as it focuses on actionable metrics:

Whoop to the left focuses on metrics that I can change while Garmin to the right focuses on sleep stages that I have no idea how to influence.

I also think Whoop is immediately more useful than Garmin’s when you open it up:

Whoop’s landing page to the left and Garmin’s on the right.

I’m a sucker for pretty graphs and Whoop has a lot of them.

I have some gripes with the UI—I would like to be able to customize the home screen more for example—but overall I think Whoop’s app is a lot better designed and more useful than any alternative I’ve tried.

Whoop in the boxers

As I mentioned before, Whoop still thinks that I’m sleeping when I sit with Whoop in the boxers. Either before I go to bed, after I go to bed, and sometimes it thinks I’m napping when I’m sitting during the day.

Very annoying.

But they’re still a killer feature for me because it’s the best way to track Submission Grappling. Whoop is less accurate than the Polar bicep/chest straps but a biceps band or a chest strap sometimes gets in the way during training, while I’ve never noticed the Whoop in my boxers.

Submission grappling. A version of hugging where you try to strangle each other.

The Whoop 5.0 / MG also fits the 4.0 boxers well—lucky me as I have a bunch of the older 4.0 boxers. I’ve gotta admit, I like their boxers and I kept using them even after I canceled my subscription.

The Whoop MG in the 4.0 boxers to the left and the MG in the new boxers to the right.

I was skeptical to their new design with the “pods” but I think they’re an improvement as it’s a lot easier to add/remove the device while wearing the boxers, and if you remove the pod they’re just like regular boxers. The holders on my old 4.0 boxers have started to peel away and started to chafe but I think there’s less of a risk with the new design.

ECG

The ECG feature is why I went with Whoop MG instead of Whoop 5.0.

Outputs from Whoop’s ECG feature. It’s a little difficult to take an ECG as you need to stay very still—you can see where I moved too much in the top-right picture.

I’ve had a couple of episodes with chest pain where I’ve hurried to the hospital to get a check-up. They never showed anything out of the ordinary (it was ruled as “something muscular”) but the experience has left me worried.

If the ECG and background “Irregular Heart Rhytm” detection makes me relax a little (or if they do detect something) then I figured it’s worth the price jump from the 5.0 to the MG.

Whoop age

My “Whoop age” right after it unlocked after 3 weeks. You can see that I’ve been exercising way to little and that I’m slightly overweight.

I’ve seen Reddit warriors call the Whoop age metric a “gimmick” and dismiss it as just a combination of metrics available elsewhere.

But for me—a middle-aged programmer dad who’s struggling to exercise consistently—the Whoop age metric is a fantastic addition to Whoop as it gives me a pretty and actionable way to improve my overall health.

I already know that I need to lose weight and exercise more, but sometimes you need someone else to hit you with the reality before you internalize the problem and start doing something about it.

It’s too early to tell how useful the Whoop age metric ultimately ends up being but my first impression is very positive.

More measures

Whoop also comes with more “raw” measures that I glance at from time to time:

Body weight and body composition

Whoop now syncs with my Withings smart scale and I do need to lose weight; it’s nice to have it in the Whoop app so I don’t have to open up Withing’s app just to see my weight trend.
Steps

Again, I have (more accurate) step tracking in Garmin but it’s nice to have it all in one app. I try to hit a reasonable step goal and step counting—even if inaccurate—has made me try to move around more.
VO₂ MAX

It seems like an important metric but I’m not sure about it’s accuracy and it hasn’t caused me to change any behaviours. (I also need to calibrate it with a 15 minutes run. I haven’t been on a run the last decade…)
Blood pressure

I calibrated the blood pressure insights but I’m not sure how useful it is for me. Maybe it can act as an early indicator that my health is deteriorating but so far it’s just a pretty statistic.

Journaling and insights

The journal that correlates your behaviours with your recovery scores is an amazing feature and in theory this feature alone could carry a device such as Whoop by itself…

If it wasn’t for the fact that the usefulness tapers off hard as soon as you learn how the various behaviours affect your body. At the end of my last subscription I even turned off the journal as it didn’t provide any new information and filling it in only became a chore.

Right now I use it but I only track a handful of behaviours that I want to remind myself of. However, I’ll probably turn off the journal in a few months when the newness wears off again.

Bands

It was a really shitty move by Whoop to break backwards compatibility with the old bands. Granted, I don’t care that much about appearance so I never bought a lot of bands but I still want to switch between bands when they get wet after shower.

Where corporations fails the 3D printer community steps up to save the day. You can 3D print a whoop 5.0 / MG adapter to continue using your existing bands:

A 4.0 band together with my Whoop MG.

A 3D printed adapter making the 4.0 clasp compatible with a 5.0/MG device.

It’s not as secure as a proper 5.0/MG band and the old 4.0 battery doesn’t fit but it works well enough for regular usage (I don’t dare to swim with it).

I’ll probably buy another band anyway so I have another ECG-compatible clasp; possibly a colorful SportFlex band for when I swim with the kids.

Pricing

Whoop outdid themselves and the MG took something already expensive and made it even more expensive. While I don’t regret going with the more expensive option, the “Peak” plan (without Blood pressure and ECG) probably makes more sense for most people.

Still, if Whoop can help me improve my fitness or health—even in a small way—the cost is worth it for me.

Conclusion

Despite its faults and corporate bullshit, the Whoop is still my favorite smart device for fitness and health. I’ve tried to find alternatives but nothing has been as convenient or as helpful (or as expensive) as the Whoop.

But the jury is still out on how helpful Whoop will be for me this time and in a year I may have moved on to try something else.

Some VORON 0 mods

2026-04-27T15:25:12+00:00

I recently completed my VORON 0 build and I was determined to leave it as-is for a while and to start modding my VORON Trident…

So before embarking om my larger Trident modding journey I decided to work on the VORON 0 just a little bit more.

HEPA filter

With the Nevermore Micro V4 I had active carbon filtering but I also wanted a HEPA filter that would also provide negative air pressure to the printer. I found the Hepa filter by JNP for the VORON 0.1 and a mount for the VORON 0.2 that I installed.

For the fans I used two Noctua NF-A4x10 FLX fans and I spliced them together with the Nevermore filter, allowing the MCU to control all the filter fans together. It might have been better to buy the 5V versions and connect them to the 5V output to have them always on, but by then I had already ordered the other version. Oh well.

Back meshed panel

The small 5V fan for the Raspberry Pi was super loud and I wanted to replace it with something. Because the Raspberry Pi Zero doesn’t get that hot I removed the fan and replaced the back panel with a meshed variant, which I hope should provide enough airflow to keep the electronics cool.

(There are other variants with integrated fans if I realize this wasn’t enough.)

Modesty mesh

The wiring is super ugly and I stumbled upon the modesty mesh that hides the wires well from the sides. Not at all necessary but they make the printer a little prettier.

Full size panels

One thing that bothered me with the stock VORON 0.2 was the gaps between the tophat and the side panels and front door. I went looking for a mod with fill-sized panels and found the ZeroPanels mod.

Instead of magnets the printed parts clips into the extrusions pretty hard while still allowing you to pull them off when you want to. It works really well honestly.

The clips were slightly difficult to print but manageable.

I was looking at the BoxZero mod for a proper full-sized panels mod but I didn’t want to tear apart the printer and rebuild the belt path so I simply replaced the stock panels with full sized ones. This does leave some air gaps at the back and front of the printer right next to the belt that I simply covered with some tape:

Some tape to cover the gaps around the belts.

While the clips are good for panels you don’t remove that often, they’re too much to use for the front door. They have some magnetic clips you can use but I’m honestly perplexed on how to use them for good effect.

The standard VORON 0 handles don’t consider the extra 3mm the foam tape adds, leaving a gap that severely reduces the pulling force of the magnets. Similarly the magnet clips included in ZeroPanels surprisingly have the same issue.

For the door handle I used the stealth handle found in the Voron 0.2 fullsize ZeroPanel mod that does take the foam tape into consideration.

Three different magnet holders; at the top the Stealth handles holders that come out 3mm, in the middle the 6mm holder, and at the bottom the standard magnet holder.

There’s a variant of the clips for 6mm magnets in the pull requests that I used by pushing in two 3x2mm magnets and super gluing one 10x3mm magnet on top, so it sticks out the 3mm extra distance the foam tape adds. (Yes, maybe just the 10x3mm magnet would be enough).

For the outside I used the standard ZeroPanels holders for 10x3mm magnets, allowing the magnets close really tightly against each other.

Extra magnets at the top of the printer to get a proper seal.

Let's build a VORON 0

2026-01-29T10:45:13+00:00

About 1.5 years ago I ventured into 3D printing by building a VORON Trident. It was a very fun project and I’ve even used the printer quite a bit.

Naturally, I had to build another one and this time I opted for the cute VORON 0.

Why another printer?

I really like my VORON Trident and it’ll continue to be my main printer for the foreseeable future but a second printer would do two important things for me:

Act as a backup printer if my Trident breaks.

A printer made partially of printed parts is great as you can easily repair it… But only if you have a working printer to print the parts.

It would also be very annoying if I disassemble the printer because I want to mod it and realize I’ve forgotten to print a part I needed.
Building printers are really fun.

Building the VORON Trident is one of my most fun and rewarding projects I’ve done.

Why a VORON 0?

These properties makes the VORON 0 an ideal secondary printer for me:

You need to assemble the VORON 0 yourself (a feature not a bug)
Prints ABS/ASA well (for printer parts)
Very moddable and truly open source
It’s tiny

The VORON 0 to the left and the VORON Trident 250 to the right. It’s really small, which is perfect for me as I have a limited amount of space.

It would be very fun to build a VORON 2.4 (or even a VORON Phoenix) but I really don’t have space for more printers.

Getting the parts

I opted to buy a kit instead of self-sourcing the parts as it’s usually cheaper and requires a lot less work, even if you replace some parts.

This is what I ended up getting:

A VORON 0 kit from Lecktor
Parts for a Dragon Burner toolhead
Parts for a Nevermore V4 active carbon filter
Later on, I replaced the SKR Mini E3 V2 that came with the kit with the V3

Lots of delays

I ordered a VORON 0 from Lecktor in February 2024 and it took roughly 4 months before I got the first shipment of parts and it wasn’t until the end of 2024 that I had received all the parts needed to complete the build.

The wait was annoying…

Printing parts myself

So what do you do when you can’t start the build?

You print parts!

A box of some of the printed parts for the build (and many I later threw away).

There’s something very satisfying with printing parts you then build a printer with.

This time I wanted to make a colorful printer and I came up with this mix of filament:

I think they made the printer look great.

The build

I won’t do as detailed of a build log as I did when building the VORON Trident but I tried to take some pictures. Scroll on!

Frames and bed

The linear Y-rails.

The kit comes with the Kirigami bed mod.

The frame with A/B motors.

Building the bottom of the printer with feet, power supply, and display.

MGN9 instead of MGN7 X-axis

After I assembled the X-axis I noticed a problem:

The carriage collides with the stock A drive.

The reason is that the kit comes with MGN9 rails for the X-axis instead of the standard MGN7 rails. This required me to reprint modified A/B drives, X-carriage, and alignment tools.

The carriage passes the modded B drive.

Belts

Starting to install the belt.

The belt is tight.

Dragon Burner toolhead

I got the parts needed to build the standard mini stealthburner…

But I’m attracted to playing around with new stuff and I decided to try out the Dragon Burner instead. I went with it because it’s quite popular, it has good cooling (I print a bunch of PLA), and I haven’t tried it out yet.

The fans are inserted. I don’t care about LEDs so I inserted an opaque magenta part instead. I think it looks really good.

The back of the Dragon Burner. I opted for the Rapido 2 instead of the Dragon that came with the kit because the Dragon has problems printing PLA.

I was a bit confused on how to route the wires as there was very little space when mounting the toolhead on the carriage. Routing the wires close to the fans, clipping off the ears of the fans, and holding together it with cable ties in this way worked for me.

Galileo 2 standalone

Dragon Burner together with the Galileo 2 extruder mounted on the printer.

For the extruder I opted for the standalone version of Galileo 2. I’ve used Galileo 2 on the Trident but I hated the push down latch it uses in the Stealthburner configuration. The latch eventually broke by pulling out a heat-set insert so I went back to the Clockwork 2 on the Trident, giving me the parts to rebuilt the Galileo for the VORON 0 in a standalone configuration.

The parts for Galileo 2. There will be left-overs from the Stealthburner variant.

The build was really fast and simple—compared to the Stealthburner variant it’s night and day. I didn’t even think to take a break for pictures.

Nevermore filter

Since I want to be able to print ABS I feel I need to have an activated carbon filter. I wanted to have an exhaust fan with a HEPA filter as well, but I’ll leave that to a mod in the future.

The Nevermore V4 is an activated carbon filter that fits well in the VORON 0.

I fastened the fan using a strip of VHB—it was a struggle to position it in the middle.

The Nevermore is mounted standing in the side of the printer.

Panels

With the panel and spool holder at the back.

With the tophat and door installed.

I’m slightly annoyed with the small gaps and holes the printer has (mainly between the tophat and the panels at the bottom half).

Wiring

Wiring was simpler than for the Trident but it was harder to make the wiring pretty. Thank god I could cover it up.

The underside of the printer with the power, 5V converter, display, and Z-motor.

Back of the printer with the Raspberry Pi and MCU.

Raspberry Pi

The Raspberry Pi only has two cables; power and communication over the GPIO pins and a display via USB.

The Pi communicates and gets power over the TFT connection on the MCU.

Toolhead

The kit came with a toolhead board and breakout board for an umbilical setup:

The toolhead board.
I didn’t use the x-endstop.

The breakout board.

I did run into an issue where the polarity of the fans on the toolhead board did not match the polarity of the fans on the MCU, leading to some frustration where the fans refused to spin. I ended up swapping the polarity using the cables from the breakout board to the MCU.

Chamber thermistor

The MCU only has two thermistor ports and they’re used for the hotend and bed thermistors. For the chamber thermistor (that’s integrated into the breakout board) I use the MOSI pin on the SPI1 8-pin header:

The chamber thermistor connected to MOSI and ground on the SPI1 header.

SKR mini E3 v3

I got an SKR mini E3 v2 with the kit but I replaced it with the v3 for two reasons:

An extra FAN output, used for the Nevermore Filter
A filament runout sensor

There’s not much to say about the extra FAN output but the filament runout sensor has 3 pins, while VORON 0.2 style runout sensor has 3 pins. I reused the prepared y-endstop I got with the kit, scratched away some of the plastic to make the 2-pin connection fit the 3-pins on the MCU (the +5V pin isn’t needed):

The filament runout sensor connected to E0-stop.
Yes it’s not the right connector but where there’s a will there’s a way.

Klipper setup

I followed the VORON documentation and chose Mainsail as I’ve been happy with it on my Trident. I’m not going to describe everything and only call out some issues I had or extra steps I had to take.

MCU firmware

The VORON documentation assumes USB communication so the default firmware instructions didn’t work for me.

According to BigTreeTech’s documentation if you communicate over USART2 (the TFT port) then you need to compile the firmware with Communication interface set to Serial (on USART2 PA3/PA2). You then need to use this klipper configuration:

[mcu]
serial: /dev/ttyAMA0
restart_method: command

Filament runout

[filament_switch_sensor Filament_Runout_Sensor]
pause_on_runout: True
runout_gcode: PAUSE
switch_pin: PC15

Chamber thermistor

According to this comment this is the config to use the SPI header for a thermistor:

[temperature_sensor chamber_temp]
sensor_type: Generic 3950
sensor_pin: PA7
pullup_resistor: 10000

Works for me™

Display

It’s easy to flash the display directly from the Raspberry Pi although the first firmware I built was too large. There are optional features you can remove but I removed too many so the configuration for the buttons wasn’t accepted. These were the features that ended up working for me:

[*] Support GPIO "bit-banging" devices
[*] Support LCD devices
[ ] Support thermocouple MAX sensors
[ ] Support adxl accelerometers
[ ] Support lis2dw and lis3dh 3-axis accelerometers
[ ] Support MPU accelerometers
[*] Support HX711 and HX717 ADC chips
[ ] Support ADS 1220 ADC chip
[ ] Support ldc1612 eddy current sensor
[ ] Support angle sensors
[*] Support software based I2C "bit-banging"
[*] Support software based SPI "bit-banging"

Sensorless homing

I was nervous setting up sensorless homing, fearing that without a physical switch the printer might decide to burn the motor against the edge or something. (I really have no idea how it works, hence my fear.)

In the end it was straightforward. The VORON 0 example firmware was already configured for sensorless homing and the only things I had to do was:

Physically jump the X-DIAG and Y-DIAG pins on the board
Tweak the driver_SGTHRS values (I landed on 85 down from 255)

And now I have sensorless homing working consistently.

What confused me was that the sensorless homing guide and the homing macros it links to were slightly different from the VORON 0 example firmware and it wasn’t clear if I had to make all the changes or not. (I did not.)

Some random issues I encountered

In typical 3D printer fashion, you’ll always run into various issues, for example:

I got the mcu shutdown: Timer too close error a few times.

I don’t know what I did but it only happened a couple of times at beginning.
The filament sensor had some consistency issues.

Some extra tape on the bearing seemed to fix it.
The filament keeps getting stuck in the extruder after unload.

I’m still having issues but forgetting to tighten the nozzle and using a too short PTFE tube didn’t help.
I had trouble getting the filament to stick to bed.

Super frustrating to be honest. I re-calibrated the z offset and thumb screws a bunch of times and (right now) it seems to work fairly well. Even though you’re not supposed to need automatic bed leveling for a printer this small, I can’t help but miss the “just works” feeling I have with the Trident.

Update 2025-03-27

I absolutely recommend anyone to follow Elli’s First Layer Squish guide after you’ve tried to calibrate your bed screws and z endstop. It’s much easier to see any minor inconsistencies visually than with the paper test and you’ll get much better bed adhesion (and prints) if you just take your time to tune in a good first layer squish.

Initial thoughts on the printer

A model I printed for one of my kids. It came out really well.

I haven’t printed that much with the printer yet but I have some positive things to say about it:

It looks very good and was very fun to build.
The small footprint is great and a surprising amount of prints fits on the small build volume.
The print quality is very good. The extra cooling from the Dragon Burner is great when printing PLA (which I use a lot).

But I have some negative things to say too:

It’s loud. The 5V fan close to the Raspberry Pi is horribly loud but the print movement is also too loud for my taste.
It’s poorly insulated. For example there are gaps between the top hat and the rest of the printer that I don’t see a good way to cover up.

Overall though I’m very happy with it. I wouldn’t recommend it as a first printer or to someone who just wants a tool that works out of the box, but for people like me who wanted to build a backup/secondary printer I think it’s great.

What’s next?

With a secondary printer finally up and running I can now start working on some significant mods for my Trident! This is the tentative plan right now:

Install the Inverted electronics mod.
Replace Stealthburner with another toolhead, most likely A4T-toolhead.
Build a BoxTurtle for multi-color support.

But we’ll see when I manage to get to it. I’m not in a rush and I should take a little break and play with my VORON 0 and perhaps work on my other dozen or so projects that lie dormant.

I'll give up Neovim when you pry it from my cold, dead hands

2025-02-18T11:25:38+00:00

I recently came upon a horror story where a developer was forced to switch editor from Neovim to Cursor and I felt I had to write a little to cleanse myself of the disgust I felt.

Two different ways of approaching an editor

I think that there’s two opposing ways of thinking about the tool that is an editor:

Refuse to personalize anything and only use the basic features

“An editor is a simple tool I use to get the job done.”
Get stuck in configuration hell and spend tons of time tweaking minor things

“An editor is a highly personalized tool that works the way I want.”

These are the extreme ends of the spectrum to make a point and most developers will fall somewhere in between.

It’s not a static proposition; I’ve had periods in my life where I’ve used the same Vim configuration for years and other times I’ve spent more time rewriting my Neovim config than doing useful things.

Freedom of choice is important

Freedom of choice is more to be treasured than any possession earth can give.

David O. McKay

Some developers want zero configuration while others want to configure their editor so it’s just right. Either way is fine and I’ve met excellent developers from both sides.

But removing the power of choice is a horrible idea as you’re forcing developers to work in a way they’re not comfortable with, not productive with, or simply don’t like. You’re bound to make some of the developers miserable or see them leave (usually the best ones who can easily find another job).

To explain how important an editor might be to some people, I give you this story about Stephen Hendry—one of the most successful Snooker players ever—and how important his cue was to him:

In all the years I’ve been playing I’ve never considered changing my cue. It was the first cue I ever bought, aged 13, picked from a cabinet in a Dunfermline snooker centre just because I liked the Rex Williams signature on it.

I saved £40 to buy it. It’s a cheap bit of wood and it’s been the butt of other players’ jokes for ages. Alex Higgins said it was ‘only good for holdin’ up f*g tomatoes!’

But I insist on sticking with it. And I’ve won a lot of silverware, including seven World Championship trophies, with it. It’s a one-piece which I carry in a wooden, leather-bound case that’s much more expensive than the cue it houses.

But in 2003, at Glasgow airport after a flight from Bangkok, it emerges through the rubber flaps on the carousel and even at twenty yards I can see that both case and cue are broken. Snapped almost clean in two, the whole thing now resembling some form of shepherd’s crook. The cue comes to where I’m standing, and I pick it up, the broken end dangling down forlornly.

I could weep. Instead, I laugh.

‘Well,’ I say to my stunned-looking friend John, ‘that’s my career over.’

Stephen Hendry, The Mirror

Small improvements leads to large long-term gains

Kaizen isn’t about massive overhauls or overnight success. Instead, it focuses on small, continuous improvements that add up to significant long-term gains.

What is Kaizen? A Guide to Continuous Improvement

I firmly believe that even small improvements are worth it as they add up over time (also see compound interest and how it relates to financial investments).

An editor is a great example where even small improvements may have a big effect for the simple reason that you spend so much time in your editor. I’ve spent hours almost every day inside (neo)vim since I started using it 15+ years ago.

Even simple things like quickly changing text inside brackets (ci[) instead of selecting text with your mouse might save hundreds of hours during a programming career—and that’s just one example.

Naturally, as a developer you can find small but worthwhile improvements in other areas too, for instance:

Learning the programming languages and libraries you use a little better
Customizing your keyboard and keyboard layout

This is more for comfort and health than speed but that makes it even more important, not less.
Increasing your typing speed

Some people dismiss typing speed as they say they’re limited by their thinking, not typing. But the benefit of typing faster (and more fluidly) isn’t really the overall time spent typing vs thinking; it’s so you can continue thinking with as little interruption as possible.

On some level you want to reduce the time typing in this chain:

think… edit, think… edit, think…

It’s also why the Vim way of editing is so good—it’s based on making small edits and to return quickly to normal (thinking) mode.

Some people ask how can you afford to spend time practicing Vim commands or to configure your editor as it takes away time from work?

But I ask you: with a programming career of several decades and tens of thousands of hours to spend in front of your computer, how can you afford not to?

Neovim is versatile

During the years I’ve done different things:

Studied at the University and then started working as a developer.
Used many different programming languages and paradigms.
Changed domains many times (games, grammars & language design, graphics programming, web development, …)
Switched keyboard and keyboard layout multiple times.
Been blogging and wrote a book.

The one constant through all of this has been Neovim. Neovim may not have the best language specific integrations but it does everything well and the benefit of having the same setup for everything you do is not to be underestimated. It pairs nicely with the idea of adding up small improvements over time; every small improvement that I add to my Neovim workflow will stay with me no matter what I work with.

Neovim is easily extensible

Neovim: a Personalized Development Environment

TJ DeVries A different take on editing code

I’ve always felt that Vimscript is the worst part of Vim. Maybe that’s a weird statement as the scriptability of Vim is one if it’s strengths; and to be fair, simple things are very nice:

nnoremap j gj
set expandtab

But writing complex things in Vimscript is simply not a great experience.

One of the major benefits of Neovim is the addition of Lua as a first-class scripting language. Yes, Lua isn’t perfect and it’s often too verbose but it’s so much better than Vimscript. Lua is the main reason that the Neovim plugin ecosystem is currently a lot more vibrant than in Vim.

Making it easier to write plugins is of course a boon, but the real benefit is in how it makes it even easier to make more complex customization for yourself. Just plop down some Lua in the configuration files you already have and you’re done. (Emacs worked this out to an even greater extent decades ago.)

One way I use this customizability is to help me when I’m blogging:

A custom picker to search and display blog posts
Autocomplete tags, post urls, and more
LSP-like functionality to display warnings and jump between posts
Use treesitter to convert links, autoformat lists, and jump around

Maybe you don’t need to create something this big but even small things such as disabling autoformat for certain file types in specific folders can be incredibly useful.

Approachability should not be underestimated.

Neovim won’t go anywhere

The old is expected to stay longer than the young in proportion to their age.

Nassim Nicholas Taleb, “Antifragile”

The last big benefit with Neovim I’ll highlight—and why I feel fine with investing even more time into Neovim—is that Neovim will most likely continue to exist and thrive for years if not decades to come.

While Vim has—after an impressive 30 years of development—recently entered maintenance mode, activity in Neovim has steadily increased since the fork from Vim more than a decade ago. The amount of high quality plugins, interest in Google trends, and GitHub activity have all been trending upwards. Neovim was also the most desired editor according to the latest Stackoverflow developer survey and the overall buzz and excitement in the community is at an all-time high.

With the self-reinforced behavior and benefits of investing into a versatile and flexible editor with a huge plugin ecosystem such as Neovim I see no reason for the trend to taper off anytime soon.

Neovim will probably never be as popular as something like VSCode but as an open source project backed by excited developers, Neovim will probably be around long after VSCode has been discontinued for The Next Big Thing.

Securing my partner's digital life

2025-01-20T12:58:29+00:00

I’ve been with Veronica for over a decade now and I think I’m starting to know her fairly well. Yet she still manages to surprise me. For instance, a couple of weeks ago she came and asked me about email security:

I worry that my email password is too weak. Can you help me change email address and make it secure?

It was completely unexpected—but I’m all for it.

The action plan

All heroic journeys needs a plan; here’s mine:

Buy her a domain name (her .com surname was available).
Migrate her email to Fastmail.
Setup Bitwarden as a password manager.
Use a YubiKey to secure the important services.

Why a domain?

If you ever want (or need) to change email providers it’s very nice to have your own domain. For instance, Veronica has a hotmail.com address but she can’t bring that with her if she moves to Fastmail.

Worse, what if she gets locked out of her Outlook account for some reason? It might happen if you forget your password, someone breaks into your account, or even by accident.

In almost all cases, your email is your key to the rest of your digital life. The email address is your username and to reset your password you use your email. If you lose access to your email you lose everything.

When you control your domain, you can point the domain to a new email provider and continue with your life.

Why pay for email?

One of the first things Veronica told me when I proposed that she’d change providers was that she didn’t want to pay. It’s a common sentiment online that email must be cheap (or even free).

I don’t think that email is the area where cost should be the most significant factor. As I argued for in why you should own your email’s domain, your email is your most important digital asset. If email is so important, why try to be cheap about it? You should spend your money on the important things and shouldn’t spend money on the unimportant things.

Paying for email gives you a couple of nice things:

Human support.

It’s all too easy to get shafted by algorithms where you might get banned because you triggered some edge case (such as resetting your password outside your usual IP address).
Ability to use your own domain.

Having a custom domain is a paid feature at most email providers.
A long-term viable business.

How do you run an email company if you don’t charge for it?
(You sell out your users or you close your business.)

Why a password manager?

The best thing you can do security wise is to adopt a password manager. Then you don’t have to try to remember dozens of passwords (leading to easy-to-remember and duplicate passwords) and can focus on remembering a single (stronger) password, confident that the password manager will remember all the rest.

“Putting all your passwords in one basket” is a concern of course but I think the pros outweigh the cons.

Why a YubiKey?

To take digital security to the next level you should use two-factor authentication (2FA). 2FA is an extra “thing” in addition to your password you need to be able to login. It could be a code sent to your phone over SMS (insecure), to your email (slightly better), a code from a 2FA app on your phone such as Aegis Authenticator (good), or from a hardware token (most secure).

It’s easy to think that I went with a YubiKey because it’s the most secure option; but the biggest reason is that a YubiKey is more convenient than a 2FA app.

With a 2FA app you have to whip out your phone, open the 2FA app, locate the correct site, and then copy the TOTP code into the website (quickly, before the code changes). It’s honestly not that convenient, even for someone like me who’s used this setup for years.

With a YubiKey you plug it into a USB port and press it when it flashes. Or on the phone you can use NFC. NFC is slightly more annoying compared to plugging it in as you need to move/hold it in a specific spot, yet it’s still preferable to having to jump between apps on the phone.

There are hardware keys other than YubiKey of course. I’ve used YubiKey for years and have a good experience. Don’t fix what isn’t broken.

The setup

Here’s a few quick notes on how I setup her new accounts:

Password management with Bitwarden

The first thing we did was setup Bitwarden as the password manager for her. I chose the family plan so I can handle the billing.

To give her access I installed Bitwarden as:

An app on her phone
A browser plugin on her computer

I gave her a YubiKey and registered it with Bitwarden for additional security. As a backup I also registered my own YubiKeys on her account; if she loses her key we still have others she can use.

Although it was a bit confusing for her I think she appreciates not having to remember a dozen different passwords and can simply remember one (stronger) password. We can also share passwords easily via Bitwarden (for news papers, Spotify, etc).

The YubiKey itself is very user friendly and she hasn’t run into any usability issues.

Email on Fastmail

With the core security up and running the next step was to change her email:

Gave her an email address on Fastmail with her own domain (<firstname>@<lastname>.com).

She has a basic account that I manage (there’s a Duo plan that I couldn’t migrate to at this time).
I secured the account with our YubiKeys and a generated password stored in Bitwarden.
We bolstered the security of her old Hotmail account by generating a new password and registering our YubiKeys.
Forward all email from her old Hotmail address to her new address.

With this done she has a secure email account with an email address that she owns.

As is proper she’s been changing her contact information and changing email address in her other services. It’s a slow process but I can’t be too critical—I still have a few services that use my old Gmail address even though I migrated to my own domain more than a decade ago.

Notes on recovery and redundancy

It’s great to worry about weak phishing, weak passwords, and getting hacked. But for most people the much bigger risk is to forget your password or lose your second factor auth, and get locked out that way.

To reduce the risk of losing access to her accounts we have:

Multiple YubiKeys for all accounts.
The recovery codes for all accounts are written down and secured.
My own accounts can recover her Bitwarden and Fastmail accounts via their built-in recovery functionality.

Perfect is the enemy of good

Some go further than we’ve done here, others do less, and I think that’s fine. It’s important to not compare yourself with others too much; even small security measures makes a big difference in practice.

Not doing anything at all because you feel overwhelmed is worse than doing something, even something simple as making sure you’re using a strong password for your email account.

First impressions of Ghostty

2025-01-19T07:16:57+00:00

There are two conflicting forces in play in setting up your computer environment:

It’s worthwhile to pursue small improvements in frequently used tools.
It’s not productive to get stuck tweaking your setup endlessly.

It’s common to find people get stuck at the extreme ends of the spectrum; some programmers refuse to configure or learn their tools at all, while others get stuck re-configuring their setups constantly without any productivity gains to show for it.

Finding a balance can be tricky. With regards to terminals I’ve been using alacritty for many years. It gets the job done but I don’t know if I’m missing out on anything? I’ve been meaning to look at alternatives like wezterm and kitty but I never got far enough to try them out.

On one hand it’s just a terminal, what difference could it make?
On the other hand, I spend countless of hours every day inside a terminal so even a small improvement should pay off in the long run.

Enter Ghostty, a terminal so hyped up it made me drop any useful things I was working on and see what the fuzz was about. I don’t quite get why people hype up a terminal of all things but here we are.

Ghostty didn’t revolutionize my setup or anything but I admit that Ghostty is quite nice and it has replaced alacritty as my terminal.

I just want a blank canvas without any decorations

One of the big selling points of Ghostty is its native platform integration. It’s supposed to integrate well with your window manager so it looks the same and gives you some extra functionality… But I don’t know why I should care—I just want a big square without decorations of any kind.

You’re supposed to to be able to simply turn off any window decorations:

window-decoration = false

At the moment there’s a bug that requires you set some weird GTK settings to fully remove the borders:

gtk-titlebar = false
gtk-adwaita = false

It’s unfortunate as I haven’t done any GKT configuration on my machine (I use XMonad as my window manager and I don’t have any window decorations anywhere).

Cursor invert

cursor-invert-fg-bg = true

In alacritty I’ve had the cursor invert the background and foreground and you can do that in Ghostty too.

I ran into an issue where it interferes with indent-blankline.nvim making the cursor very hard to spot in indents (taking the color of the indent guides, which is by design low contrast with the background).

Annoying but it gave me the shove I needed to try out different plugins to see if the problem persisted. I ended up with (an even nicer) setup using snacks.nvim that doesn’t hide the cursor:

Left: indent-blankline.nvim (cursor barely visible)
Right: snacks.nvim (cursor visible and it highlights scope).

Minimum contrast

Unreadable ls output is a staple of the excellent Linux UX. It might look like this:

Super annoying.

You can of course configure the ls output colors but that’s just for one program and it won’t automatically follow when you ssh to another server.

Ghostty’s minimum-contrast option ensures that the text and background always has enough contrast to be visible:

minimum-contrast = 1.05

Most excellent.

Hide cursor while typing

mouse-hide-while-typing = true

A small quality-of-life feature is the ability to hide the cursor when typing. I didn’t know I needed this in my life.

Consistent font sizing between desktop and laptop

With alacritty I have an annoying problem where I need to use a very different font size on my laptop and my desktop (8 and 12). This wasn’t always the case and I think something may have changed in alacritty but I’m not sure.

Ghostty doesn’t have this problem and I can now use the same font settings across my machines ( font-size = 16).

Ligature support

The issue for adding ligatures to alacritty was closed eight years ago and even though I wanted to try ligatures I couldn’t be bothered to “run a low quality fork”.

Ghostty seems like the opposite of “low quality” and it renders Iosevka’s ligatures very well:

My configured ligatures of Iosevka, rendered in Ghostty.

Overall I feel that the font rendering in Ghostty is a little better than in alacritty, although that might be recency bias. I’m still undecided on ligatures but I love that I don’t have to feel limited by the terminal.

I use a custom Iosevka build with these Ghostty settings:

font-family = IosevkaTreeLig Nerd Font
font-style = Medium
font-style-bold = Bold
font-style-italic = Medium Italic
font-style-bold-italic = Bold Italic
font-size = 16

Colorscheme

While Ghostty has an absolutely excellent theme selector with a bunch of included themes (ghostty +list-themes) melange-nvim wasn’t included, so I had to configure the colorscheme myself. It was fairly straightforward even though the palette = 0= syntax was a bit surprising:

# The dark variant of melange
background = #292522
foreground = #ECE1D7
palette = 0=#867462
palette = 1=#D47766
palette = 2=#85B695
palette = 3=#EBC06D
palette = 4=#A3A9CE
palette = 5=#CF9BC2
palette = 6=#89B3B6
palette = 7=#ECE1D7
palette = 8=#34302C
palette = 9=#BD8183
palette = 10=#78997A
palette = 11=#E49B5D
palette = 12=#7F91B2
palette = 13=#B380B0
palette = 14=#7B9695
palette = 15=#C1A78E
# I think it's nice to colorize the selection too
selection-background = #403a36
selection-foreground = #c1a78e

I’m happy with Ghostty

In the end Ghostty has improved my setup and I’m happy I took time to try it out. It took a little more time than “just launch it” but it absolutely wasn’t a big deal. The reward was a few pleasant improvements that have improved my life a little.

And perhaps most important of all: I’m now an alpha Nerd that uses a terminal written in Zig.

2024 in review

2025-01-19T07:16:57+00:00

It’s time for my 15th yearly review.

Nerdy things I enjoyed

I read a lot of fantasy books this year!

My favorite new series were The Kingkiller Chronicle, Gentlemen Bastards series, and The Stormlight Archive.

If you’re curious about Sanderson’s books but a little apprehensive about jumping into a massive series such as The Stormlight Archive then I’ll recommend The Emperor’s Soul as an excellent little introduction. The standalone book Warbreaker is also fantastic (available for free on Brandon’s website).
Customizing Neovim was fun and rewarding.

It’s amazing I got anything productive done this year…
I really enjoy working with Rust in my own hobby projects.
Types are coming to Elixir and I’m loving it.

(I recently migrated some small projects to v1.18 and found a bunch of errors.)
The Gleam programming language shows a lot of promise.

My one gripe is the pain of manually encoding/decoding JSON (even with the various libraries). Compared to for example Elixir dynamic encoding or Rust’s #[derive(Deserialize)] it just feels so bad that I’ve avoided Gleam for some projects. Shame on me?
CSS is alive and better than ever.

Things I accomplished

I quit my job and started my own company.

At the moment I’m focusing on consulting but maybe something else can grow from it one day?
I wrote 26 blog posts—it was quite a productive blogging year for me.
I built a custom keyboard together with a custom keyboard layout.
Made the eBook for Why Cryptocurrencies? freely available and finally finished the How I wrote ‘Why Cryptocurrencies?’ series.
I wrote a Tree-sitter grammar for Djot.

I need to be more active maintaining it… But it’s hard to get motivated as I’ve got so many other interesting things I’d like to work on. Managing an open source project is not for the faint of heart (or the easily distracted).
Finished the blog series about building my first 3D printer.

I’m up to over 2100 printing hours with the machine so it’s safe to say I’ve been using it, not only playing around with.
Rewrote my lighting home automation from Python to Elixir.
I realized that meta-blogging is a great way to get virtual points on Hacker News.

Tentative plans/goals/wishes for 2025

For some reason the idea of writing a fantasy novel got stuck in my head.

I had a stint where I listened to dozens of hours of advice for aspiring writers and started planning a series. The excitement tapered off a bit during the Christmas holidays and I don’t know if this was just a temporary sidetrack or if it’s something I’ll actually end up doing.
Design a one-handed keyboard layout.

Again, this was just something my brain got stuck thinking about and I’m not sure if it’s just a fleeting idea or something I need to do so I can stop thinking about it. (Sometimes just a little planning plus solving the most difficult problems are enough—I don’t have to finish all the crazy/dumb ideas I get for my mind to consider them “done”.)
Complete my second 3D printer.

There’s no point in having a single printer; what if I break it and I can no longer print replacement parts for it?
Develop my home automation system more.

I’ve got a ton of things I’d like to improve (or play around with). For instance, yesterday I received the Home Assistant Voice Preview Edition that I hope works as well as advertised.

A type checking error in Elixir 1.18

2025-01-19T07:16:57+00:00

Although I’m a big Elixir fan, the lack of static typing has always been my biggest annoyance (and why I think Gleam is so cool). I think static typing helps catch bugs earlier and in an automated way, leading to less buggy software and saves time in the long run.

To my great joy Elixir is working on a new type system that will hopefully give us the early type checking errors I’ve been craving for. The system has been rolled out in steps since v1.17 and when I migrated to v1.18 I found my first type checking warning that I wanted to highlight.

Comparison with structs

This is the offending code with the corresponding warning:

def get_surrounding_events_as_dt(events, now = %DateTime{}) do
  time = DateTime.to_time(now)
  next_i = Enum.find_index(events, fn {_, event_time} -> time < event_time end) || 0

warning: comparison with structs found:

    time < event_time

given types:

    dynamic(%Time{}) < dynamic()

where "event_time" was given the type:

    # type: dynamic()
    # from: lib/haex/sun.ex
    {_, event_time}

where "time" was given the type:

    # type: dynamic(%Time{})
    # from: lib/haex/sun.ex:88:10
    time = DateTime.to_time(now)

Comparison operators (>, <, >=, <=, min, and max) perform structural and not semantic comparison.
Comparing with a struct won't give meaningful results.
Structs that can be compared typically define a compare/2 function within their modules that
can be used for semantic comparison.

typing violation found at:
│
│     next_i = Enum.find_index(events, fn {_, event_time} -> time < event_time end) || 0
│                                                                 ~

(The type checker cannot yet resolve event_time to the Time struct, leaving it as dynamic() in the text above.)

The issue here as that < isn’t overloaded for the Time struct (like it would be in for instance Rust) and will instead perform structural comparison.

You should use Time.before? instead of < (and DateTime.before for DateTime etc).

As it happens for Time this doesn’t seem to be an issue as the structure happens to perform the comparisons in the same order as Time.before?, which this test verifies:

test "check_times" do
  times =
    Enum.zip([0..23, 0..59, 0..59])
    |> Enum.map(fn {h, m, s} -> Time.new!(h, m, s) end)

  for a <- times do
    for b <- times do
      assert a < b == Time.before?(a, b)
    end
  end
end

This is not the case for DateTime, which did cause a production bug in my home automation system, that my spouse complained about…

Remember this when you think about types: type checking saves relationships.

My hope for the future

I’ve always disliked matching against atoms in Elixir as it’s so easy to make a mistake, for example like this:

case Supervisor.start_child(supervisor, child_spec) do
  {:error, {:already_stated, pid}} ->
    Logger.info("Got pid: #{inspect(pid)}")

(There’s a missing r in :already_stated.)

At the moment this doesn’t produce an error but I really hope we’ll reach this point sooner rather than later as I make these kinds of mistakes all the time. I think I catch most of these with tests but I’m sure some slip through.

I hope this isn’t that far away as the v1.18 type checker manages to catch a simpler case like this:

def num_to_descr(num) do
  case num do
    1 -> :one
    2 -> :two
    _ -> :many
  end
end

def print(num) do
  case num_to_descr(num) do
    :zero -> IO.puts("zero")
    x -> IO.puts("Other: #{x}")
  end
end

    warning: the following clause will never match:

        :zero

    because it attempts to match on the result of:

        num_to_descr(num)

    which has type:

        dynamic(:many or :one or :two)

    typing violation found at:
    │
 41 │       :zero -> IO.puts("zero")
    │       ~~~~~~~~~~~~~~~~~~~~~~~~

Building my ultimate keyboard

2026-04-27T10:06:42+00:00

The Cybershard keyboard.

What comes to mind when you see the description “the ultimate keyboard”?

There are many keyboards in this world; here are some that might fit the “ultimate” moniker:

Das Keyboard 4 Ultimate mechanical keyboard
DataHand
Ergodox EZ
Glove80
Happy Hacking Keyboard
Model M Keyboard
Stenotype keyboards.
Ultimate Hacking Keyboard
CharaChorder

Some even have “ultimate” in their name, although I’ll assert that they’re far from ultimate.

Any man who must say, “I am the King”, is no true king.

Tywin Lannister

I’ll go one step further to say that no keyboard is universally the ultimate because it’s impossible to agree on how to rank different keyboards. For example, while I personally prefer a split keyboard, you might not. Some people have very long fingers and some have very short fingers, making some layouts more preferable. Others may not even have 10 fingers (or both hands), requiring more drastic modifications.

If an ultimate keyboard exists, it differs from person to person. This is my attempt to build my ultimate keyboard.

My wishlist

To me, the ultimate keyboard should have these features:

Should be split to support a more natural typing position.

Really the biggest ergonomical leap in my opinion.
Customized for my own fingers and typing eccentricities.

Column stagger, curvatures and tenting are features I think I want but they need to be tuned, probably by trial-and-error. The position of the thumb keys is another sticking point that the other keyboards I’ve tried have failed to get just right.
Have an integrated trackball or trackpad.

This way I don’t have to move my hand so far and I can free up some valuable desk space. It shouldn’t be operated with my thumb due to my RSI.
Contain the keys I need but no more.

I like smaller keyboards and I’ve been very happy and with my custom keyboard layout that only has 34 keys. Some modifications are fine of course but for the most part I want to be able to use the same layout on both the Ferris and my new keyboard.

To fulfill these requirements I need to be able to customize all parts of the keyboard and I really don’t want to learn CAD and create one from scratch; I wonder what alternatives I have?

Cosmos keyboard configurator

Having looked around, I probably want something similar to a Dactyl / Dactyl Manuform (many variants exists). They’re keyboards you generate from parameters (such as number of rows and columns and the amount of curvature). I’ve always wanted to try one and now with a 3D printer, I can.

When looking for a generator I stumbled upon the Cosmos keyboard configurator and I want to gush about it a little because it’s excellent.

A relatively standard Dactyl Manuform with an encoder and trackpad.

It’s excellent because it allows a clueless sod like me to configure a keyboard the way I want to and it has an impressive feature list:

Easily generate keyboards of any size.
Customize XY-spacing, row- and colomn curvature, and more.
Several pre-made thumb clusters.
UI to move around all the keys.
Supports different switches (I so need my Choc switches).
An Expert mode that allows you to customize anything via JavaScript.
Supports encoders, trackpads, OLED displays, and trackballs.
Can generate a wrist rest.
Exports .stl for easy printing or .step you can import to CAD.

Here’s a small snippet from how the code in Expert mode might look like:

const curvature = {
  curvatureOfColumn: 15,
  curvatureOfRow: 5,
  spacingOfRows: 18, // 18x19 Choc spacing
  spacingOfColumns: 19,
  arc: 0,
};

/**
 * Useful for setting a different curvature
 * for the pinky keys.
 */
const pinkyCurvature = {
  ...curvature,
  curvatureOfColumn: 15,
};

/**
 * The plane used to position the upper keys.
 * It's rotated by the tenting and x rotation
 * then translated by the z offset.
 */
const upperKeysPlane = new Trsf()
   // `20` specifies the tenting angle.
  .rotate(20, [0, 0, 0], [0, 1, 0], false)
  .rotate(1, [0, 0, 0], [1, 0, 0], false)
  .translate(0, 0, 0, false);

The entire state of the keyboard is also stored in the url, so I can easily share my config by including a link: Cosmos reference of the final keyboard configuration. (Barring any breaking changes in the tool of course…)

Initial design parameters

Even with a keyboard configurator I needed a way to start. I already have a layout that I really like so I wasn’t starting from nothing. These were the important parts going into the design process:

A 3x5 grid with 1-2 thumb keys (in practice one thumb key is enough).

If you question why I want to build such a small keyboard I’ll redirect you to the discussion in The T-34 keyboard layout post.
Integrated trackball on the right-hand side.
Choc switches.

One of the major decisions with a keyboard is what kind of switch to use. While MX-style switches are the most common I personally really love Choc switches for a couple of reasons:
- Low-profile
- Low actuation force
- Can be closer together
While a low profile switch is more important for a flat keyboard, not a tented and curved one like I’m building now, the flatter keycaps and the switches being closer together is crucial for pressing two keys with one finger:

A horizontal combo is pressed with the finger in the middle of the keys. It’s surprisingly comfortable.

The low-actuation force is also more comfortable to me as it helps reduce the strain on my fingers, and makes combos (pressing several switches at once) generally more pleasant.

Hardware and material

It’s not enough with just a 3D printer, to build a working keyboard you need a bunch of hardware:

Two microcontrollers.

I got the Liatris microcontroller as it has enough pins to connect a trackball sensor and it supports QMK.
Switches

What kind of Choc switch should I use?
Linear, tactile, or clicky?
Exactly how heavy should they be?
Should they be silent?

I wasn’t sure so I ordered a sampling of different switches to try.

A collection of different Choc switches.

For the final keyboard I used the Ambients silent Noctural (linear / 20gf) switches, where the deciding factor was getting as light switches as possible. (I’ve previously used modded 15gf switches, which were even better, but I couldn’t find a way to buy them.)
Keycaps

It’s hard to decide on a colorscheme so I bought a bunch of random colors.

Keycaps aren’t only for looking cool. A convex keycap for the thumb button instead of the standard concave one makes it much more comfortable:

The blue convex keycap to the left and the red concave to the right.

I also got keycaps for the index row with these small homing notches to help my fingers more easily find the home row.
A pair of TRRS connectors and a TRRS cable.
A Trackball with a matching sensor.

I decided to pick up this PMW3389 sensor because it was recommended in the keyboard configurator and a red 34mm trackball from Amazon.
Filament for the 3D printed pieces.

I ended up settling on the PolyTerra PLA Army Purple for the case but I used a bunch of different filament during the prototype phase.
Diodes, screws, heatset inserts, and cable to do the wiring.

Prototypes

Some discarded prototypes.

When you’re trying to design something like a custom keyboard I think you need to go through a bunch of trial-and-error until you find something that fits.

Here’s a short rundown of some of the significant revisions I went through, mostly to illustrate that it’s very much an iterative process.

First print

For my first print I mostly wanted to print it out and test how a keyboard with a standard curvature felt. I also wanted to try to place a trackball somewhere.

I ended up removing a regular thumb key (I’ve used two thumb keys with my keyboard layout) to make it fit and I added a “mouse thumb key” that I plan to use as a left mouse button when I’m operating the trackball. It was tricky to place the trackball as I wanted to operate it with my index + middle finger, not my thumb.

Another tweak I made was to reduce the spacing between the keys to be closer to the Choc spacing. Choc spacing seems to be 18.6 x 17.6 mm, but I used 19 x 18 mm spacing—the attraction to round numbers is real.

This is the very first prototype I printed. Please ignore the bad print quality; the filament was wet and the temperature was too high. It’s just a prototype so it really doesn’t matter.

Pressing the top right key with the ring finger

Most of the keys on the keyboard felt fine but I had one major annoyance: I have a habit of using the ring finger to press the top right key instead of the pinky but with the curvature on the keyboard this just wasn’t possible anymore.

You might wonder, why don’t I just create a new habit and use the pinky as you’re supposed to? The simple answer is that I hate it. To my fingers that feels beyond terrible and I’d rather remove the key and only have two keys in the outermost column. As it happens, pressing the key with my ring finger (on a flat keyboard) feels good so I’d rather adjust the key than remove it.

The second printed prototype, with some keys installed for testing. The printer clogged before the print was finished but it did its job as a prototype.

Here’s an angle from the configurator showing the offset of the p key compared the other keys in the column.

I also added an extra mouse thumb key and lowered the pinky column a bit.

Adjust mouse keys and increase tenting

It’s starting to look like an actual keyboard. With color coded keycaps; red for mouse-only buttons and violet for the home-row keys.

Pressing p with my ring finger feels great. Pressing the thumb normal thumb key feels awful because the mouse thumb keys are in the way when I relax my hand.

Adjustments made:

Moved mouse thumb keys to be more vertical and pressed from the side.
Added an extra pinky key reachable when I’m using the trackball.
Increased tenting to 20 degrees from 10 degrees.

20 degrees of tenting.

Rounded base and pinky tweak

Yet another prototype.

I tried the “rounded” sides and top feature of Cosmos.
The mouse pinky key was too low, I raised it up a bunch.

Thumb keys adjustments

Rotated the main thumb key inwards
Added an area for a display

Lowered the mouse thumb keys a little
Removed the “rounded” features

More tweaks and the left half

Configure the left half of the keyboard
Move pinky keys a little upwards
Move all thumb keys a little further away

Removed the display (felt like too much of a hassle for a little coolness)

Although I said I wanted to have a 3x5 grid, the generator included an easy option to include a small bottom row with 2 extra keys (for the ring and middle finger) that I wanted to try out for the left side. They’re… Okay I guess. Not crazy uncomfortable but not quite comfortable enough that I want to have common keys there.

Beta V3

At this point the Beta V3 of configurator is out and in it there’s several improvements, most notably:

Both halves can be configured at the same time.
Can go between the Advanced and Expert tabs! WOW!

I had to manually keep track of the JavaScript changes I made, and update them manually if I wanted to make a change in the UI… But no more!

I had to redo most of the configuration and I think I made some minor changes that I didn’t keep track of, but I made two larger ones:

Lowered the tenting angle to 15 degrees (from 20)
Lowered ring pinky column key a little

Small tweaks to pinky and thumb keys

Raise/tilt top pinky row key
Move thumb keys on left side closer together

Trackball mounting types

Roller bearings for the trackball.

When I started this project Cosmos only supported a single type of trackball mount: roller bearings. They worked quite poorly for me as the ball was spinning well in one direction but poorly in others.

Luckily new options were added and as I’m writing this there’s 4 different ways you can mount the trackball:

Roller bearings (the old option)
BTU (7.5mm or 9mm)
Static ball bearings (3.175mm)

Because I was burned with the bad experience (and I didn’t want to rebuild the keyboard yet again) I made small prototypes of the three different options:

The new trackball mounts; BTU 9mm, BTU 7.5mm, and static ball bearings.

The BTUs had the least friction and it felt really easy to spin the ball but they were also distressingly loud. The static ball bearings had more friction than the BTUs and less than the roller bearings while being completely silent, so I chose to go with the ball bearings.

The ball bearings installed on the keyboard, with the trackball sensor peeking through.

While they don’t feel nearly as good as the Kensington SlimBlade they’re decent enough. I try not to use the mouse that much and having the trackball so much closer is worth it compared to having a separate trackball unit besides the keyboard.

Remove mouse keys

After having used the keyboard for real I realized that the three keys dedicated to mouse buttons would have to go. There were two major issues with them:

The pinky key got in the way sometimes when I reached for the top column, and I couldn’t retrain myself to avoid it.
One of the goals with the keyboard layout I use is to reduce the thumb and pinky usage of my right hand. The mouse keys counteract this goal.

So I had them removed and I rewired the right half for the 3rd time. Sigh.

I think the lesson is that it’s not enough to print a prototype and press switches pretending to type, you have to build and use the keyboard a bunch before you can evaluate some of the design decisions.

Cosmos reference

Additional printed parts

While the case is the biggest and most important part of this kind of keyboard, there are a few other parts I had to print to complete the keyboard.

Wrist rests

Some of the different wrist rests I tried.

Magnet attachments

The wrist rests didn’t come with any sort of attachment to the case, so they just always drifted away. I tried to combat this by gluing magnets inside the case and outside the wrist rest, making them stick together just enough to stay together during normal use, while being easily removable.

I ended up not using the wrist rests

Despite my efforts, I haven’t been using the printed rests as I reverted to the ”squishy” ones I’ve used before:

It’s not visible from this angle but my hand rests using the palm instead of the wrist.

The printed felt too uncomfortable and I couldn’t find an angle I liked more than the gel rests. Oh well.

Microcontroller holder

The microcontroller is held in place by a holder you screw into the case.

There’s a holder to fasten the microcontroller to the case that I use. I had to manually make a hole to make the Boot button accessible, which was easily accomplished when slicing the model.

Bottom plate

A flexible bottom plate hides the wiring.

One problem with the Ferris was that it would sometimes slip on the table. I counteracted this by using an old Netrunner playmat but I wanted another solution.

The keyboard is generated with a bottom plate that’s used to hide and protect the internals. I printed it in TPU, a flexible and rubbery material, that gives enough grip to stay relatively still when I’m typing.

Wiring

The complete wiring of the right-side keyboard.

Matrix

One of the first things you need to do when wiring up a custom keyboard is to plan out a matrix. I guess you could directly wire every switch directly to the controller too, but that’s not feasible if you have a larger amount of keys, so the usual thing is to use a matrix.

What a matrix means is you should wire together all keys in a row and connect that to a pin on the controller, and to the same with the columns.

It might look something like this:

The green lines indicate columns and the purple lines indicates rows.

You should also use diodes in the matrix (for either rows or columns, I chose the rows). Pay attention to the diode direction.

The rows are connected with diodes and with a cable to a pin on the controller.

The first matrix I soldered on the right side. It was a lot more difficult to solder because of the awkward positions of the switches.

The 3rd matrix I soldered for the right side, this time without the challenging mouse keys. Note that I wired it up slightly differently than in the wiring plan above because it felt more straightforward. Exactly how you choose to construct the matrix doesn’t really matter, as long as every key has a unique row/column combination.

Both the rows and columns are wired up and soldered to the controller.

The wiring is horrible, I know.

I only lost one microcontroller due to a short… With my wiring prowess I consider that a success!

Controller wiring

The right-side controller connected to the TRRS and the trackball sensor. This was after I had removed them from my second wired right half and was preparing to rebuild it.

The pins of the Liatris microcontroller. It’s an RP2040-based controller.

Controller pin	Connection
1	Handedness (V_CC on the left keyboard and GND on the right)
2	TRRS data
3, 4, 5, 6, 7	Matrix columns
20, 22, 26, 27	Matrix rows
13 (CS1)	Trackball SS
14 (SCK1)	Trackball SCK
15 (TX1)	Trackball MOSI
16 (RX1)	Trackball MISO

The TRRS connector is connected to Vcc, GND, and pin 2 (and similarly on the right side). Pin 1 is also connected to Vcc to signal to QMK that this is the left side of the keyboard, whereas pin 1 is connected to GND on the right controller.

The pmw3389 sensor attached beneath the trackball.

Adding the keyboard to QMK

The QMK cli has the qmk new-keyboard command that helps you get started. I couldn’t get the generated template to work for me, so I copied settings from an existing keybord with rp2042 support.

I’ll try to hit on the most important parts of the config, take a look at the source code for all details.

Basic setup

The folder structure for the keyboard looks like this:

cybershard
├── keyboard.json
├── rules.mk
├── halconf.h
├── mcuconf.h
└── keymaps
    └── default
        ├── config.h
        ├── keymap.c
        ├── rules.mk
        └── ...

(Cybershard is the name I eventually settled on for the keyboard.)

The most important part is keyboard.json that defines (almost) everything we need for a new keyboard in QMK.

First you need to set the processor, bootloader, and usb values. The Liatris microcontroller uses the RP2040 MCU, and I just picked some vendor- and product identifiers:

{
    "keyboard_name": "cybershard",
    "processor": "RP2040",
    "bootloader": "rp2040",
    "usb": {
        "device_version": "0.0.1",
        "pid": "0x0002",
        "vid": "0x0361"
    },
}

Then we need to define the matrix (with the pins we soldered) and the layout (how we’ll configure the keymap in keymap.c):

{
    "diode_direction": "COL2ROW",
    "matrix_pins": {
        // We need to use a `GP` prefix for the pins.
        "rows": ["GP26", "GP27", "GP22", "GP20"],
        "cols": ["GP3", "GP4", "GP5", "GP6", "GP7"]
    },
    "layouts": {
        "LAYOUT": {
            "layout": [
                // First physical row
                { "matrix": [1, 0], "x": 0, "y": 0 },
                { "matrix": [0, 1], "x": 0, "y": 0 },
                { "matrix": [0, 2], "x": 0, "y": 0 },
                { "matrix": [0, 3], "x": 0, "y": 0 },
                { "matrix": [0, 4], "x": 0, "y": 0 },

                // Second row
                { "matrix": [2, 0], "x": 0, "y": 0 },
                { "matrix": [1, 1], "x": 0, "y": 0 },
                { "matrix": [1, 2], "x": 0, "y": 0 },
                { "matrix": [1, 3], "x": 0, "y": 0 },
                { "matrix": [1, 4], "x": 0, "y": 0 },

                // etc...
            ]
        }
    }
}

Note that we can pick whatever physical pins we want as we can move around and configure them in software. The LAYOUT macro is what we use in keymap.c to define our keymap. When defining it we can choose to skip certain keys and reorganize it to be easier to define; for example, there’s no switch at 0,0 in my keyboard so I skip that.

The above LAYOUT can then be used like this:

LAYOUT(
 SE_J,    SE_C,    SE_Y,    SE_F,    SE_P,
 SE_R,    SE_S,    SE_T,    SE_H,    SE_K,
 SE_COMM, SE_V,    SE_G,    SE_D,    SE_B,
          SE_A,    SE_B,
                            // Thumb keys
                            FUN_CLR, MT_SPC,
),

Flashing

With the above setup we should be able to flash the keyboard by first entering the boot loader and running:

qmk flash -kb cybershard -km default

Now the process of updating the firmware is quite nice and unless I screw up I don’t need to connect another keyboard to do it.

Start flashing with qmk flash (it will wait until it finds a flashable target).
Press the QK_BOOT combo (the keyboard becomes unresponsive).
Wait until the script finishes and the keyboard is available again.

qmk flash first didn’t work for me and it always got stuck at:

Flashing for bootloader: rp2040
Waiting for drive to deploy...

After some digging around I found that the script is trying to copy a .uf2 file into a usb storage, and the controller will then reboot as a keyboard with something like this:

qmk compile -kb cybershard -km default
sudo mount /dev/sdX1 /media/sd
sudo cp cybershard_default.uf2 /media/sd/

After more frustration I found out that the flash scripts looks for a file called INFO_UF2.TXT under all drives mounted below /media. Because my system doesn’t mount usb drives by default the script would never find it and hang.

The simple solution is to start mounting usb drives automatically, which I did by installing udevil and running devmon on system startup.

Split keyboard

To get the split keyboard feature to work I had to set the SERIAL_DRIVER option in rules.mk:

SERIAL_DRIVER = vendor

And add the split configuration to keyboard.json and modify the LAYOUT macro:

{
    "split": {
        "enabled": true,
        // The pin that signals if the current controller is the left (high)
        // or right (low) controller.
        "handedness": {
            "pin": "GP1"
        },
        // The TRRS data pin.
        "soft_serial_pin": "GP2",
        "matrix_pins": {
            "right": {
                // We can override the pins for the right controller.
                // Note that GP26 and GP27 are swapped compared to the left side
                // due to a mistake I made when soldering.
                "rows": ["GP27", "GP26", "GP22", "GP20"],
                "cols": ["GP3", "GP4", "GP5", "GP6", "GP7"]
            }
        },
        "transport": {
            "sync": {
                // We need to sync the matrix state to allow combos, mods, and
                // other stuff to work.
                "matrix_state": true
            }
        }
    },
    "layouts": {
        "LAYOUT": {
            // The rows 0 to 3 specifies rows on the left side and
            // 4 to 7 the rows on the right side.
            "layout": [
                // These 5 keys are the first row on the left side.
                { "matrix": [1, 0], "x": 0, "y": 0 },
                { "matrix": [0, 1], "x": 0, "y": 0 },
                { "matrix": [0, 2], "x": 0, "y": 0 },
                { "matrix": [0, 3], "x": 0, "y": 0 },
                { "matrix": [0, 4], "x": 0, "y": 0 },
                // These 5 keys are the first row on the right side.
                { "matrix": [4, 0], "x": 0, "y": 0 },
                { "matrix": [4, 1], "x": 0, "y": 0 },
                { "matrix": [4, 2], "x": 0, "y": 0 },
                { "matrix": [4, 3], "x": 0, "y": 0 },
                { "matrix": [4, 4], "x": 0, "y": 0 },

                // etc..
            ]
        }
    }
}

The LAYOUT macro is just a function with many arguments but with the right order it can be formatted to look similar to the physical keyboard. For example, this is how the base layer of my keyboard could look like:

LAYOUT(
 // Left side                                    // Right side
 SE_J,    SE_C,    SE_Y,    SE_F,    SE_P,       SE_X,    SE_W,    SE_O,    SE_U,    SE_DOT,
 SE_R,    SE_S,    SE_T,    SE_H,    SE_K,       SE_M,    SE_N,    SE_A,    SE_I,    REPEAT,
 SE_COMM, SE_V,    SE_G,    SE_D,    SE_B,       SE_SLSH, SE_L,    SE_LPRN, SE_RPRN, SE_UNDS,
          // The extra two keys on the left side
          SE_MINS, SE_PLUS,
                            // Left thumb keys   // Right thumb key
                            FUN_CLR, MT_SPC,     SE_E
),

Trackball

It took a long time for me to get the trackball working (admittedly, mostly because I soldered the pins wrong). There’s quite a lot of documentation for QMK but curiously enough I didn’t find anything that covered the whole setup. I arrived here by trial and error, trying to piece together parts from other keyboards into a setup that worked for me.

First we need to create the files halconf.h and mcuconf.h (they go in the same folder as keyboard.json) to enable the SPI driver:

#pragma once
#include_next <halconf.h>
#define HAL_USE_SPI TRUE

#pragma once
#include_next <mcuconf.h>
#undef RP_SPI_USE_SPI1
#define RP_SPI_USE_SPI1 TRUE

And enable the pointing device with the pmw3389 device driver in rules.mk

POINTING_DEVICE_ENABLE = yes
POINTING_DEVICE_DRIVER = pmw3389

Now we need to add the sensor pins to config.h:

// SPI1, matching mcuconf.h
#define SPI_DRIVER SPID1
// The pin connections from the pmw3389 sensor
#define SPI_MISO_PIN GP12
#define PMW33XX_CS_PIN GP13
#define SPI_SCK_PIN GP14
#define SPI_MOSI_PIN GP15

This should be enough to get the sensor going, but because we have a split keyboard we need to set that up too:

#define SPLIT_POINTING_ENABLE
// The trackball is on the right
#define POINTING_DEVICE_RIGHT

There are some additional tweaks that I had to play with to make the trackball work well:

// The trackball is quite sensitive to how
// large the liftoff distance should be.
#define PMW33XX_LIFTOFF_DISTANCE 0x10
// Sets the mouse resolution, up to 16000.
#define PMW33XX_CPI 1600
// The directions where messed up, this fixes it.
#define POINTING_DEVICE_ROTATION_270 1
#define POINTING_DEVICE_INVERT_X 1

With that I got the trackball moves the mouse as expected.

Debug

As I struggled to get the trackball working I tried to use the debug output. I’ll include it here for completeness sake:

Enable the console in rules.mk:
```
CONSOLE_ENABLE = yes
```
Enable pointing device debugging in config.h:
```
#define POINTING_DEVICE_DEBUG
```

Turn on debugging in keymap.c:

void keyboard_post_init_user(void) {
    debug_enable = true;
    debug_mouse = true;
}

And then run qmk console from the command line.

Is this the ultimate keyboard?

No.

This keyboard is certainly the most comfortable keyboard I’ve used but it’s not close to being an “ultimate” keyboard. Here’s a few things that might improve the keyboard:

The trackball still isn’t nearly as comfortable as the Kensington SlimBlade.

Maybe a keyboard with a larger trackball would be better?
The extra keys on the left side are barely useful.

It’s not a big deal, maybe I can find some usage for them, but to me having barely useful keys feels wrong.
There are more extra features I feel an ultimate keyboard should have.

The keyboard I’ve built is nice… But it’s still just a normal keyboard with a trackball. Maybe a vibration sensor, a display, or even some LEDs? A smart knob with software-configurable endstops and detents would really add some weight to the moniker of an ultimate keyboard.

Next steps

It’s hard to know how good the keyboard is before I’ve put it through extensive use, and to do that I need to settle on a keyboard layout for the keyboard. I’ve already designed a layout for a 34-key keyboard that should be fairly straightforward to adapt but I still need to figure out how to add mouse keys and what to do with the “extra” keys on the left-hand side.

Check out The current Cybershard layout for how the keyboard layout is coming along.

The current Cybershard layout

2026-05-05T06:58:28+00:00

This is the keyboard layout I’m using for my custom keyboard that I generated, printed, and hand-wired. It’s a minimalistic keyboard of 35 keys and features an integrated trackball on the right-hand side.

The keyboard layout started out as a direct copy of the T-34 keyboard layout, with some small modifications from the 34-key keyboard T-34 was designed for:

An extra two keys on the left-hand side, in the ring and middle finger columns.
Removed the second thumb key on the right-hand side.
Accommodation for mouse keys and trackball handling.

While the layout has diverged since then, the design philosophy from original T-34 post still holds true and I recommend it as it may explain why the layout looks like it does.

Legend

I use quite a number of special features for the keys and I’ve tried to color code according to the above legend.

Layers

Layers are super important for smaller keyboards and I use them a ton.

Base

The repeat key is used to output the last pressed key.
I shift keys using auto shift (see long press) and CAPSWORD.
The letters Z and Q, together with a bunch of other keys, are on combos.
The keys for F2, F12 and FUN are just extras and aren’t in a comfortable enough position to warrant anything more common.

Swedish overlay

Swedish overlay.

When I want to write Swedish I activate this layer that replaces ()_ with åäö, or I use combos from any layer.

Symbols

Symbols layer.

I typically use combos to output symbols (following the same layout pattern as the symbols layer). The symbols layer is mostly used to roll symbol pairs like {} or #[.

Some common symbol sequences (like ->, != , or ```) exists as combos and others as long press.

Numbers

Numbers layer. The browner keys (like J) turn off NUMWORD.

While I can activate the number layer persistently (using leader sequences) I typically use combos for single digits (like 0), or NUMWORD for larger numbers (like 1984).

NUMWORD makes the number layer smart, so it will deactivate when certain keys are pressed. It’s used to type numbers in text or code and for relative movement in Neovim, where 17J would move 17 lines down and then turn off the number layer. Jumping directly to a line in Neovim with 12G is also made convenient.

If I want to enter the layer without it turning off I can either use leader sequences to activate it persistently or hold the NUMWORD combo (hold both thumbs). The layer won’t release until both thumb keys are released, so Space can be tapped with the left thumb without leaving the number layer.

@u is there to easily activate macros in Neovim. For example 7@u in the number layer would run the u macro 7 times and then turn off NUMWORD.

Function keys

Function keys.

The function keys follow the same layout as the numbers layer.
The trackball DPI can be lowered and raised at runtime.

Navigation layers

Navigation layer.

Left/Middle/Right Display are used to switch between displays in my window manager.
This layer is commonly used in conjunction with the trackball, giving access to mouse keys.

For instance, Shift + Left Mouse can be used to drag, Ctrl + A to select, and Ctrl + C to copy.
Tabbing is for switching browser tabs and the Back / Fwd mouse buttons goes backwards and forwards in history.
Ctrl + arrow is used to switch windows in Neovim.
Ctrl + D and Ctrl + U are used in Neovim to scroll half a screen (compared to PgUp/PgDn that scrolls an entire screen).
The workspace layer is triggered by first holding Space, and then holding the right thumb key (WNAV).

Arrows on the left-hand side.

This layer exists for the rare occasions I want to navigate using only the left hand.

The keys on the right side is there just because and are rarely, if ever, used. I typically use long press for shift and combos for other modifiers, the modifiers here is a fallback when those aren’t enough (but honestly, I can’t remember the last time I used them).

Niri layer

Keys used to control my window manager Niri.

I’m in the middle of migrating to Niri instead of xmonad and this is the layout I’m currently working on. I plan to replace my 3-monitor setup with a single super ultrawide, so this layout is still very much in flux.

Workspace layer

Workspace layer. All keys have an implicit Gui modifier.

This is used for all window and workspace management in xmonad / Niri. Some common operations are also on the navigation layer. Auto shift works and can used to send a window to another workspace (Gui + Shift + 2).

Windows layer

Windows layer. All keys have an implicit Alt modifier.

This is purely to enable window switching using Alt-Tab and Ctrl-Alt-Tab, without releasing Alt.

Mouse layer

The mouse layer for right-hand only usage.

I generally prefer to use the navigation layer, where the mouse buttons are on the left side, but in some cases I’d like to only use my right hand.

Special characters

Specials layer.

The dead keys add diacritic to any letter. For example, to get é you can use the dead key ´ then e, and the operating system will merge them together. (É also exists as a combo.)

Gaming

My gaming layer.

GAME2, the right half of a QWERTY keyboard.

GNUM, numbers on the left-hand side.

GFUN, function keys on the left-hand side.

I’m not a heavy gamer by any means but this setup allows me to play some games well enough. By necessity this layer disables auto shift.

Combos

Combos is another fantastic tool that I (ab)use a lot. Simply put it allows you to press multiple keys at once and acts as another key—very useful for smaller layouts.

Neighbour combos

These combos are made by keys next to each other, either horizontally (pressed with two fingers) or vertically (pressed with one finger in the middle of two keys).

2-key neighboring combos.

Some combos have a separate hold behaviour; for instance holding Escape activates the symbols layer, allowing me to output [] easily.
vsplit splits a window vertically in Neovim and hsplit splits it horizontally, and Close Window closes a window in Neovim (<C-w>q).
Clear resets all states; sets the base layer, releases modifiers, stops CAPSWORD and NUMWORD, and clears other persistent states.
Ctrl + Shift + M is the shortcut to mute/unmute in Teams.

3-key horizontal combos.

SWE activates the Swedish layer, and if prefixed with ()_ it will replace that with åäö and vice versa. So for example if I typed hall( I would press SWE to get hallå, with the Swedish layer activated.
Ctrl W is used to close tabs in Firefox.

A 4-key horizontal combo.

Save Neovim is a 4-key combo that saves the buffer in Neovim.

Split combos

These split combos uses the ring and index finger.

Combos for the quotes " and '.

Combos don’t have to be on the same row, these angled combos are fairly comfortable.

One-shot Alt on the left combo and holding the right combo activates the windows layer (with implicit Alt).

Leader key on the bottom row.

Combos over keyboard halfs

Tapping T + A once activates CAPSWORD, tapping again makes it persistent (CAPS LOCK), and a third tap to deactivate CAPS LOCK.
Tapping Space + E activates NUMWORD and tapping them again activates the number layer persistently.

The repeat key works with the above, making them easier to double-tap.

Swaps _ and -.

Access the specials layer with the ring fingers.

Thumb key combos

I have a bunch of 2-key thumb + key combos:

Combos using Space and another key.

Combos using E and another key.

The logic here is that same-side thumb + key = symbol and opposite-side thumb + key = digit, following the placements of the numbers, symbols and swedish layers. They’re used if I want to just type a single character, without having to activate a layer first.

Combos using FUN and another key.

I have similar combos for the function keys.

QMK boot

The keycode QMK_BOOT enters boot mode for the microcontroller connected via USB, making it easy to update the keymap on the keyboard. These two 5-key combos (one for each half) are almost impossible to trigger accidentally while being easily accessible.

Additional features

While layers and combos are the two main features I use, QMK has a lot of other nifty features (and you roll your own implementation of them too).

Long press

Most keys have a different behaviour when tapped compared to a long press. Most commonly I use this to produce shifted keys (called auto shift). So tapping the A key will output a as normal and if it it A will appear instead.

There are a bunch of special cases as well (many on top of combos):

Tap	Long press
`_` `<` `>` `/` `\` `#`	Double, e.g `__`
`"` `'` `=` ` `0` `.`	Triple, e.g `"""`
`\|` `&` `=`	Double with spaces, e.g `\|\|`
`!`	`!=` (with spaces)
`?`	`{:?}`
`#`	`{:#?}`
`%`	`%{}`
`(` `[` `{`	Close and move cursor between
`@`	`@u` (paired with `qu` combo for Neovim macro execution)

Leader sequences

I use the combo l + ) as the leader key. This will wait for a sequence of key presses (in contrast to combos where keys must be pressed at the same time). I use this with mnemonics for rarely used outputs:

Leader sequence	Action
`l` + `)`, `c`	Caps lock
`l` + `)`, `s`	Swedish input in Linux (mapped in xmonad)
`l` + `)`, `t`, `n`	Toggle Number layer
`l` + `)`, `t`, `s`	Toggle Symbols layer
`l` + `)`, `t`, `f`	Toggle Function layer
`l` + `)`, `t`, `c`	Toggle Caps lock escape swap
`l` + `)`, `Esc`	`Ctrl` `Shift` Escape

CAPSWORD

CAPSWORD is a “smart caps lock”. It works like a regular caps lock, except it automatically turns off after certain keys are typed (most commonly space).

It will not turn off on letters, numbers, _ - Backspace and the Repeat keys.

NUMWORD

NUMWORD is a “smart layer”. It’s similar to CAPSWORD, except it activates and then turns off the numbers layer instead of caps lock.

It will not turn off on these keys: 0-9 % / + * - _ . , : = x Backspace Enter and the Repeat keys.

Repeat key

The repeat key simply repeats the previous key. So to type fall I can type f a l Repeat, using four different fingers instead of pressing l twice. It can also repeat things like Ctrl-c or Delete, and unlike regular keys that use auto shift the Repeat key can be held.

Trackball

The trackball is normally configured to move the mouse as a regular trackball.

There are different modes that alters the behavior of the trackball:

Lower the DPI when Space or _ are held (the mouse moves slower when the navigation layer or the mouse layer are active).
Raise the DPI when the MOD combo is held (the mouse moves faster).
Scroll instead of moving the mouse when the SYM combo is held.

More info

Read the T-34 series for the design process and motivations of my other keyboard layout (it’s the same layout with minor refinements and additions).
See the post Building my ultimate keyboard for how I designed and built the keyboard I’m using this layout with.
For implementation details and the most up-to-date reference check out the layout’s QMK source code.

I use a bunch of custom re-implementations of existing QMK functionality and it’s probably not a good idea to copy them. They’re there for various reasons, such as CAPSWORD not being integrated into QMK when I started using it and I can’t be bothered to migrate over.

The code is super messy and in desperate need of refactoring…

November 19, 2024

Copied the T-34 layout and adapted it for the new keyboard by adding a mouse layer, remove the shortcut layer, and changed the activation of the specials layer.
November 22, 2024

Moved - to an angled combo, moving the WIN key to the top row, and move % to the home-row and ! to the bottom row.
November 23, 2024

Reworked the mouse layer and use a more advanced triggering mechanism to be more explicit about when the layer is turned on and off.
November 25, 2024

Added double-tap functionality to NUMWORD and CAPSWORD combos.
November 26, 2024
1. Moved - back to it’s original position and placed % on the angled combo.
2. Experimental functionality to swap - and _ for the languages that use kebab-case.
3. Removed the mouse layer and placed mouse buttons on the navigation layer.
December 3, 2024

Reworked the navigation layer to keep the original positions for PgUp, PgDn, and Tabs. To allow this I moved the mouse click to index finger and demoted the up/down to the top row.
January 12, 2025
1. Reworked the navigation layer to be more focused on two hands on the board. The idea is to use better placed keys on the right-hand side instead of cramming in too much on the left. Moved PgUp and Home to the right side and it’s enough to use the arrow keys on the right. (The secondary navigation layer exists to enable arrow keys on the left side.)
2. Added mouse button combos on the right-hand side so in a pinch I can operate the mouse with one hand.
January 14, 2025
1. Removed mouse button combos from the right-side and place them on a separate layer instead (to keep the shift combo in the regular place).
2. Add Gui + ,/. for xmonad master window management to the navigation layer, moving Ctrl + A to the home-row once again.
January 20, 2025

Added the gaming layer.
December 22, 2025

Expanded the gaming setup with more than one layer to be more complete, giving access to most of a regular keyboard.
May 5, 2026

A first draft of the Niri layer for use with the window manager Niri, replacing xmonad. Bunch of keys were removed from the navigation layer as I instead have a dedicated layer. It’s accessed by holding down the Tab combo and extra modifiers were instead moved to the Arrow layer.

Why I don't rely on AI for programming (too much)

2024-10-31T08:31:27+00:00

I find that ai can help significantly with doing plumbing, but it has no problems with connecting the pipes wrong. I need to double and triple check the updated code - or fix the resulting errors when I don’t do that.

thih9 on Hacker News

I’ve been skeptical of the AI craze that’s been going on in the developer community. It’s a useful tool but some people behave like large swaths of developers will be replaced by AI tomorrow.

I don’t understand the hype as my experience has been quite different, yet I’ve struggled to pinpoint why. In this post post I’ll try to explain what I think is the fundamental problem I have with letting an AI generate code for me.

I’m bad at double-checking code

I realized what my problem with AI is when I read this comment on Hacker News (emphasis mine):

My theory is the willingness to baby sit and the modality. I’m perfectly fine telling the tool I use its errors and working side by side with it like it was another person. At the end of the day it can belt out lines of code faster than I, or any human, can and I can review code very quickly so the overall productivity boost has been great.

ianbutler on Hacker News

It’s true that I’m not fond of pair programming but the key issue is that I can’t review code quickly. On the contrary I’m quite bad at looking at an unknown piece of code and verify that it’s correct.

Struggling to verify math problems

This isn’t a problem of mine that’s unique for programming. I’ve been quite good at math (relatively speaking) since I was a child and I breezed through the University math (where I read as many math courses I could get my hands on).

Despite my relative skills I always got marks against me during tests and exams. They weren’t caused by my lack of understanding but by small mistakes like writing numbers wrong. Mistakes that I tried hard to correct; I started to double-check and triple-check my work but they were still slipping through.

I realized that when I was first solving the problem I was focused. I was in the zone and I could keep the problem in my head while I worked.

But when I went back to verify my work my brain wouldn’t engage in the same way. I was trying to but I couldn’t get into the zone. The problem was Done™ and it was like my brain had disengaged. If I was looking at myself in a third-person view I’m sure my eyes would glaze over.

It’s hard to read code without a mental model

When we write code or solve math problems I think we build up a mental model of the problem we’re trying to solve and the system we’re interacting with; what a variable name signifies, what effects a function call might have, and how pieces of information relate to one another.

This mental model is crucial when reading code or solving math problems and if it’s missing we need to rebuild it. I think this is what happened when I had finished my math problems: when I was finished I dropped the model, so coming back to it was a struggle.

The same is true when reviewing code; you’ll be much more effective when reviewing small changes to a code base you’re familiar with because you already have a mental model of the surrounding systems. It becomes harder when you’re reviewing larger changes, or reviewing changes in an unfamiliar code base, because you have more gaps in your mental model.

I struggle to properly review code

Maybe it’s a skill issue but I find it much more difficult to find errors in code others write (or I myself wrote a while ago) than to find errors while I’m developing the code. I get the same “eye glazes over” feeling as when I went back to verify my math problems. I’m slow, I know I’m not doing a good job, and it’s a struggle.

I truly wonder how other people review code in a productive way. Sometimes I feel I need to run, change, and test the code to understand it… But that’s time consuming especially as the amount of code increases. Trusting your fellow developers seems like a necessity.

AI generated code requires careful verification

Some are enamored with how great AI code generation is. And to be sure, compared to just a few years ago it’s unbelievably good. But would I trust the code as much as I’d trust a co-worker? Absolutely not.

In my experience an AI is at best as good as a new developer, often much worse, and sometimes outright horrible. (And no, I don’t blindly trust a new developer. I don’t trust myself either.) At least I can be reasonably sure that other developers test or run their code before I need to look at it.

Relying on AI is like copy pasting code from Stack Overflow: useful but you cannot trust it. While the code may look good on a surface level, it’s often subtly wrong in ways that even a Stack Overflow answer doesn’t quite manage to. Hallucinating a non existing library function or adding an extra argument are quite common.

This is mostly fine for short snippets where it’s easy to run the code and test but the problem becomes significant when you ~~copy paste~~ rely on AI for larger pieces of code.

Programming less and reviewing more is a bad trade

The crux of the matter is that I’m much more productive when I’m programming than when I’m reviewing code. With most current AI tools it feels like I’m reviewing code more than programming and that’s a bad trade for me to make.

You still need to build a mental model

While you’re writing code you’re continually building up your mental model but when you let an AI generate the code you still need to do the hard work of building your mental model.

I don’t think writing code is the most important thing you’re doing while programming—it’s building a mental model of the system you’re building.

There’s no return of your investment

Ever felt that it would be faster to just code something yourself than to gently guide a junior developer through a problem? That’s how I feel like when I shepherd an AI, with the difference that teaching a junior programmer is an investment but the AI won’t learn no matter how many times you interact with it.

Some AI tools are very useful

I need to clarify that while I’m skeptical towards the current AI hype I find some AI tools useful in various contexts.

For programming I’m a heavy user of Kagi’s quick answer functionality that uses AI to summarize the search results and gives you references so you can drill down further if you need to. I use it many times a day to answer questions like:

How do you format a date in Python?
How do you subscribe to a table change in postgres in Elixir?
How do you open a new buffer in Neovim using Lua?
How to order mp4 by length in Linux?
What’s the cron syntax to execute a script every second day?

It’s not bullet proof but the combination of good search results (way better than Google in my opinion) combined with AI’s summarizing ability is absolutely fantastic.

I must be missing something

AI dev tools are useful, I just haven’t seen the incredible productivity boost that some say exist. Maybe they are working on different problems in different contexts than I am, have different standards, or just are better at utilizing them than I am?

Because, surely, it would be way to simple to dismiss the productivity claims as people evaluating the tools as how useful they may become instead of how useful they are right now?

xkcd: 605; ever relevant as a response to the currently hyped technology.

Writing Home Assistant automations using Genservers in Elixir

2025-03-21T06:31:42+00:00

I’ve been a fan of Home Assistant a while now; it’s a great platform for home automation with its beginner friendly and feature rich UI, support for a ton of different devices and integrations, and there’s a bunch of ways to create automations.

But there’s no engine for writing automations in Elixir that I could find; this post addresses this fatal weakness.

Specifically, in this post I’ll go through:

How to use Home Assistant’s Websocket API.
An introduction to GenServers and concurrency in Elixir.
How to use this knowledge to write and test a simple automation.

Why Elixir?

Ever since I started with home automation I’ve thought that it would be a great match for the concurrency model that Elixir uses. You’ll have all sorts of automations running concurrently, reacting to different triggers, waiting for different actions, and interacting with each other; something I think Elixir excels at.

Now, there are many options for writing automations for Home Assistant that already work well, the biggest reason I wanted to use Elixir is because I like it. That Elixir happens to be a good fit for home automation is just a bonus.

I’ve tried to write automations via the Home Assistant UI (meh), using YAML configuration (hated it), visual programming with Node-RED (I want real programming), and in Python using Pyscript (pretty good). In the end I simply enjoyed writing automations in Elixir more.

Controlling Home Assistant from Elixir

The very first thing we need to solve is how do we get data from Home Assistant and how to call services (now called actions)?

Home Assistant has a websocket API and a REST API that we can use to implement our engine. As we can get entity states and call services over the websocket there’s no need to bother with the REST API for our example.

Connecting

I used WebSockex to setup the websocket connection to Home Assistant. Here’s a tentative start that connects and receives a message:

defmodule Haex.WebsocketClient do
  use WebSockex
  require Logger

  # Adjust to your Home Assitant instance
  @url "ws://lannisport:8123/api/websocket"

  def start_link(_args) do
    WebSockex.start_link(@url, __MODULE__, %{}, name: __MODULE__)
  end

  @impl true
  def handle_frame({:text, msg}, state) do
    case Jason.decode(msg) do
      {:ok, msg} ->
        Logger.debug("Received:\n#{inspect(msg)}")
        handle_msg(msg, state)

      {:error, error} ->
        Logger.warning("Couldn't decode message `#{inspect(error)}`:\n#{inspect(msg)}")
        {:ok, state}
    end
  end

  defp handle_msg(msg, state) do
    Logger.warning("Unhandled message: #{inspect(msg)}")
    {:ok, state}
  end
end

As with all concurrent services in Elixir Websockex should be started in a supervision tree. Under the main Application Supervisor works well:

defmodule Haex.Application do
  @moduledoc false

  use Application

  @impl true
  def start(_type, _args) do
    children = [Haex.WebsocketClient]
    Supervisor.start_link(children, strategy: :one_for_one)
  end
end

If we run this then Home Assistant will send us a message upon connection:

[warning] Unhandled message: %{"ha_version" => "2024.10.0", "type" => "auth_required"}

This means we need to authenticate using a long lived access token. Reading the websocket API we should respond with an "auth" message:

defp handle_msg(%{"type" => "auth_required"}, state) do
  token = Application.fetch_env!(:haex, :access_token)

  reply =
    Jason.encode!(%{
      type: "auth",
      access_token: token
    })

  {:reply, {:text, reply}, state}
end

It’s prudent to fetch secrets from environment variables in runtime.exs:

config :haex, access_token: System.fetch_env!("HA_ACCESS_TOKEN")

And now we get another unhandled message, telling us our auth succeeded:

[warning] Unhandled message: %{"ha_version" => "2024.10.0", "type" => "auth_ok"}

Subscribing to state changes

After authenticating we can tell Home Assistant that we’d like to subscribe to all state changes in the system (so we can write automations that trigger on a state change).

I’m lazy so I send the subscription message when I’m handling (ignoring) the "auth_ok" message:

defp handle_msg(%{"type" => "auth_ok"}, state) do
  reply = Jason.encode!(%{id: 1, type: :subscribe_events, event_type: :state_changed})
  {:reply, {:text, reply}, state}
end

With this up we’ll get another acknowledgment that our subscribe command succeeded (matching id: 1):

[warning] Unhandled message: %{"id" => 1, "result" => nil, "success" => true, "type" => "result"}

And we start receiving state changed messages:

[warning] Unhandled message: %{"event" => %{"context" => %{"id" => "01J9DK3CN0CEEWGCV1139HTC11", "parent_id" => nil, "user_id" => nil}, "data" => %{"entity_id" => "sensor.vardagsrum_innelampor_switch_power", "new_state" => %{"attributes" => %{"device_class" => "power", "friendly_name" => "Vardagsrum innelampor switch Power", "state_class" => "measurement", "unit_of_measurement" => "W"}, "context" => %{"id" => "01J9DK3CN0CEEWGCV1139HTC11", "parent_id" => nil, "user_id" => nil}, "entity_id" => "sensor.vardagsrum_innelampor_switch_power", "last_changed" => "2024-10-05T05:40:36.640422+00:00", "last_reported" => "2024-10-05T05:40:36.640422+00:00", "last_updated" => "2024-10-05T05:40:36.640422+00:00", "state" => "4.6"}, "old_state" => %{"attributes" => %{"device_class" => "power", "friendly_name" => "Vardagsrum innelampor switch Power", "state_class" => "measurement", "unit_of_measurement" => "W"}, "context" => %{"id" => "01J9DK37CMJBDFK7M5VGYJ1CZG", "parent_id" => nil, "user_id" => nil}, "entity_id" => "sensor.vardagsrum_innelampor_switch_power", "last_changed" => "2024-10-05T05:40:31.252863+00:00", "last_reported" => "2024-10-05T05:40:31.252863+00:00", "last_updated" => "2024-10-05T05:40:31.252863+00:00", "state" => "4.5"}}, "event_type" => "state_changed", "origin" => "LOCAL", "time_fired" => "2024-10-05T05:40:36.640422+00:00"}, "id" => 1, "type" => "event"}
[warning] Unhandled message: %{"event" => %{"context" => %{"id" => "01J9DK3CQ27BWBX0R9MAP5SRM9", "parent_id" => nil, "user_id" => nil}, "data" => %{"entity_id" => "sensor.dishwasher_plug_voltage", "new_state" => %{"attributes" => %{"device_class" => "voltage", "friendly_name" => "Dishwasher plug Voltage", "state_class" => "measurement", "unit_of_measurement" => "V"}, "context" => %{"id" => "01J9DK3CQ27BWBX0R9MAP5SRM9", "parent_id" => nil, "user_id" => nil}, "entity_id" => "sensor.dishwasher_plug_voltage", "last_changed" => "2024-10-05T05:40:36.706679+00:00", "last_reported" => "2024-10-05T05:40:36.706679+00:00", "last_updated" => "2024-10-05T05:40:36.706679+00:00", "state" => "232.5"}, "old_state" => %{"attributes" => %{"device_class" => "voltage", "friendly_name" => "Dishwasher plug Voltage", "state_class" => "measurement", "unit_of_measurement" => "V"}, "context" => %{"id" => "01J9DK37THDW13GTP09KXNMG0Q", "parent_id" => nil, "user_id" => nil}, "entity_id" => "sensor.dishwasher_plug_voltage", "last_changed" => "2024-10-05T05:40:31.697304+00:00", "last_reported" => "2024-10-05T05:40:31.697304+00:00", "last_updated" => "2024-10-05T05:40:31.697304+00:00", "state" => "232.18"}}, "event_type" => "state_changed", "origin" => "LOCAL", "time_fired" => "2024-10-05T05:40:36.706679+00:00"}, "id" => 1, "type" => "event"}
...

Managing cross-service messages with PubSub

At this point I’d like to take a step and plan ahead a little. We have our state changed events but how should we send them to the automations we’ll write?

One option might be to let WebSocketClient loop over all automations and call them directly:

defp handle_msg(msg = %{"type" => "event"}, state) do
  for automation <- automations do
    automation.state_changed(msg)
  end

  {:ok, state}
end

But that’s not very flexible. We’d have to keep the automations list updated and what about other services that might want to subscribe to state changes but aren’t automations?

Instead I opted to use Phoenix.PubSub, a publisher/subscriber service that can broadcast messages throughout your application.

First we’ll need to start an instance in our supervision tree (called Haex.PubSub):

@impl true
def start(_type, _args) do
  children =
    [
      {Phoenix.PubSub, name: Haex.PubSub},
      Haex.WebsocketClient
    ]

  Supervisor.start_link(children, strategy: :one_for_one)
end

Then we can broadcast messages to anyone who cares to listen:

defp handle_msg(%{"type" => "event", "event" => event}, state) do
  Phoenix.PubSub.broadcast(
    Haex.PubSub,
    "state_schanged",
    {:state_changed,
     %{
       entity_id: event["entity_id"],
       new_state: event["new_state"],
       old_state: event["old_state"]
     }}
  )

  {:ok, state}
end

If a service wants to receive the messages they’ll subscribe to the "state_changed" channel:

Phoenix.PubSub.subscribe(Haex.PubSub, "state_changed")

Calling services

There’s key component left and that’s how do call a service / execute an action?

You call a service by sending this type of message over the websocket:

# This message turns on a light.
%{
  id: 2,
  type: :call_service,
  domain: :light,
  service: :turn_on,
  target: %{
    entity_id: "light.j_kontor_dator_ledstrip"
  }
  service_data: %{
    color_name: "beige",
    brightness: 100
  }
}

You’ll then receive a successful result message corresponding to the id of the message. You’re supposed to correlate the ids of the messages you send and receive, but it’s not central to this post so I’ll gloss over that implementation detail.

Outline of a GenServer automation

I decided to create automations as regular GenServers that subscribes to triggers and then does stuff. An automation might look like something like this:

defmodule Automations.MyAutomation do
  use GenServer
  alias Phoenix.PubSub

  def start_link(opts) do
    GenServer.start_link(__MODULE__, opts)
  end

  @impl true
  def init(_opts) do
    PubSub.subscribe(Haex.PubSub, "time")
    {:ok, %{}}
  end

  @impl true
  def handle_info({:time, time}, state) do
    # Do something at a specific time
    {:noreply, state}
  end
end

If you’re unfamiliar with GenServers then the gist is that a GenServer is an isolated process that receives messages and should be started in a supervision tree.

In the above example we subscribe to the "time" channel and then receive a message with the handle_info callback. (The "time" message is generated from a "state_changed" message for the entity sensor.time that’s updated every minute.)

Let there be light

It’s finally time for the ultimate expression of home automation:
controlling a light source.

Gentlemen I am now about to send a signal from this laptop through our local ISP racing down fiber-optic cable at the speed of light to San Francisco, bouncing off a satellite in geosynchronous orbit to Lisbon Portugal where the data packets will be handed off to submerge transatlantic cables terminating in Halifax Nova Scotia, and transferred across the continent via microwave relays back to our ISP and the XM receiver attached to this…

Lamp.

Big Bang Theory: Internet success

Jokes aside, controlling a light is great because it’s easy to start with (turn on/off), you’ll get to see results in the real world (the light changes color), and you can increase the complexity if you want (create a sunrise alarm, use circadian lighting, flash during a fire alarm, etc).

Time trigger

Let’s ease into an automation by turning on a light on a specific time:

defmodule Automations.BedroomLight do
  use GenServer
  alias Phoenix.PubSub
  alias Haex.Light

  # This is the Home Assistant entity I want to control.
  @entity "light.jonas_bedroom_lamp"

  def start_link(opts) do
    GenServer.start_link(__MODULE__, opts)
  end

  @impl true
  def init(_opts) do
    PubSub.subscribe(Haex.PubSub, "time")
    {:ok, %{}}
  end

  @impl true
  def handle_info({:time, time}, state) do
    # Note that time only ticks every minute so seconds will always be zero.
    if time == ~T[06:00:00] do
      Light.turn_on(@entity, color_name: "yellow", brightness_pct: 80, transition: 10)
    end

    {:noreply, state}
  end
end

Wake-up lighting

That was easy. Let’s try something bit more interesting: a wake-up sequence.

Specifically I’d like to gradually change the brightness and color of the light from a dim red to a bright, white light.

We could hardcode it with something like this:

 def handle_info({:time, time}, state) do
   cond do
     time == ~T[06:00:00] ->
       Light.turn_on(@entity, brightness_pct: 10, color_name: "red", transition: 450)

     time == ~T[06:10:00] ->
       Light.turn_on(@entity, brightness_pct: 70, color_name: "orange", transition: 450)

     time == ~T[06:20:00] ->
       Light.turn_on(@entity, brightness_pct: 80, color_name: "gold", transition: 450)

     time == ~T[06:30:00] ->
       Light.turn_on(@entity, brightness_pct: 100, kelvin: 2700, transition: 450)

     true ->
       nil
   end

   {:noreply, state}
 end

But that’s not flexible if we for example want the start time to be configurable via the UI in the future. While refactoring it let’s try to implement the transitions using a message passing approach:

@impl true
def handle_info({:time, time}, state) do
  if time == ~T[06:00:00] do
    send(self(), :transition_sunrise)
    {:noreply, Map.put(state, :light_state, {:sunrise, 0})}
  else
    {:noreply, state}
  end
end

At line 3 we’re using send() to send the message :transition_sunrise to ourselves and at line 4 we’re tracking inserting :light_state as {:sunrise, 0}, to let the GenServer keep track of what transition we should perform.

This message is again handled by handle_info:

def handle_info(:transition_sunrise, state = %{light_state: {:sunrise, _}}) do
  case set_sunrise_light(state) do
    :done ->
      # We've reached our last transition.
      {:noreply, Map.put(state, :state, :day)}

    {:next, next} ->
      # We still have transitions left to handle,
      # send another :transition_sunrise message after 10 minutes,
      # repeating the loop.
      Process.send_after(self(), :transition_sunrise, 10 * 60 * 1000)
      {:noreply, Map.put(state, :light_state, {:sunrise, next})}
  end
end

The function set_sunrise_light sets the light depending on {:sunrise, sunrise_state} and returns :done when we’ve set the last transition. Pay attention to line 10 where we send another :transition_sunrise message but with a delay, continuing the recursion until we’ve set handled all transitions.

I’m not thrilled about the implementation of set_sunrise_light but here it is:

 defp set_sunrise_light(%{light_state: {:sunrise, sunrise_state}}) do
   transitions =
     [
       [brightness_pct: 10, color_name: "red", transition: 450],
       [brightness_pct: 70, color_name: "orange", transition: 450],
       [brightness_pct: 80, color_name: "gold", transition: 450],
       [brightness_pct: 100, kelvin: 2700, transition: 450]
     ]
     # Transform the list into a map with index => transition.
     # Yes, it's a shoddy imitation of an array.
     |> Enum.with_index()
     |> Map.new(fn {val, index} -> {index, val} end)

   last_state = Enum.count(transitions) - 1

   {light_opts, next_transition} =
     if sunrise_state >= last_state do
       {transitions[last_state], :done}
     else
       {transitions[sunrise_state], {:next, sunrise_state + 1}}
     end

   Light.turn_on(@entity, light_opts)

   next_transition
 end

Abort the wake-up sequence

I’d like to add the ability to abort the sunrise alarm by turning off the lamp. It’s fairly straightforward:

Subscribe to a state change:
```
PubSub.subscribe(Haex.PubSub, "state:" <> @entity)
```
(I use a simplified message instead of the raw "state_changed" message we’ve seen before.)

Change the state if we’re in a sunrise:

def handle_info({:state, @entity, "off"}, state = %{state: {:sunrise, _}}) do
  {:noreply, Map.put(state, :state, :day)}
end

def handle_info(_, state) do
  {:noreply, state}
end

We still have a :transition_sunrise message that will arrive later but the fallback handle_info will ignore it. If we’ll implement a snooze or restart for our sunrise this may become a problem.

Refactoring into another GenServer

What we’ve done so far works but the structure isn’t ideal. The leftover :transition_sunrise message bothers me and what if we want to implement another light transition, either for a bedtime routine or for another light? Then we’d have to re-implement a large portion of the automation, which isn’t my idea of fun.

We can break out the code into another GenServer, let’s call it LightTransition, and we can let it keep track of the transitions and lets us focus on the more interesting parts of automation writing.

This lets us start a sunrise with something like this:

if time == ~T[06:00:00] do
  {:ok, transition_pid} =
    LightTransition.start_link(
      entity_id: @entity,
      transitions: [
        [brightness_pct: 10, color_name: "red", transition: 450],
        [brightness_pct: 70, color_name: "orange", transition: 450],
        [brightness_pct: 80, color_name: "gold", transition: 450],
        [brightness_pct: 100, kelvin: 2700, transition: 450]
      ]
    )

  state =
    state
    |> Map.put(:light_state, :sunrise)
    |> Map.put(:transition, transition_pid)

  {:noreply, state}

At line 2 we start our transition using start_link, foregoing the supervision tree as it doesn’t make sense to have the transition without the automation. We keep track of the service process id at line 15, which we can use to stop the transition if needed:

GenServer.stop(state.transition)

LightTransition itself is fairly straightforward when we don’t have to keep track of the transition state:

defmodule Haex.LightTransition do
  use GenServer
  alias Haex.Light

  def start_link(opts) do
    GenServer.start_link(__MODULE__, opts)
  end

  @impl true
  def init(opts) do
    send(self(), :transition)
    {:ok, Map.new(opts)}
  end

  @impl true
  def handle_info(:transition, state) do
    case state.transitions do
      [] ->
        {:stop, :normal, state}

      [light_opts | rest] ->
        Light.turn_on(state.entity_id, light_opts)

        timer = Process.send_after(self(), :transition, light_opts.transition)
        {:noreply, Map.merge(state, %{transitions: rest, timer: timer, last: light_opts})}
    end
  end
end

With this in place we can support pause and resume by using Process.read_timer() and Process.cancel_timer():

@impl true
def handle_call(:pause, _, state = %{timer: timer}) do
  time_left = Process.read_timer(timer)
  Process.cancel_timer(timer)

  state =
    state
    |> Map.put(:time_left, time_left)
    |> Map.delete(:timer)

  {:reply, :ok, state}
end

def handle_call(:resume, _, state = %{time_left: time_left}) do
  Light.turn_on(state.entity_id, state.last)
  timer = Process.send_after(self(), :transition, time_left)

  state =
    state
    |> Map.put(:timer, timer)
    |> Map.delete(:time_left)

  {:reply, :ok, state}
end

I think things turned out pretty well in the end.

State machines are great

So far we only have a sunrise alarm, but it’s easy to imagine more features that our humble lamp could support:

Snooze the wake-up light (using the above pause/resume functionality).
Circadian lighting.
A bedtime transition, similar to a reverse wake-up light except it shouldn’t force the light on.
A “max power mode” that sets the light to max brightness, triggered by toggling on/off quickly. Should only end when you turn off the light.
The all-important “sexy time” mode.
If a fire alarm goes off, flash the light in an aggressive way. Should of course override every other mode.

While you could implement them all as separate automations, the more you add the harder it gets to keep them from interfering with each other. You wouldn’t want your sexy time to be interrupted would you?

An alternative is to use a state machine to track the different states, making the state transitions more explicit. Our automation is already a simple state machine and it’s fairly easy to add more states and more functionality to it.

Automation testing

An automation is just an Elixir GenServer, so the same strategies to test a GenServer applies here too. I’ll start with the test I want to write, and we’ll work backwards to make it work:

test "trigger sunrise", %{server: server} do
  # Start the sunrise by sending a time message to the automation.
  send(server, {:time, ~T[06:00:00]})

  # Assert that we'll eventually receive the sunrise transitions.
  assert eventually(fn ->
           [
             %{brightness_pct: 100, kelvin: 2700},
             %{brightness_pct: 80, color_name: "gold"},
             %{brightness_pct: 70, color_name: "orange"},
             %{brightness_pct: 10, color_name: "red"},
             %{brightness_pct: 1, color_name: "red"}
           ] =
             WebsocketClientCollector.get_messages(
               get_service_data: true
             )
         end)
end

An isolated GenServer

The first thing we’ll need to do is to start the GenServer so we can start interacting with it. We don’t need a supervision tree so we can start it directly and send it to the test:

setup _opts do
  {:ok, server} = BedroomLight.start_link([])
  %{server: server}
end

test "trigger sunrise alarm", %{server: server} do
  # ...
end

I like to test against isolated GenServers as it allows parallel testing and it reduces the risk of contamination from other parts of the application.

Alter the code to be able to test?

If we run this test we’ll notice that the automation will only output the first sunrise transition. What gives?

Remember this line?

Process.send_after(self(), :transition_sunrise, 10 * 60 * 1000)

It says that we’ll continue the sunrise transition after 10 minutes. Nobody wants to wait that long for a test to finish…

To get around this I added an option to the automation so that we can override the delay to 1 millisecond during the test:

setup opts do
  opts = Map.put_new(opts, :transition_time, 1)
  {:ok, server} = BoysRoofLight.start_link(opts)
  %{server: server}
end

# And in the automation:
transition_time = state[:transition_time] || 10 * 60 * 1000
Process.send_after(self(), :transition_sunrise, transition_time)

I don’t like modifying code just to make tests work but in this case I think it’s a reasonable workaround.

The eventually helper

I want to touch on the eventually helper that I think is super useful when testing processes in Elixir. It comes in handy whenever I want to wait for a message to be delivered or wait for a process to reach a certain state.

Here it is:

def eventually(func, timeout \\ 1_000) do
  # Use Task to be able to timeout the execution.
  task = Task.async(fn -> _eventually(func) end)
  Task.await(task, timeout)
end

defp _eventually(func) do
  try do
    if func.() do
      # Return true so we can use it in an `assert` statement.
      true
    else
      Process.sleep(10)
      _eventually(func)
    end
  rescue
    # Safe up so we don't have to bother with proper matches etc
    # inside the predicate function.
    _ ->
      Process.sleep(10)
      _eventually(func)
  end
end

Careful use of checkpoints in our tests, where we wait for a state to be fulfilled, is much preferable over sprinkling Process.sleep() in our tests, hoping that the race conditions will go away.

Capturing sent websocket messages

The last thing we need is to capture outgoing websocket messages. In fact we also need to block the websocket connection because as it is now the full application will run when we run then tests, including connecting to our Home Assistant instance and start receiving state changed events.

We can do this by replacing the websocket client during tests. The application config is a good place for these settings:

config :haex,
  ws_client: Haex.WebsocketClient

config :haex,
  ws_client: WebsocketClientCollector,

Then when we send a message we delegate to the proper client:

def send(data) do
  ws_client().send(data)
end

def ws_client() do
  Application.fetch_env!(:haex, :ws_client)
end

All WebsocketClientCollector does is collect sent messages by process id and is able to return a list of them:

defmodule WebsocketClientCollector do
  use GenServer

  def send(msg) do
    GenServer.call(__MODULE__, {:send, msg})
  end

  def get_messages(opts \\ []) do
    GenServer.call(__MODULE__, {:get_messages, opts})
  end

  # Skipped the implementation ...
end

With this our test for the sunrise alarm should pass!

Beware of race conditions

Tests in an asynchronous and concurrent system—where messages don’t arrive immediately and where services interact with each other—can be very annoying to deal with as it’s easy to introduce race conditions, where a test sometimes fail.

Consider this test where we’ll test that the sunrise is aborted if the light is turned off in the middle:

@tag transition_time: 10
test "turn off light after sunrise alarm has begun halts it", %{server: server} do
  send(server, {:time, ~T[06:00:00]})

  assert eventually(fn ->
           :sunrise = BedroomLight.get_state(server)
         end)

  # Should stop the sunrise
  send(server, {:state, @entity, "off"})

  assert eventually(fn ->
           :day == BedroomLight.get_state(server)
         end)

  assert Enum.count(WebsocketClientCollector.get_messages(server)) == 1
end

Even though it appears we’re avoiding race conditions by waiting for the automation to change its internal state at line 4 and 11, this test may still fail on occasion.

The issue is that on the last line we’re testing that we only received a single sunrise transition. But we set a transition time of 10 milliseconds on line 0, and sometimes the messages arrive in such a way that the automation manages to transition twice.

To add some leeway in our test we might try to change the condition to < 4 and to increase the transition time…

What’s next?

We already have a working home automation engine that can be used as-is to control our home. But there are a couple of features that are missing and would enhance the system, for example:

Cron style support.

We can add cron-like scheduling to our automations using libraries such as Quantum or Oban.
A simpler API for simpler automations.

While GenServers are great in many ways they’re a bit verbose for simple automations. I took inspiration from AppDaemon’s listen_state for a simpler API:
```
# This automation turns on a ledstrip behind my monitors when the plug power
# is above 180, which happens when I turn on my three monitors.
listen_state(
  "sensor.winterfell_plug_power",
  fn ->
    Light.turn_on("light.j_kontor_dator_ledstrip", color_temp: 220, brightness_pct: 40)
  end,
  gt: 180
)
```
listen_state is implemented by—you guessed it—a GenServer. listen_state registers a trigger callback together with some trigger conditions within the GenServer, then the server calls the callbacks whenever the conditions are met. This way we don’t need to mess with the internals of a GenServer and can use a declarative approach to create simpler automations.
Querying entity states.

Sometimes we want to only execute an automation if an entity has a specific value, for example:
```
if is_on("input_boolean.doorbell_sound_enabled") do
  # Trigger doorbell
end
```
I support this with the States GenServer that holds the state of every entity in Home Assistant. At startup it fetches all states and uses the state changed event we’ve seen before to keep it in sync.
Generate automation entities.

Home Assistant dashboard to enable/disable automations.

I want to be able to enable and disable the automations in the system. I’ve been manually creating input_boolean.<automation>_enabled entities, but our automation engine could create these manually. We could keep track of when the automation was last triggered and display the internal state of automations for debugging purposes.

To set states (and create entities) we need to use the REST API.

There’s probably a bunch of things I haven’t yet realized that I need, but at the moment I’m really happy with writing my home automations in Elixir.

Trying and returning the Eight Sleep Pod 4

2025-05-16T10:52:05+00:00

I recently bought the Eight Sleep Pod 4—a smart mattress cover that tracks your heart rate, HRV, snoring, and cools or warms the mattress during the night. There’s a lot to like about the mattress but in the end I opted to return it.

This post describes my experience with the Pod 4.

Sleep is important enough to offset the steep price

The Eight Sleep mattress is really expensive but that’s not all—it’s a mattress with a subscription! I hated it when Oura introduced a subscription for their ring, and I hate the world that led us to a mattress with a subscription.

So why bother with the ridiculous pricing?

Because sleep is important.

What would 60 or even 30 minutes of extra sleep per day be worth? Or maybe the same amount of sleep but better? For me, as a parent of young kids that wakes up way too early, the answer is that it would be worth a lot.

That’s why I was able to look past the price and give Eight Sleep a chance.

My experience with the smart mattress

There are a bunch of things I like about the mattress and a bunch of things I didn’t like about it. The cons outweigh the pros for me but not by much; if my circumstances were a little different I might have kept it.

Pros

Sleep generally improved.

I didn’t get the promised +30 minutes of extra sleep but anecdotally it was a positive change.
The mattress could get very hot and cold.

I was worried that the mattress wouldn’t be able to get cold enough but it was able to go really cool.
Tap control on the side works very well.

It was very easy to tap the side of the bed to increase or decrease the temperature (at least for me, the bed is flush to the other wall).
Separate sections of the bed is excellent.

Although our kids slept with us the two sections worked well for us.
It’s a cool gadget—I like gadgets.

Cons

There’s no way to connect it to Home Assistant.

I like home automation and I’ll freely admit that if I could’ve connected the bed to Home Assistant I would’ve kept it, everything else be damned.

Using it as a presence sensor and being able to track the temperature of the bed and create my own automations would be glorious.

But alas, Eight Sleep keeps all the data to themselves and want you to pay for the expensive subscription for the privilege of controlling your own mattress.

Update 2024-10-06

An integration for Home Assistant actually exists. I feel very silly now.

I sleep parts or even whole nights in my kids’ bed.

To benefit from this kind of mattress you need to sleep on it, which I didn’t always do.
The app is a black box.

I was severely disappointed in the app as it doesn’t provide any insight into what the Autopilot is doing, making you question if it does anything at all or if it’s just empty AI marketing.
1. There’s no history of the temperature adjustments during the night.
  
  You can’t look back at the night and see your own or the Autopilot’s temperature adjustments. My own adjustments aren’t even saved so the temperature settings for the next night is a guessing game.
  
  Eight Sleep claims that Autopilot is making adjustments but for all I know it’s not doing anything.
2. The “Autopilot has reduced your X by Y%” messages feels made up.
  
  I didn’t have the Pod 4 Ultra that can elevate the bed, so how can the Autopilot reduce my snoring during the night? Sometimes I didn’t sleep the whole night in the bed yet Autopilot claims it improved my deep sleep with 20%?
  
  I’ll give them the benefit of the doubt and say it’s probably bad statistics rather than regular old bullshit… But how can you tell?
Most importantly it did not achieve the partner approval.

Using the free 30 day return

I gave it a shot but after a few weeks I decided to use the generous free 30 day return to send back the pod and get a refund (you throw away the mattress).

It wasn’t the smoothest ride but the customer service did a decent enough job. I had lots of trouble with the pickup, although that was probably an issue with the shipping company rather than Eight Sleep:

At first, they didn’t show up.
The next time I didn’t get a label I could print, so they couldn’t take the package.
Then they again didn’t show up.
Finally, we tried another shipping company and Eight Sleep sent the label to me directly, then they picked it up.

I work from home so it wasn’t that big of a deal, although it was a bit stressful.

Still, the free return is great and it might be the biggest reason to try Eight Sleep. In the future, when the kids get older and if someone reverse engineers the next generation of the Pod to connect it to Home Assistant, I might give it a try again.

Why I still blog after 15 years

2025-05-02T13:37:35+00:00

Time flies when you’re having fun.

Before you know it, your little babies have started school, you celebrate the 30th anniversary of Jurassic Park, and that little blog you started have now been going for 15 years.

15 years is a long time; longer than I’ve been waiting for Winds of Winter, and that wait has felt like an eternity. How did I—who frequently abandon projects for the next shiny thing—manage to continue this blog for so long?

I’m as surprised as anyone but I’ve tried to make a retrospective of how this may have happened.

Why I started the blog

I started this blog because I wanted to create a bunch of fast game prototypes and I wanted somewhere I could write about my plans and, ultimately, the games.

You see, I was a budding programmer and I wanted to learn how to program by making a game. Not a simple game like Tetris—that would be way too sensible—no, I wanted to make a big RTS game, like StarCraft or Supreme Commander. And to do that you needed a game engine.

So I got stuck developing my engine with truly groundbreaking features such as:

A menu with keyboard and mouse support.
A console you could bring up with F2 where you could update variables (such as unit speed) without having to recompile.
You could select units with proper Ctrl, Shift, and right click behavior.

… But, embarrassingly, I didn’t have anything even resembling a game, and with the development speed I had I doubt I’d be finished to this day.

I’d gotten stuck in the Game Engine Trap, and I hated it.

Then I found The Experimental Gameplay Project (of World of Goo fame) that promoted the idea that you should be able to create a game prototype in just 7 days. That sounded like the perfect cure against the Game Engine Trap, so I created this blog to document my progress.

Why I’ve continued to blog

While the blog fulfilled it’s initial purpose as I developed around a dozen game prototypes that got me out of the Game Engine Trap (and that gave me a small “game engine” library at the end), I soon started write about other things.

There are a number of reasons I continued to blog:

I enjoy writing.

I realize now that the biggest reason I blog is that I enjoy the writing process. I can’t put my finger on why, I just generally like it.

This isn’t always true though and I’ve had years where I’ve barely written anything at all (2022 for example). Sometimes I’ve had to force myself to write something.

I guess the motivation ebbs and flows sometimes.
Writing helps me think more clearly and helps me flesh out ideas.

The act of writing something down helps me find errors in my thinking and helps me consider different viewpoints. Rewriting the text you’ve written has a similar benefit to refactoring your code; your thoughts will be more polished afterwards.
Publishing something forces me to do better.

If I’m going to put something out there I’m going to re-read and rework my text/code/ideas more than if I had kept it for myself. (Even if nobody will read your posts, the mere act of putting something out there has this effect I think.)

For example, my custom keyboard layout wouldn’t have been nearly as well-developed if I hadn’t published it for everyone to see.

Being more thoughtful about how I write is something I’ve become more cognizant of as the years have gone by. My first posts where little more than a stream of thoughts, while the larger posts I gravitate towards today have gone through multiple revisions and rewrites before I publish them.

At any time I have several drafts that I’m writing on, but many of them never gets published. Sometimes I lose interest, and other times I see that the post won’t become the polished masterpiece (or at least, not a pile of dung), so I abandon it.
The blog is a place to document my personal projects.

Over the years I’ve done other projects, such as built a 3D printer and wrote a book. It’s nice to have a place where I can write about them.
Looking at a log of things I’ve done makes me feel better.

I’ve been doing a small yearly review every year where I try to list the highlights of the past year. It’s been super helpful for me as it helps counteract the depressing feeling that nothing has happened and that I haven’t done anything.

Doing a yearly review of some sort is a practice I highly recommend everyone to try, and of course you don’t have to publish it for everyone to see.
I enjoy developing the blog as a project that exclusively solves my problems.

Programming is my biggest hobby and I can’t see myself ever stopping. The blog is a great project as it’s something that exists only for me so I can rewrite, refactor, and add whatever silly features I want and I only have myself to answer to. It’s a nice feeling.
Blogging helps me become a better writer, which in turns helps me become a better developer.

I think communicating well is an important and underrated part of being an effective software developer. Writing well is a skill that can be developed by practice, and maintaining a blog is a pretty good way to practice I’d say.

No, dumping a stream of thought into ChatGPT isn’t good enough.

My motivations aren’t dependent on external feedback

It’s important to point out that it’s not external feedback that has kept me going all these years. Yes, of course, it’s nice to get the occasional email with compliments, but that’s just a bonus.

I keep this blog for me to write, not necessarily for others to read.

Many of these kinds of retrospectives contain graphs of views over time or the most popular posts; but I’m not showing it to you because I can’t—I don’t keep any statistics whatsoever.

I don’t really care—and I don’t want to care—about how many readers I have or what posts are and aren’t popular. I worry that if I add statistics to the blog it’ll change from an activity I perform for the activity’s sake, to an exercise in hunting clicks where I write for others instead of for myself.

If I were chasing views I would certainly not have continued to blog for as long as I have, and I’d have missed out on the many benefits I’ve gotten from the blog.

Evolution of the tech stack

One of the reasons I’ve been blogging so long is that I’ve been able to play around with the tech stack of the blog. I’ve changed the tech stack a number of times; from choosing languages I wanted to learn, to a boring setup that “just works”, and back again.

~ 2008

I started out with PHP using the Kohana Framework and I still have fond memories of their excellent documentation. Although I had figured out how to create a website, it never graduated to a real blog.

Early 2009

Then I moved on to rewrite the site in Perl using Mojolicious. I’m not sure my efforts ever resulted in anything tangible but I remember if was fun to play around with.

July 2009

I stumbled upon the idea of using a static site for my blog and therefore abandoned Perl for Jekyll, a popular static site generator at that time.

I believe it was a smart choice because it helped me start writing, instead of jerking around with cool tech.

~ July 2013

Eventually, I grew tired of the boring backend that just got the job done and in my quest to learn Haskell I replaced the generator with Hakyll, another static site generator with a pretty neat DSL.

July 2013

The earliest Git commit on record. I’m fairly sure I used Git before this point
(I abandoned SVN for my games in 2009).

2013–2022

Sadly, I never truly graduated from the “throw shit at the wall until it sticks” stage of my Haskell journey, which is why I barely added any features to the blog for many years.

August 2022

Having outgrown existing solutions I decided to join the Rewrite in Rust club (or is it a cult?)

Religious weirdness aside, having complete control of the site generator made it fun again to tinker and add small features.

2022–2024

Honestly though, my favorite piece of technology on the blog is CSS. I just really like to spend time to fiddle with the design and to make small tweaks here and there. I do use Sass but 95% is just plain CSS.

Modern CSS is honestly great.

February 2024

Almost by accident I started using Djot instead of Markdown to write my posts. I couldn’t find a Tree-sitter grammar for Djot so I created one.

May 2024

I’m in the process of connecting the site generator to Neovim to provide autocomplete, diagnostics, jumping between posts, and other cool features.

There’s lots of potential for spending tons of time in this swamp but these IDE-like features really elevate the writing experience.

At the moment the blogging software is a whole project in and of itself (by design; it’s a fun project to tinker with).

Posts have changed focus and increased in scope

:post-stats-graph:

It probably comes as no surprise that my posts have changed a lot since I started the blog. I made the above visualization that counts the words of each post and plots them on a time axis, together with loose grouping of the type of post.

I have two main takeaways:

The posts have grown larger and more ambitious.

In the beginning I treated the blog almost like a Twitter/X feed with short updates on my game making progress. Now I spend weeks or even months slowly working away on a post until I feel it’s interesting and polished enough to publish.
As my interests have changed, so has the focus of my posts.

I only write about my hobbies or things that I’m interested in at that moment so it’s only natural that the theme of the posts have changed. Gaming related posts have given way for more programming and the occasional meat-space related project.

What does the future bring?

I find almost find it obvious that the blog has changed so much during the 15 years of it’s existence; of course my posts would grow more ambitious as my writing matured and I’d obviously start gravitating away from games towards other projects.

Naturally, it’s just a lie I tell myself with the benefit of hindsight.

Predicting the future is impossible and I have no idea what the blog will look like 15 years from now. While it feels like I’ll keep blogging the same way, it would be foolish to claim that as a fact.

Sometimes it’s best to stop worrying and just enjoy the ride.

A simple timeline using CSS flexbox

2025-01-19T07:16:57+00:00

As I added a /now page to the site I also decided to refresh my /about page and I figured it would be neat to have timeline element where I could list some of the larger events in my life.

To my surprise it wasn’t too difficult to create one that looks pretty clean—the flexbox feature in CSS is really good. In this post I’ll walk you through how I made this kind of timeline:

1989

I was born in the north of Sweden

2006

I got introduced to Visual Basic

August 2008

Got together with Veronica

Markup

I like to start with the markup before moving on to styling. I have two wrappers (timeline and events) around the different events (event) that contains the event marker (svg) and content with a time and text:

<div class="timeline">
  <div class="events">
    <!-- The first `1989` event -->
    <div class="event life">
      <!-- The circle is an svg -->
      <svg
        class="marker"
        xmlns="http://www.w3.org/2000/svg"
        width="12"
        height="12"
      >
        <circle cx="6" cy="6" r="6"></circle>
      </svg>
      <!-- The event info -->
      <div class="content">
        <time>1989</time>
        <div class="text">
          <p>I was born in the north of Sweden</p>
        </div>
      </div>
    </div>

    <!-- etc ... -->
  </div>
</div>

A simple line

Let’s start with the actual line in the timeline. I chose to use the ::before pseudo-element on the events div to simulate a line by setting the width and height:

.events::before {
   // We need some content for the element to show up.
   content: "";
   // Use absolute positioning to place the timeline at the very top.
   position: absolute;
   top: 0;
   // With a height and with the timeline will be a tall and thin box.
   height: 100%;
   width: 1px;

We also need to set the wrapper .events to use relative positioning, otherwise the timeline will start from the top of the page, not the container:

.events {
  position: relative;
}

I’ll also throw in a little bit of styling so it’s easier to see:

// For the tutorial I use slightly different colors,
// but you get the idea.
.events::before { background: white; }
// Events use different classes to differentiate them.
.event.life .marker { fill: yellow; }
.event.programming .marker { fill: magenta; }
.event.family .marker { fill: red; }
// Make the time stand out
.content time {
  font-family: concourse_4, Helvetica, sans-serif;
  font-weight: bold;
}
// Just some extra spacing to make the timeline not merge
// with the surrounding text.
.events { margin: 0.5em; }

And we have our line for our timeline:

1989

I was born in the north of Sweden

2006

I got introduced to Visual Basic

August 2008

Got together with Veronica

Alignment

The circle and event aren’t aligned, let’s try to fix that.

By using flexbox the event will display its content horizontally (with the circle to the left and the content to the right):

.event {
   display: flex;
}

1989

I was born in the north of Sweden

2006

I got introduced to Visual Basic

August 2008

Got together with Veronica

Close, but the circle seems off. Remember that the circle is an svg 12 pixels wide and high and positioning will use 0,0 by default.

With relative positioning we can move the center of the circle to align it better:

.event .marker {
   position: relative;
   left: -6px;
   top: 6px;
}

1989

I was born in the north of Sweden

2006

I got introduced to Visual Basic

August 2008

Got together with Veronica

But if you look closely this still doesn’t look correct. Turns out that centering things is the hardest problem in computer science, so don’t be discouraged.

To save you some grief, I found that align-items: baseline does a better job than nudging top positioning:

.event .marker {
  position: relative;
  left: -6px;
  top: 0px;
}
.event {
  align-items: baseline;
}

1989

I was born in the north of Sweden

2006

I got introduced to Visual Basic

August 2008

Got together with Veronica

(The alignment looks good enough to me, at least with the default font I use.)

Vertical spacing

It feels a bit cramped so lets space things out. One way is to simply add a margin-bottom: 1em; but that would add a useless space below the last event (that we’d have to remove another way).

I think a cleaner way is to use flexbox and row-gap to only specify spacing between elements:

.timeline-5 {
  .events {
    display: flex;
    // Lay out events column-wise instead of row-wise.
    flex-direction: column;
    // Set some spacing between elements.
    row-gap: 1em;
  }
}

1989

I was born in the north of Sweden

2006

I got introduced to Visual Basic

August 2008

Got together with Veronica

Making it responsive

What we’ve made is good for smaller screens but for larger screens I’d like to place the line in the middle and move some events to the left and some to the right.

I’ll use media queries to create a cutoff:

@media (min-width: 700px) {
  // Styling for wider screens goes here.
}

Even though I won’t include the media query in the following code snippets the media query should wrap them all.

Events to the left

The first thing I’d like to do is move the line to the middle:

.events::before {
  // This centers the line horizontally.
  // Remember that we used absolute positioning before.
  left: 50%;
}

1989

I was born in the north of Sweden

2006

I got introduced to Visual Basic

August 2008

Got together with Veronica

(Use a wider screen to see the effects of our changes.)

Now, let’s move the marker to the timeline. First lets move the marker to be after the content in the layout ordering:

.event .marker {
  order: 1;
}

1989

I was born in the north of Sweden

2006

I got introduced to Visual Basic

August 2008

Got together with Veronica

Secondly, we’ll make the content take up all the space to the left, pushing the marker on top of the line in the middle:

.event .content {
  width: 50%;
}

1989

I was born in the north of Sweden

2006

I got introduced to Visual Basic

August 2008

Got together with Veronica

Lets move right-align the content and add some padding so the text won’t overlap with the marker:

.event .content {
  text-align: right;
  padding-inline: 1em;
}

1989

I was born in the north of Sweden

2006

I got introduced to Visual Basic

August 2008

Got together with Veronica

Events to the right

To move events to the right side of the timeline all we have to do is tell flexbox to lay out elements from right to left instead of left to right:

// Use `nth-child(even)` to target every other event.
.event:nth-child(even) {
  // Layout elements from right to left.
  flex-direction: row-reverse;
}

To make it look good lets add left aligned text and move the marker offset to be aligned over the line again:

.event:nth-child(even) {
  .content { text-align: left; }
  // The marker used to be offset -6px, but now we
  // move from the right.
  .marker { left: 6px; }
}

1989

I was born in the north of Sweden

2006

I got introduced to Visual Basic

August 2008

Got together with Veronica

We’re done

That’s all there is to the timeline I use. You can of course modify and expand on it in many ways but I quite like this simple styling.

With flexbox it was in the end fairly simple to get a basic timeline created and it’s one of my absolute favorite CSS features that manages to simplify many things that used to be very awkward.

Here’s the all the styling for the timeline we created in this post:

// The line in the middle.
.events::before {
  content: "";
  position: absolute;
  top: 0;
  height: 100%;
  width: 1px;
  background: var(--color-hr);
}

.events {
  // Needed for positioning the line.
  position: relative;
  // Add some space.
  display: flex;
  margin-block: 0.5em;
  flex-direction: column;
  row-gap: 1em;
}

.event {
  // Layout content and marker using flexbox.
  display: flex;
  // Align marker vertically.
  align-items: baseline;
}
.event .marker {
  // Adjust marker to center on the line.
  position: relative;
  left: -6px;
}

// Some coloring to make our life easier.
.event.life .marker {
  fill: var(--melange_b_yellow);
}
.event.programming .marker {
  fill: var(--melange_b_magenta);
}
.event.family .marker {
  fill: var(--melange_b_red);
}
.content time {
  font-family: concourse_4, Helvetica, sans-serif;
  font-weight: bold;
}

@media (min-width: 700px) {
  // Place the line in the middle.
  .events::before {
    left: 50%;
  }
  // Layout the marker after the content.
  .event .marker {
    order: 1;
  }
  .event .content {
    // Make the content take 50% space so the marker
    // will be placed at 50% (on top of the line).
    width: 50%;
    // Event is to the left, align text towards the line.
    text-align: right;
    // Avoid overlap with the marker.
    padding-inline: 1em;
  }
  // For these types, move the event to the right.
  .event:is(.programming, .work, .projects) {
    // Layout the content and marker from right to left.
    flex-direction: row-reverse;

    // Now align text to the left.
    .content {
      text-align: left;
    }
    // We used to offset the marker from the left with -6px,
    // now we need to do it from the other side.
    .marker {
      left: 6px;
    }
  }
}

Microfeatures in my blog

2026-04-27T10:16:47+00:00

xkcd: Nerd sniping

A while I ago I encountered a blog post called Microfeatures I Love in Blogs and Personal Websites, and together with the related Hacker News discussion I got nerd sniped. (I spent more time than I care to admit implementing new and exciting microfeatures for the blog.)

Microfeatures are fun and time consuming

For some people, blogging is their job. For me, blogging is a way to delve deeper into ideas, to document my journey to future me, to relax, or have fun. Microfeatures are fun and so they’re a perfect fit for my blog.

I also really appreciate microfeatures in other blogs. It’s nice to discover a beautiful table of content or a page with favorite blog posts. It makes me want to stick around longer and appreciate the craft that is blogging.

But realize that microfeatures take time to implement. One small feature won’t make a big difference but dozens of microfeatures might transform your blog rewrite you thought were going to take a weekend, to a project spanning weeks or even months.

Microfeatures I’ve implemented

Here’s a collection of notable microfeatures I’ve implemented for the blog. It’s not an exhaustive list, just the ones I think are fun, interesting, or that I’d like to see in more blogs.

Published and revision info

There’s a trend for blog posts to not include the date the post was published—and I hate it, especially for technical content. I don’t even like to call the date of publishing a “micro” feature as it’s more an essential feature.

Regardless, I include the published date below the post title in my blog:

The published date together with the Git commit.

I also think it’s valuable to display the date the post was updated:

The date of the last revision together with the corresponding Git commit.

I guess it would be more precise to manually specify when the post was updated, to avoid changes like Enclose titles in “, now an error after Hakyll update where the post content isn’t changed in a meaningful way. It’s too bothersome to remember though so I rely on the Git history and have a list of commits I ignore when I fetch the dates. Not perfect but good enough I think.

Quote attribution

The only true wisdom is in knowing you know nothing.

Socrates

Blockquotes are standard everywhere but you often want to show where the quote originates from.

I think it’s nicer to have specific styling for attributes than to solve it manually, like this:

The only true wisdom is in knowing you know nothing.
— Socrates

Different kinds of notes

I’m a fan of sidenotes and I used them heavily in the book I wrote. They’re great for a certain style of content but for the blog I noticed I used them very rarely. Instead I use “notes” of different kinds to highlight certain things:

Maybe a weird thing to prioritize in a post but I really like the additional color splash the notes can give to a post.

I also have footnotes¹ (mostly because Djot provides them by default) but I never really use them. I guess I should use footnotes more now that I have them.

Enhanced code snippets

pub enum Code<'a> {
    Inline {
        code: &'a str,
        lang: Option<&'a str>,
    },
    Block {
        code: &'a str,
        lang: Option<&'a str>,
        path: Option<&'a str>,
        linenum_start: Option<u32>,
        highlight_lines: Option<RangeSet<u32>>,
    },
}

Embedding code into blogs is common practice and I’ve added a few extra features to the code display on my blog:

Overlay the language or file path.

For code blocks there’s a small description that displays the language. It can be customized to for example display the path of the file:

It’s accomplished using CSS with data attributes and ::before, and won’t be visible in the RSS feed.

View the source Luke.
Syntax highlight for inline code elements.

Highlighting code blocks is standard but I wonder, why don’t we also highlight inline code?

It’s something I added to be able to refer back to values like "-NoHU", 0, and require("telescope.builtin").find_files() when explaining what happens inside a code block. A sentence with color is much more pleasing than the colorless "-NoHU", 0, and require("telescope.builtin").find_files() don’t you think?
Ability to highlight lines.
```
code > .line.hl {
  background-color: var(--melange_a_sel);
}
```
Benjamin Tan’s excellent blog post about Jujutsu used highlighted lines to good effect and inspired me to implement them.
Line numbers with offset.
```
code > .line[data-linenum]::before {
  content: attr(data-linenum);
  padding-right: var(--space-2xs);
  color: var(--melange_a_ui);
}
```
Line numbers is another feature I’ve recently implemented that I think is a good idea. Them being optional is important as line numbers adds visual bloat. I’ll probably only use them in very specific scenarios where I really want to call out code at certain lines.

The selector at line 9 targets lines with the linenum data attribute to avoid the padding at line 11 to apply to code blocks without line numbers.

Adding line numbers in ::before has the additional benefit of the line numbers not being included in the selection, so copying the code works as expected.
No images, no JavaScript, and no embedded Gists.

It frustrates me to no end when someone has made the effort to write a good blog post and then use images for their code. Images inevitably fail to render as crisply as regular text and they’re either too small, too blurry, or impossible to read on the phone.

I also really dislike requiring JavaScript just for displaying text or embedding code as GitHub Gists. It’s just text—let’s serve it as text.

I’ve gotten email at work with images of code they expected me to copy. That’s Office Space thriller material and such behavior will earn you enemies for life.

Table of content

I can optionally insert a table of contents by including a :table-of-content: marker in the markup. It uses the <details> element and is collapsed by default. When expanded it looks like this:

Expanded table of content for Let’s create a Tree-sitter grammar.

It’s important for me that the table of content is optional as I have a mix of small and large posts. The table of content is generated from the first two heading levels and it works quite well for my use-case.

Flex and gallery display for images

I sometimes want to display two or more images next to each other. Instead of having images embedded like normal I place two or more images in a <figure> and use flexbox to place them next to each other:

Two boards for a game called Hextraction that I 3D printed.

When I have more images I use CSS grid to create a small gallery:

Pictures of a robot project from my time at the University.

Embedding YouTube thumbnails

https://www.youtube.com/watch?v=eoKDyhxCVm0

The recommended way to embed YouTube videos is to use iframes and it’s something I implemented over a decade ago. It works but it’s not a great solution. Embedding anything from Google is an enabler for their all-encompassing privacy violations and YouTube embeds are bananas heavy.

Instead I embed an image generated from the video (served from my site, not YouTube) and make it a link that takes you to YouTube. I could’ve used JavaScript to convert the placeholder into an embedded video when clicked but I like simplicity and redirecting to YouTube allows third-party players to handle the redirect.

Different list types

I like lists and I have several different types I can use to mix things up a bit.

Here are some ordered list types:

Alpha 1
Alpha 2

Roman 1
Roman 2

Alpha
Beta

And here are some unordered list types:

Bullet

Dash

Plus

Necessary? No.
Fun? I think so.

Unbroken indexes of all posts

Under /archive I have a list of all posts so it’s easy to scroll through and get an overview of what I’ve written about during the 15 years the blog has been active.

Naturally there’s no pagination so you can just scroll through. I only have 279 posts… What’s the point of pagination anyway?

There’s also indexes for tags (see keyboards) and per year (see 2023). The yearly index mostly exists so I have an easy way to see the past years posts when I do my yearly review.

Featured & favorite posts

Highlighting favorite posts is a good idea I got from the Hacker News discussion and one I just had to implement after seeing it. I handle featured and favorite posts in three ways:

I list five featured posts on the homepage:

Featured posts on the homepage.

A featured post isn’t the same as a favorite post, although the featured posts tend to be favorites.
All favorite posts are listed under /favorite.
Each favorite post is accompanied by a star: <span class="favorite"><a href="/favorite">★</a></span>

A post listing from the archives.

Clicking on the star takes you to /favorite.

Series

Tags are fine for grouping slightly related posts but sometimes posts follow a more structured story, which is where series come in.

A good example of a series is the Let’s build a VORON Trident where I document my journey of building my first 3D printer over 12 posts.

There’s a few features that come with a series:

All series, both ongoing and completed, are listed under /series.
Each series gets a separate page with a description and the list of posts.

See /series/voron_trident or /series/t-34.
A post is clearly marked as belonging to a series.

It’s marked next to the post title:

The series is marked both above and below the post title.

And more information about the series is included at the end of the post, so it’s easy to jump around in the series:

All posts in the series are included at the end of a post.
Selected series are showcased on the homepage.

I like series and I want to write more series. The drawback is that they take more effort to create than standalone blog posts. As my attention and motivation tends to shift a lot this increases the risk of stress if I lose motivation in the middle of a series.

Projects

While a blog is about writing I also wanted to highlight some of the personal projects I’ve made.

There are no individual pages for the projects as they typically live outside this site (maybe at Codeberg). Instead I have a /projects page with the projects and I include a subset of those on the homepage.

The projects markup is fairly simple, just a title and a description (that could include an image, code block, or whatever):

The T-34 Keyboard layout project.

Long ago I made some game prototypes and I wanted to showcase them in a slightly different manner. They’re still included as a project but they get specialized markup that I’m pretty happy with:

The games overview in the /projects page.

Automatic dark mode

The light and dark style of the site.

Because I have a preference for dark mode I really wanted a dark mode for the blog, while also catering to people that prefers a light mode.

I implemented dark mode using prefers-color-scheme, a simple solution that doesn’t require JavaScript and “just works”. It’s a CSS feature that allows the user to specify their preference using the browser or operating system.

Microfeatures I may implement in the future

Naturally, there’s always more features you can implement. Many I won’t bother with but there are some that I think are good ideas and that I may implement one day.

Targeted RSS feeds

RSS feeds are awesome and I think all blogs should have them (and news sites, social media sites… almost everything really). I do of course have a feed but it might be a good idea to add specialized feeds such as:

Feed for a series
Feed for a tag

The only reason I don’t have them is laziness.

Search

Because it’s a static site it’s harder to have a good search functionality. Maybe there’s a good way to create/include one but I haven’t looked into it more.

A better 404 page

Perhaps related to the search functionality, it would be nice if the 404 page would include a helpful “did you mean” message.

For example if you typed in the path /use it could suggest you to try /uses instead.

So far I’ve avoided JavaScript in the blog but here it would be nice to have.

Summary of a post

I’ve toyed with the idea of having a summary of each post, so I could have the summary of a featured post on the homepage. However, good summaries are cumbersome to maintain and hard to auto-generate.

I don’t want to summarize manually—it introduces too much friction into blogging. While LLMs are honestly quite good at generating summaries, I think we need less AI generated content on the web, not more. Taking the first N characters or M paragraphs is a shoddy way of summarizing a post and won’t create a useful summary.

While I like the idea of a post summary, it’s not a feature I’ll implement anytime soon.

Changelog

While I display the latest Git commit for each post I was impressed by the list of “meaningful changes” at the bottom of the jj init blog post.

A changelog looks cool but I’m too lazy to maintain one for all posts. A post like The current T-34 keyboard layout would probably benefit from a proper changelog.

Djot has a bunch of nice benefits over markdown such as footnotes.

There are various flavors such as Pandoc flavored markdown that has footnotes, among other things.↩︎

Back to lazy.nvim

2024-06-25T07:38:52+00:00

Around a month ago I had an affair with rocks.nvim. It was fun, but I’m back together with lazy.nvim again. This is a short post to explain why—at this point in time—the grass wasn’t greener on the other side.

Problems with rocks.nvim

Too many weird issues.

I had quite a few weird bugs that I couldn’t pin down. What finally broke the camel’s back was that I couldn’t run neotest with Elixir. I think the problem was that I didn’t have the correct treesitter grammar but no matter how I tried to :Rocks sync, :Rocks update, :TSInstall, or nuke the nvim folders in ~/.local and do a complete reinstall, I couldn’t get it to work.

I don’t want to mess with my Neovim configuration when I’ve got work to do. With lazy.nvim these issues went away.
Update and sync was really slow.

:Rocks update and :Rocks sync is painfully slow compared to lazy.nvim. I was already frustrated with packages breaking and having to wait for the :Rocks sync to finish when I trying to fix them made me want to smash the computer to pieces.

That there’s no way to update or sync an individual package was just gravy.

Update

I’m told that :Rocks install {rock} updates an installed package.

Lazy.nvim 11.0 supports luarocks and rockspec

The single reason I started looking into rocks.nvim was support for luarocks where plugins can specify their own dependencies so that I don’t have to. With 11.0 lazy.nvim added support for luarocks including the ability to specify any luarocks dependency (such as a toml library).

Given that lazy.nvim supports semver versioning and :Lazy restore there are no longer any features I need that rocks.nvim have that lazy.nvim don’t.

I will be faithful, I promise

I really need my configuration to just work and unfortunately that wasn’t the case for me with rocks.nvim. That’s why I’m back to lazy.nvim and I’m really enjoying the fantastic speed of lazy.nvim. Why did I ever leave you?

Migrating to rocks.nvim

2026-04-27T15:24:59+00:00

My relationship with my Neovim config is best described as an On-again, off-again relationship. At times I’m deeply in love and spend all my time caressing the config—like how in September I did a complete rewrite in Lua—while other times I’m busy with other love interests and the config is left alone, sometimes for months or even years.

While not as intense as the September affair, I recently got back together with my config to migrate her from the “old and boring” lazy.nvim package manager to the new and exciting rocks.nvim. It wasn’t all smooth sailing but with some patience—and a drink or two—our threesome with rocks.nvim was quite enjoyable.

Why rocks.nvim?

To be honest, the biggest reason I started looking into rocks.nvim was that my brain—for some weird reason—tends to get stuck thinking of things. Rewriting my config wasn’t something I wanted to do but it’s not easy to escape the brain lock.

Luckily, this time my brain locked onto something a worthwhile as rocks.nvim has some nice and ambitious features.

Benefits over other package managers

rocks.nvim makes dependency management the responsibility of the plugin.

With other package managers you as a user have to specify the dependencies for the plugin. Using lazy.nvim it might look like this:
```
return {
  "NeogitOrg/neogit",
   dependencies = {
     "nvim-lua/plenary.nvim",
     "nvim-telescope/telescope.nvim",
     "sindrets/diffview.nvim",
   },
   opts = opts,
}
```
There are several issues with this:
1. It’s annoying.
2. You need to babysit the config if the plugin adds or removes a dependency.
3. The plugin might break if there’s a breaking change in a dependency.
4. What if you have several plugins that depend on a different version of a dependency? (You’re going to have a bad time.)
rocks.nvim moves the dependency management to the plugin, so we can just specify the plugin itself:
```
"neo-tree.nvim" = "3.26"
```
This makes plugin management easier and should reduce the risk of plugins breaking.
rocks.nvim supports loading Lua packages from luarocks.

Lua is a neat little language but it’s very bare-bones and doesn’t include a large standard library. Neovim has been incorporating more and more utility functions—such as vim.split and vim.fs.joinpath()—but there are still plenty of functionality that we need to import. That’s why utility plugins such as plenary.nvim exists and is a dependency to a lot of different plugins.

With luarocks you get access to many more libraries; for example a yaml and a toml library that would’ve saved me from parsing them with regex.

Drawbacks compared to lazy.nvim

Naturally, it’s not all fun and games and there are drawbacks to rocks.nvim compared to lazy.nvim:

Most plugins don’t have a rockspec that define their dependencies, meaning you still need to manage the dependencies yourself, forgoing the biggest benefit of rocks.nvim.
Installing and updating all packages feels a lot slower.
You must manage lazy loading manually. I’ve seen rumors of lazy loading support for rocks.nvim but as I’m writing this post there’s nothing released yet.
rocks.nvim is newer than lazy.nvim; meaning less fancy features, more bugs, and more rough edges.

While I think that rocks.nvim is taking a necessary and difficult step forward for Neovim package managers, there are valid reasons to stick with lazy.nvim.

Basic setup

You can install rocks.nvim by manually sourcing an installer script but I wanted rocks.nvim to install itself automatically. It’s possible by dropping the bootstrap script into your init.lua file.

Then you’re good to go with managing plugins with the :Rocks commands:

:Rocks install {rock} to install a package.
:Rocks sync to sync packages with rocks.toml.
:Rocks update to update packages and their versions in rocks.toml.
:Rocks prune {rock} to uninstall a package.

I was a bit surprised that you can’t update or sync an individual package but otherwise the commands feel intuitive.

Separate config file per plugin

One feature I really like about lazy.nvim is the ability to separate plugin configuration into separate files. This is easy to setup in rocks.nvim using rocks-config.nvim:

Run :Rocks install rocks-config.nvim or edit rocks.toml manually:
```
[plugins]
"rocks-config.nvim" = "1.6.0"
```
Create a plugin-specific file at lua/plugins/<plugin-name>.lua with the plugin setup and configuration code.

For example, we can install conform.nvim with :Rocks install conform.nvim and configure it in lua/plugins/conform.lua:
```
require("conform").setup({
  formatters_by_ft = {
    lua = { "stylua" }
  }
})
```
There are some rules on what to name the config file:
- The plugin’s name (as long as it is a valid module name).
- The plugin’s name with the .[n]vim suffix removed.
- The plugin’s name with the [n]vim- prefix removed.
- The plugin’s name with - substituted for ..
For conform.nvim we could name the config file conform-nvim.lua or simply conform.lua.

Something to keep in mind when migrating to a setup with a config file per plugin is a potential ordering issue. I for example use mason-lspconfig.nvim for my LSP setup and it’s important to call the setup in the right order:

If the plugins have their own config file then we can’t guarantee this order. We can instead setup them all in one of the config files—although I’m not a fan of commingling setup of different plugins in a single file in lua/plugins, I prefer them to have a 1-to-1 relationship with a plugin. I think it’s cleaner to place such a file in a runtimepath such as plugin/lspconfig.lua.

Git dependencies

Another crucial feature is the ability to install plugins from git repositories. This requires the rocks-git.nvim module that’s installed with :Rocks install rocks-git.nvim:

[plugins]
"rocks-git.nvim" = "1.5.1"

You can then add git dependencies using :Rocks install <git-path> or add them to rocks.toml manually:

[plugins]
"vim-fugitive" = { git = "tpope/vim-fugitive" }
"trouble.nvim" = { git = "folke/trouble.nvim", branch = "dev" }
"nvim-ts-autotag" = { git = "windwp/nvim-ts-autotag", rev = "aeb7090" }

As I’m writing this almost exactly half of my plugins in rocks.toml depends on a git repository instead of luarocks. Mostly because they don’t exist on luarocks but I also have some Vimscript plugins that never will be.

One feature I’m missing is a command to automatically update rev to the latest available value or removing it, now I did it manually.

How to build a plugin?

There are some plugins that needs to be built before we can use them in Neovim. telescope-fzf-native is such an example where we need to run make after we clone the repository. If this plugin was on luarocks this would be managed seamlessly by rocks.nvim but since the dependency is a git repository we need to build it ourselves.

I spent some time wondering how I should solve this but turns out it’s as simple as adding a build option to the plugin:

"telescope-fzf-native.nvim" = { git = "nvim-telescope/telescope-fzf-native.nvim", build = "make" }

Before I discovered the build option I called make the hard way:

require("nio").run(function()
  local package_path =
    vim.fs.joinpath(
      vim.fn.stdpath("data"),
      "site/pack/rocks/start",
      "telescope-fzf-native.nvim/"
    )

  -- Before loading the extension we need to build it with `make`.
  require("nio").process.run({
    cmd = "make",
    args = {},
    cwd = package_path,
  })
  -- Now we can load the extension.
  require("telescope").load_extension("fzf")
end)

That’s what you get if you skip the manual.

Lazy loading

One big feature that lazy.nvim promotes is lazy loading—it’s even in the name! Unfortunately rocks.nvim doesn’t provide first-class support for lazy loading so we have to manage it ourselves.

The problem with lazy loading

Before looking at how to implement lazy loading, I’d like to bring up a few problems with lazy loading plugins.

It’s easy to half-ass it.

For example, with lazy.nvim you can add commands and events that you want to lazy load on:
```
{
  "nvim-treesitter/nvim-treesitter",
  cmd = { "TSInstall", "TSUpdate" },
  event = { "BufReadPre", "BufNewFile" },
  config = config,
  build = ":TSUpdate",
}
```
But how do you know that you used the correct events and listed the right commands? And how do you keep up to date when a plugin adds or removes commands?

I managed to get really agitated when I thought I’d messed up the treesitter installation when I couldn’t call :TSInstallInfo, until I remembered that I hadn’t registered that command to load nvim-treesitter…

nvim-treesitter defines a lot of commands that we ideally should list when we setup lazy loading.

Extra complexity.

Earlier in this post I complained about having to manage the dependencies for the plugins you install. When you lazy load a plugin you also need to specify commands and events you want to use for lazy load.

And if you really want to commit to lazy loading as many plugins as possible (I did!) you might end up with some pretty horrendous code, like how you’d lazy load oil.nvim:

{
  "stevearc/oil.nvim",
  dependencies = { "nvim-tree/nvim-web-devicons" },
  opts = opts,
  command = "Oil",
  -- This is how to lazy load oil according to:
  -- https://github.com/folke/lazy.nvim/issues/533
  init = function()
    if vim.fn.argc() == 1 then
      local stat = vim.loop.fs_stat(vim.fn.argv(0))
      if stat and stat.type == "directory" then
        require("lazy").load({ plugins = { "oil.nvim" } })
      end
    end
    if not require("lazy.core.config").plugins["oil.nvim"]._.loaded then
      vim.api.nvim_create_autocmd("BufNew", {
        callback = function()
          if vim.fn.isdirectory(vim.fn.expand("<afile>")) == 1 then
            require("lazy").load({ plugins = { "oil.nvim" } })
            -- Once oil is loaded, we can delete this autocmd
            return true
          end
        end,
      })
    end
  end,
}

In general I think properly lazy loading should be the responsibility of the plugin, not us as users.

With that said, being able to lazy load plugins is a great feature when you need it.

Lazy setup with packadd and setup

On a basic level you can accomplish lazy loading by following these three steps:

Mark the plugin with opt = true.
```
[plugins]
neorg = { version = "1.0.0", opt = true }
```
This will prevent rocks.nvim from sourcing the plugin at startup.
Add the plugin with packadd.
```
vim.cmd("packadd neorg")
```
Setup and configure the plugin as needed.

Steps 2 and 3 should be done on-demand, for example via an autocommand:

vim.api.nvim_create_autocmd({ "BufReadPre", "BufNewFile" }, {
  pattern = "*.norg",
  callback = function()
    vim.cmd("packadd neorg")
    require("neorg").setup()
    return true
  end,
})

Although packadd is neat, according to rocks.nvim it’s only relevant for the plugin’s ftdetect and plugin scripts. I haven’t seen the need to go quite this far to get a snappy experience and right now I don’t use packadd at all. I don’t even have 100 plugins yet, I’m practically running stock Neovim!

Lazy LSP setup

There’s one instance where I’ve made the plugin setup lazy: the LSP config.

It’s important to me that Neovim starts quickly as I have a weird workflow where I start Neovim dozens of times a day. But after migrating my config I noticed that Neovim was feeling slow. I tracked it down to the LSP setup (and in particular setting up elixir-tools.nvim).

My solution was to create an autocommand that sources the LSP config when reading a file:

vim.api.nvim_create_autocmd({ "BufReadPre", "BufNewFile" }, {
  pattern = "*",
  callback = function()
    require("lazy_plugins.lspconfig")
    return true
  end,
})

local mason_lspconfig = require("mason-lspconfig")

mason_lspconfig.setup({
  -- ...
})

require("elixir").setup({
  -- ...
})

mason_lspconfig.setup_handlers({
  -- ...
})

-- And a bunch of other LSP related setup.

I could of course make it more granular and make more plugins lazy but I haven’t bothered since Neovim now starts under 150 ms, which my brain interprets as instant.

You can get info about Neovim’s startup time by passing the --startuptime argument:

nvim --startuptime log.txt

Here’s a shortened output of log.txt where you can see the overall startup time but also how long loading packages take:

000.000  000.000: --- NVIM STARTING ---
...
028.386  000.119  000.119: require('fzy_native')
028.388  000.201  000.082: require('fzy')
...
130.398  000.255: before starting main loop
131.047  000.649: first screen update
131.049  000.001: --- NVIM STARTED ---

Treesitter

Another feature rocks.nvim promotes is a “just works” tree-sitter setup. Unfortunately, I couldn’t get it to work and I instead rely on the nvim-treesitter git repository.

It’s likely I made some configuration error somewhere but after spending many hours reworking the entire configuration from scratch (on multiple machines) I gave up when I had a working setup.

At first I tried rocks-treesitter.nvim without nvim-treesitter.

Installing grammars using rocks-treesitter.nvim was straightforward and worked well. However, I use a bunch of extra features found in nvim-treesitter and related packages that I need. This nvim-treesitter config activates the features:

require("nvim-treesitter.configs").setup({
  highlight = {
    enable = true,
  },
  matchup = {
    enable = true,
  },
  autotag = {
    enable = true,
  },
  endwise = {
    enable = true,
  },
  indent = {
    enable = true,
  },
  textobjects = {
    move = {
      enable = true,
    },
    swap = {
      enable = true,
    },
    select = {
      enable = true,
    },
  },
})

But I couldn’t figure out how to make these feature work using rocks-treesitter.nvim.

I tried to have both rocks-treesitter.nvim and nvim-treesitter installed.

That only lead to the dreaded invalid node type error (meaning there’s a mismatch between the grammar and the query files). Which kind-of makes sense as nvim-treesitter provides query files for all grammars but there’s no guarantee that rocks-treesitter.nvim installs the correct grammar for those query files.

I tried to use the nvim-treesitter from luarocks without rocks-treesitter.nvim.

Yet once again the Rust tree-sitter grammar hit the invalid node type error. I also couldn’t install all the grammars as a lot of them failed during installation:

nvim-treesitter[bass]: Failed to execute the following command:
{
  cmd = "mv",
  opts = {
    args = { "-f", "tree-sitter-bass-tmp/tree-sitter-bass-master", "tree-sitter-bass" },
    cwd = "/home/tree/.local/share/nvim",
    stdio = {
      [2] = ,
      [3] = 
    }
  }
}
mv: cannot stat 'tree-sitter-bass-tmp/tree-sitter-bass-master': No such file or directory

Weird.

Fallback to the git repository for nvim-treesitter and friends.

It’s surprising, because I’d assume the luarocks dev version would be the same as the GitHub source, yet this worked for me:

nvim-treesitter = { git = "nvim-treesitter/nvim-treesitter", rev = "1eabe69" }
nvim-treesitter-endwise = { git = "RRethy/nvim-treesitter-endwise", rev = "8b34305" }
nvim-ts-context-commentstring = { git = "JoosepAlviste/nvim-ts-context-commentstring", rev = "0bdccb9" }
nvim-treesitter-context = { git = "nvim-treesitter/nvim-treesitter-context", rev = "55e2908" }
nvim-ts-autotag = { git = "windwp/nvim-ts-autotag", rev = "aeb7090" }
nvim-treesitter-textobjects = { git = "nvim-treesitter/nvim-treesitter-textobjects", rev = "5f9bf4b" }

I pin them to a revision because I got tired of things breaking.

While I can now install all grammars that nvim-treesitter provides and use all treesitter features I used before, I’m annoyed that I couldn’t make it work using rocks-treesitter.nvim. I’m sure there’s something obvious I’m missing but I don’t have the energy to retrace the steps again right now. I’ll instead document my failings publicly on the blog and move on with my life.

Other resolved issues

While migrating I ran into some other minor issues that I managed to resolve:

Some plugins in luarocks are outdated.

For example, the last update to the luarocks gitsigns.nvim was made 2 years ago, while the gitsigns.nvim on GitHub was updated this week.
Got some weird errors I couldn’t debug.

For example, help for rocks.nvim wasn’t available. A clean reinstall by removing the folders ~/.local/share/nvim/ and ~/.cache/nvim/ seems to have resolved the help installation and some other weird errors.
:Rocks sync didn’t respect the provided git branch.

There was a PR that resolved this issue while I was migrating. It does sound suspiciously similar to the issue with the tree-sitter grammars failing to install but I haven’t explored that further.

Should you use rocks.nvim?

I had issues while migrating my config over to rocks.nvim, with rough edges and missing features. For instance, I miss the install speed of lazy.nvim and lazy.nvim’s excellent dashboard.

Yet I’ll stay with rocks.nvim as it deserves props for tackling the huge task of cleaning up dependency management in Neovim and for giving us access to the broader Lua landscape with luarocks.

It may be too bleeding edge for some people; but I think more Neovim users and plugin authors should take note of rocks.nvim and give it a try. I’d like it if a more sane approach to package management become more popular in the Neovim community.

Autocomplete with nvim-cmp

2026-04-27T10:59:37+00:00

Autocomplete tags in the frontmatter.

Autocompletion is an absurdly powerful feature that I—and I must assume most programmers—use all the time. It’s not as crucial for writing blog posts as when you’re coding but it’s still easy to come up with examples of how autocomplete would help. For example:

Complete frontmatter metadata
```
tags = ["Lua", "Neovim"]
series = "extending_neovim_for_my_blog"
```
It’s pretty hard to remember all the tags I have on the blog.
Links to posts

You know, typing out /blog/2024/02/17/how_i_did_the_layout_for_my_self-published_book correctly from memory is pretty much impossible. Instead I opened the post in the browser, copied the url, removed the host prefix, and then pasted it… Which is incredibly slow and annoying.
Image links

I often copy an image to the site’s image folder and when I want to insert a link to the image I’ve forgotten the file name.
Reference link definitions

In Djot (and Markdown) I prefer reference link definitions for my links:
```
Here's [a link][uses]

[uses]: /uses
```
It would be pretty nice to autocomplete the [uses] reference, like some Markdown LSP servers do. Or maybe the reverse; if I’ve written [a link][uses] already but haven’t created the reference link definition for it, we could autocomplete that.

nvim-cmp is my plugin of choice for autocompletion that supports different sources such as LSP, snippets, spell corrections, math calculations, and more. Let’s see how to make our own source for nvim-cmp.

I’ve probably made some mistakes in this post or forgotten something. Check my Neovim config if you see something fishy.

A basic completion source

Creating a custom source for nvim-cmp was described well in :help cmp-develop. This is a minimal source that allows you to complete path-like items:

local source = {}

function source:complete(params, callback)
  local items = {}

  -- There's also the `cursor_after_line`, `cursor_line`, and a `cursor` fields on `context`.
  local cursor_before_line = params.context.cursor_before_line

  -- Only complete if there's a `/` anywhere before the cursor.
  if cursor_before_line:sub(1, 1) == "/" then
    items = {
      { label = "/one" },
      { label = "/two" },
    }
  end

  -- `callback` should always be called.
  callback(items)
end

-- Trigger completion (i.e. open up cmp) on these characters.
-- We can also trigger it manually, see `:help cmp.mapping.complete`.
function source:get_trigger_characters()
  return { "/" }
end

-- Don't forget to register your new source to cmp.
require("cmp").register_source("blog", source)

You also need to register the source when you setup cmp:

require("cmp").setup({
  sources = {
    {
      name = "blog",
      -- `group_index` groups several sources,
      -- and if any completion item for that index is found
      -- all sources with a lower index will be ignored.
      group_index = 1,
    },
  }
}

Assuming you’ve got nvim-cmp setup correctly, our completion should show up:

I used lspkind.nvim to display the [BLOG] label and type information.

You configure it like so:

require("cmp").setup({
  formatting = {
    format = require("lspkind").cmp_format({
      mode = "symbol_text",
      menu = {
        blog = "[BLOG]",
      },
    }),
  },
})

Availability

It might be a good idea to implement the is_available function that only activates autocompletion in certain context:

function source:is_available()
  -- Only returns `true` if the buffer is a markup file inside my blog directory.
  return vim.b[0].blog_file
end

vim.b[0].blog_file is set by Buf autocommand from the initial setup:

autocmd({ "BufRead", "BufNewFile" }, {
  pattern = autocmd_pattern,
  group = blog_group,
  callback = function(opts)
    -- Mark the buffer as a "blog file" buffer
    vim.b[0].blog_file = true
    -- ...
  end,
})

Formatting entries

While nvim-cmp doesn’t seem to give as much control over how to display entries as telescope does it’s possible to customize it a little. In particular I’d like to display the entry’s type and mark that it comes from my blog integration (see the image above).

Completion item kinds

Something that pops up in nvim-cmp’s source code and help is an “item kind”.

A “kind” simply describes what type a completion item is. nvim-cmp follows the LSP specification that includes kinds such as Class, Constant, and the default Text.

Here’s how to specify a kind other than Text for an item:

items = {
  {
    label = "/one",
    kind = require("cmp.types.lsp").CompletionItemKind.File,
  },
}

Kinds aren’t anything revolutionary but I think it helps separate different completion types from each other in certain circumstances.

Displaying different kinds with lspkind.nvim.

The problem is that LSP kinds are focused on code and doesn’t support the kinds I’d like—such as Post, Draft, and Standalone. To display our own custom types we need to do a little more work.

Custom format

Instead of relying on lspkind.nvim let’s use our own format function:

cmp.setup({
  formatting = {
    format = function(entry, vim_item)
      -- TODO customize `vim_item` before returning it
      return vim_item
    end
  },

I like lspkind.nvim and I want to use it for everything other than the blog, let’s make it the default:

local function make_format()
  local lspkind_format = require("lspkind").cmp_format({
    mode = "symbol_text",
    ellipsis_char = "…",
    menu = {
      spell = "[SPELL]",
      async_path = "[PATH]",
      -- Other sources here...
    },
  })

  return function(entry, vim_item)
    if entry.source.name == "blog" then
      return blog_format(entry, vim_item)
    else
      -- Use `lspkind` formatting as a fallback.
      return lspkind_format(entry, vim_item)
    end
  end
end

-- Remember to update `cmp.setup`:
format = make_format()

For the actual formatting vim_item supports two extra fields that we can customize:

kind holds the type information (the 2nd column).
menu holds the source information (the 3rd column).

blog_format might look like this to add type and source information:

-- The symols are from Nerd Fonts but won't show up
-- in the blog properly.
local blog_types = {
  Post = { symbol = "󱚌" },
  Tag = { symbol = "󰓹" },
  Series = { symbol = "" },
  -- etc
}

local blog_format = function(entry, vim_item)
  local type = entry.completion_item.type
  vim_item.kind = blog_types[type].symbol .. " " .. type
  vim_item.menu = "[BLOG]"
  return vim_item
end

We also need to add the type field to our completion items:

items = {
  { label = "/one", type = "Post" },
}

With this we can display our custom types in the same way as lspkind.nvim does it:

Displaying our own custom types.

Complete hidden text

One cool thing with telescope.nvim was the ability to filter on hidden text. In the post finder we developed we could search for post tags, but only display the post title. We can do the same with nvim-cmp, where we’ll display one thing, filter against something else, and insert a third piece of text.

All we need to do is add some extra fields to the completion items:

items = {
  {
    -- Text to be displayed in the completion menu.
    label = "Rewriting my Neovim config in Lua",
    -- Text to insert.
    insertText = "/blog/2023/10/01/rewriting_my_neovim_config_in_lua/",
    -- Text to filter against, works like `ordinal` for telescope.
    filterText = "/blog/2023/10/01/rewriting_my_neovim_config_in_lua/"
      .. "|"
      .. "Rewriting my Neovim config in Lua",
  },
}

In this example we display the post title, insert the url to the post, and filters against both the title and the path.

It’s not as powerful as telescope.nvim where we could treat its equivalence to filterText as structured data. I don’t think it’s a big deal because with autocomplete you’re more likely to want insertText to match what you’re typing, so a mini-language like we created for telescope isn’t as practical.

The most advanced filterText I use is exactly this example: a combination of the url and the title. Otherwise I don’t use insertText or filterText.

What to complete where?

With source:complete we already have the tools we need to autocomplete whatever we want.

The completion part of the integration is the section I’ve had to tweak the most and it has slowly grown more complex.

It’s actually pretty hard to make an exhaustive autocomplete system. You’d have to have a parser that’s capable of parsing incomplete statements. Maybe something like a Tree-sitter grammar, although the one I created for Djot doesn’t mark broken things so it’s useless for this purpose (it marks a paragraph with a single _ as text instead of broken emphasis for example).

I’ve therefore been relying on regexes on cursor_before_line to select what to complete. You could probably design a more powerful solution but this simple approach has served me well so far.

Completion logic

Here’s one of first versions of source:complete to give you an idea on how you might choose what to complete:

local items = {}

-- Expand images separately because I only ever use it in a -- `![](/url)`
-- context and not mixing with other urls gives a more pleasant experience.
if string.match(cursor_before_line, "!%[%]%([^%)]*$") then
  -- items = ...
end

-- Expand inline links, e.g. `[txt](/`
if string.match(cursor_before_line, "%]%(/[^%)]*$") then
  -- items = ...
end

-- Expanding headings in inline links, e.g. `[txt](#`
if string.match(cursor_before_line, "%]%(#[^%)]*$") then
  -- items = ...
end

-- Expand links in link ref definitions, e.g. `[label]: `
if string.match(cursor_before_line, "^%[.+%]:%s+") then
  -- items = ...
end

-- Expanding links in ref defs, e.g. `[label]: #`
if string.match(cursor_before_line, "^%[.+%]:%s+#") then
  -- items = ...
end

-- Expand url definition tags in `[text][tag]`
if string.match(cursor_before_line, "%[[^%]]+%]%[[^%]]*$") then
  -- items = ...
end

-- Expand url definition tags in `[tag][]`, simplified to after a `[`
-- If at the beginning of the line, we should complete broken link tags to..
if string.match(cursor_before_line, "%[[^%]]*$") then
  -- items = ...
end

-- More cases here...

callback(items)

As the completion logic grew more complex, I moved it out from Neovim to the backend. It was easier to setup completion details for individual items that way, and now I only rely on a single "Complete" message that I pipe directly back to cmp:

function source:complete(params, callback)
  server.call({
    id = "Complete",
    path = vim.fn.expand("%:p"),
  }, function(reply)
    -- Items is a list where items have `label`,
    -- `insertText`, and `filterText`
    -- like we manually coded before.
    callback(reply.completion_items)
  end)

I still rely on the regex based approach though.

I’ll revisit how the backend communication works in a future post.

Anatomy of a regex

Don’t be too scared of the regexes. They’re hard to read if you’re unfamiliar, but not too bad once you use them a bit.

For example, here’s how the regex matches an image url with the text ![](/path:

!           !
%[          [   `%` escapes special characters
%]          ]
%(          (
[           all characters
  ^           not equal to
  %)          )
]*            0 or more times
$           end of string

It’s important to include the end of string, so that we don’t autocomplete images after the image has ended:

![](/img) Trailing path /
                        ^
                        Don't autocomplete image here

The [^%)]* part allows the completion to match further into the path:

![](/im
      ^
      We're not done yet

Item documentation

Completion of a heading references for a url, showing the heading context.

Another feature is the “documentation window” which is an extra window with information about the entry you’re currently selecting. To set it up all we need to do is implement source:resolve and set item.documentation, for example like this:

function source:resolve(item, callback)
  -- We should generate `lines` depending on the item.
  local lines = {
    "`Rewriting my Neovim config in Lua`",
    "2023-10-01",
    "*Neovim*, *Lua*",
    "---",
    -- Post content here
  }

  if lines and #lines > 0 then
    item.documentation = {
      kind = "markdown",
      value = vim.fn.join(lines, "\n") .. "\n",
    }
  end

  callback(item)
end

We could’ve set item.description immediately but source:resolve is preferable as it’s only called when we select the item, making it the better choice if we want to do some heavier operations (such as reading from a file).

Speaking of reading from a file, here’s a function that lets you read a range of lines from a file:

-- Collect the lines into `res` instead of returning it,
-- to make it easier to insert lines before the file content.
local function read_lines(file, start_row, end_row, res)
  local linenum = 1
  for line in io.lines(file) do
    if linenum >= start_row and linenum <= end_row then
      table.insert(res, line)
    end
    linenum = linenum + 1
    if linenum > end_row then
      break
    end
  end
end

It’s used like this to produce a documentation for a heading item from another file (preferring nvim_buf_get_lines for headings in the current buffer):

local function _heading_docs(heading)
  -- If there's a heading path, then the item is pointing to a heading in another file.
  if heading.context.path then
    -- Uses markdown to make the url bold and adds a separator before the heading context.
    local res = {
      "*" .. heading.context.url .. "*",
      "---",
    }
    -- Read the heading and the 10 following lines.
    read_lines(heading.context.path, heading.context.start_row, heading.context.end_row + 10, res)
    return res
  else
    -- If we don't have a heading then heading points to the same file.
    -- We can use the buffer `0` to read lines from the current buffer.
    return vim.api.nvim_buf_get_lines(
      0,
      heading.context.start_row,
      heading.context.end_row + 10,
      false
    )
  end
end

To display post bodies we also need to skip the frontmatter. The frontmatter for my posts are delimited by --- like so:

---toml
title = "My post title"
tags = ["Lua", "Neovim"]
---

Post body here...

We can do this by counting how many --- we see, and only collecting lines after we’ve seen two of them:

-- Collect `limit` lines from `file` into `res`, skipping the post frontmatter.
local function read_post_body(file, limit, res)
  local count = 1
  local frontmatter_delimiters = 0
  for line in io.lines(file) do
    if frontmatter_delimiters == 2 then
      table.insert(res, line)
      count = count + 1
      if count > limit then
        break
      end
    elseif string.match(line, "^%-%-%-") then
      frontmatter_delimiters = frontmatter_delimiters + 1
    end
  end
end

local function _post_docs(post)
  -- I add more things such as tags and series
  -- but I shortened the code for this example.
  local res = {
    "`" .. post.title .. "`",
    "---"
  }

  read_post_body(post.path, 20, res)

  return res
end

Sorting

With nvim-cmp you get full control over the sorting of items. Sorting is done with standard comparison functions (e.g. entry1.modified > entry2.modified) that you can chain. We can add our own comparator to cmp.setup like so:

cmp.setup({
  sorting = {
    comparators = {
      -- With cmp you chain comparators.
      cmp.config.compare.offset,
      cmp.config.compare.exact,
      cmp.config.compare.score,
      cmp.config.compare.recently_used,
      cmp.config.compare.locality,
      -- I added my comparator here.
      blog_compare,
      cmp.config.compare.kind,
      cmp.config.compare.sort_text,
      cmp.config.compare.length,
      cmp.config.compare.order,
    },
  },
})

local function blog_compare(entry1, entry2)
  -- TODO
  return nil
end

The first thing I’d like to do is sort different completion types, similar to cmp.config.compare.kind but for the custom blog types:

local blog_types = {
  BrokenLink = { rank = 0, symbol = "󰌺" },
  LinkDef = { rank = 1, symbol = "󰌹" },
  -- etc
}

local function blog_compare(entry1, entry2)
  -- Only sort blog entries.
  if entry1.source.name ~= "blog" or entry2.source.name ~= "blog" then
    return nil
  end

  local item1 = entry1.completion_item
  local item2 = entry2.completion_item

  local rank1 = blog_types[item1.type].rank
  local rank2 = blog_types[item2.type].rank
  if rank1 < rank2 then
    return true
  elseif rank1 > rank2 then
    return false
  end

  -- The types are the same, `nil` doesn't imply a sort order between them.
  return nil
end

At the end of blog_compare we can add our type specific comparisons. For example, we can sort images by the modified timestamp so that the newest image comes first, making it easy to insert new images:

if item1.type == "Img" then
  -- Sort images by modification time.
  return item1.modified > item2.modified
elseif ... then
  -- More type specific sorting cases here
else
  return nil
end

Wrap-up

With this we’ve created our own completion source for nvim-cmp. We’ve tweaked the display, separated the insert and filter text, added item documentation, and customized the sorting. The completion has been extremely helpful for me and I’ll end this post with a gallery of the completion in action:

Check out my Neovim config and the site source for more details.

Browse posts with telescope.nvim

2026-04-27T10:06:36+00:00

I’ve used telescope.nvim's find files with require("telescope.builtin").find_files for quite some time. I use find files together with it’s cousin .oldfiles (find recently opened files) all the time for finding source code files, blog posts, and more.

But it’s naturally restricted to operate on only filenames and you can make telescope richer by operating on structured data.

So let’s move away from using the files finder to find posts:

To a custom posts picker that display posts in a neater way and allows us to filter using tags or other metadata:

I use the filename_first option to display filenames before the directory in telescope.nvim files finders:

require("telescope").setup({
  defaults = {
    path_display = {
      "filename_first",
    },
  }
}

The simplest picker

It’s fairly easy to create a new picker for telescope.nvim. In it’s simplest form, all you need to do is provide a list of items:

local pickers = require("telescope.pickers")
local finders = require("telescope.finders")

pickers
  .new(opts, {
    finder = finders.new_table({
      results = { "One", "Two", "Three" },
    }),
  })
  :find()

Then we need to call the above code somehow, for example by wrapping it in a function and add a keymap to it:

local map = vim.keymap.set
map("n", "gd", require("blog.telescope").find_draft, { desc = "Find blog draft" })
map("n", "gp", require("blog.telescope").find_post, { desc = "Find blog post" })

Structured content

To make our simple picker handle structured content we need to:

Convert results to a list of tables with the info we have.
Specify an entry_marker function.

A rewrite of finder in our simple picker might look like this:

finder = finders.new_table({
  -- 1. Structured data inside `results`.
  results = {
    { title = "One", tags = "Tag1, Tag2", path = "posts/2024-01-01-one.dj" },
    { title = "Two", tags = "Tag2", path = "posts/2024-02-02-two.dj" },
  },
  -- 2. A function that converts a result entry to an entry telescope understands.
  entry_maker = function(entry)
    return {
      -- Display the post title instead of the path in the list.
      display = entry.title,
      -- Allow us to filter against the title and tags (typing `Tag1` finds the "One" post).
      ordinal = entry.title .. entry.tags,
      -- We could also save the whole entry for future usage, if we need it.
      value = entry,
    }
  end,
}),

With this the finder displays the title of the post rather than the file path, and we can search for a post using the title and its tags.

It’s easy to add more metadata to ordinal and it’ll mostly work, but the matching is crude and it can easily misfire depending on your use-case.

Because the way fuzzy matching works, if I type lua with the hope of listing all posts tagged lua, it will also match any post that has the letters l u a in that order, which is currently almost 40 of them:

Prompting for lua matches too many posts.
Here I’ve also added the post date to display.

Clearly, there’s room for improvement.

Structured filtering and sorting

Turns out that ordinal can also be a table, and you can provide your own sorter that operates on the ordinal to sort and filter.

This is the basic setup:

pickers
.new(opts, {
  finder = finders.new_table({
    results = {
      -- `tags` is now a list.
      { title = "One", tags = { "Tag1", "Tag2" }, path = "posts/2024-01-01-one.dj" },
      { title = "Two", tags = { "Tag2" }, path = "posts/2024-02-02-two.dj" },
    },
    entry_maker = function(entry)
      return {
        display = entry.title,
        -- `ordinal` is now a table containing all the entry info specified in `results`.
        ordinal = entry,
      }
    end,
  }),
  -- This is the important `sorter` function.
  sorter = post_sorter(opts),
})
:find()

post_sorter should return a new Sorter that describes the sorting behavior:

local function post_sorter(opts)
  opts = opts or {}
  -- We can use `fzy_sorter` for the actual fuzzy matching.
  local fzy_sorter = sorters.get_fzy_sorter(opts)

  return sorters.Sorter:new({
    -- Allow us to filter entries as well as sorting them.
    discard = true,

    scoring_function = function(_, prompt, entry)
      -- This mimics a standard fuzzy sorting on the entry title.
      return fzy_sorter:scoring_function(prompt, entry.title)
    end,

    -- We could also specify a highlighter. The highlighter works fine in this case,
    -- but if we modify `scoring_function` we have to modify this too.
    -- I admit, I currently don't use a highlighter for my posts finder.
    highlighter = fzy_sorter.highlighter,
  })
end

There’s some ceremony here that I hope is clear enough. The important thing here is the scoring_function that we’ll need to adjust.

First, the input arguments to scoring_function:

The first argument seems to be ignored even in Telescope’s own standard sorters, so I ignore it as well.
prompt is the user input to the Telescope prompt as a string.
entry is the ordinal entry that entry_maker returns.

For instance, in our example entry could be this:
```
{ title = "Two", tags = { "Tag2" }, path = "posts/2024-02-02-two.dj" }
```

What scoring_function should do is return a single numeric value signifying how close ordinal is to prompt, where higher means a better match. Because we defined discard = true if we return a value less than 0, the entry will get removed (filtered).

At first I thought this was a weird way of creating a sorting function. I had expected a comparison function like cmp(left, right) but after having played with it a little it seems pretty clever.

Sorter requirements

Before implementing scoring_function, let’s take a step back and figure out what behavior we want. You could go nuts with advanced features such as boolean operators, set comparisons, and similar. While cool, I don’t think it’s worth implementing as my requirements are fairly simple:

Fuzzy find on title, tags, and series.

I don’t want to require a perfect match on tags, requiring me to fully type out for example Experimental Gameplay Project would be quite annoying.
Explicitly filter posts by series and tags.

It’s neat if you can type some text and it filters for series or post title, but in practice I never really want that. If I want to filter against the post series, I want to be explicit about it and the same holds for tags.
Filter posts containing tag1 and tag2.

I contemplated searching for tag1 or tag2, but what I want is to reduce the number of matches as I add more information, not increase them.
Include published date in ordering.

At a base level I want to see newer posts before older ones. This is especially true when I first open telescope without prompting anything, then I want to see an ordered lists of all posts.

Prompt syntax

Because I want to be explicit we need some syntax to separate text we want to match against post tags, series, and title. Simplicity is nice, and a simple solution is to prefix tags with @ and prefix series with #, separated by spaces. I usually find that an example is worth a 1000 words, so here are some examples to shave down the precious words count:

@rust gleam

Require a post tag matching rust and post title matching gleam.
@3d @hex

Require a post tag matching 3d and one matching hex.
#34

Require a post series matching 34.
build # start

Require a post with a series and post title matching build start.

The code that converts a prompt into parts is conceptually simple: split the prompt into words and categorize them depending starting character. This is what I use:

local function split_prompt(prompt)
  local tags = {}
  local series = {}
  local title = {}
  -- Iterates over all non-space substrings.
  -- `prompt:gmatch` is syntax sugar for `string.gmatch(prompt, ..)`
  for word in prompt:gmatch("([^%s]+)") do
    -- Use `sub(1, 1)` to get the first character.
    -- It works with empty strings too!
    local fst = word:sub(1, 1)
    if fst == "@" then
      -- Use `sub(2)` to skip the `@`.
      table.insert(tags, word:sub(2))
    elseif fst == "#" then
      table.insert(series, word:sub(2))
    else
      table.insert(title, word)
    end
  end

  return {
    tags = tags,
    series = series,
    -- Combine non-tagged elements into a string.
    -- Could've be done outside this function but it'll always be done
    -- so I thought it would be easier to join here.
    title = vim.fn.join(title, " "),
  }
end

I’m a bit of a Lua noob, so there may be better solutions.

Implementing `scoring_function`

With a plan in place, let’s go back to try to realize it. The basic idea is to match against series, tags, and title separately and add their scores at the end:

scoring_function = function(_, prompt, entry)
  prompt = split_prompt(prompt)

  local series_score = score_element(prompt.series, entry.series, fzy_sorter)
  if series_score < 0 then
    return -1
  end

  local tags_score = score_element(prompt.tags, entry.tags, fzy_sorter)
  if tags_score < 0 then
    return -1
  end

  local title_score = fzy_sorter:scoring_function(prompt.title, entry.title)
  if title_score < 0 then
    return -1
  end

  return series_score + tags_score + title_score
end,

Remember that a return value of < 0 filters the entry, so we make sure to check that for each part. This is already how fzy_sorter:scoring_function works and it will either return < 0 for entries we should remove and a value in 0..1 otherwise. Because the matching of tags and series is so similar, I introduced the score_element helper function:

-- Match the list `prompt_elements` against `entry_element`, either a list or a string.
local function score_element(prompt_elements, entry_element, sorter)
  -- We didn't prompt for this type, ignore it.
  -- This is a "is list empty?" check in Lua.
  if next(prompt_elements) == nil then
    return 0
  end

  -- We prompted for this type, but entry didn't have it, so remove the entry.
  -- For example if we prompt for a series, this removes all posts
  -- without a series.
  if not entry_element then
    return -1
  end

  -- Convert multiple entry values to a string like `tag1:tag2`.
  local entry
  -- We can use `type()` to dynamically check the type of a variable
  -- and act occordingly.
  if type(entry_element) == "string" then
    entry = entry_element
  elseif type(entry_element) == "table" then
    entry = vim.fn.join(entry_element, ":")
  end

  local total = 0
  -- For each prompt element (`tag1`, `tag2`, ...), match against the entry string (`tag1:tag2`).
  for _, prompt_element in ipairs(prompt_elements) do
    local score = sorter:scoring_function(prompt_element, entry)
    -- Require a match for every element.
    if score < 0 then
      return -1
    end
    total = total + score
  end

  -- Clamp score to 0..1.
  -- Not strictly needed but it feels neater.
  return total / #prompt_elements
end

With this in place we have a working sorter.

If we type regular text, then series_score and tags_score will be 0, practically ignoring them.
A #series_filter will set series_score == -1 unless the post has a matching series, removing the entry.
And typing @tag1 @tag2 will require a match for every tag, otherwise tags_score == -1 that again removes the entry.
Adding the fuzzy scores together gives us a pretty good fuzzy matching behavior I feel.

The only requirement left is to order posts by date. It must be done carefully not to override the sort order we get from the fuzzy matching.

One way to do this is to sort all posts and add a post counter to each entity (so the first post would get 1 and the last 272) and then add it to the final score somehow. This felt a little cumbersome and I wanted to see if I could implement the scoring function without having to sort the entries first. After all, we already have the date of each post…

This is possible by placing the post on a timeline between the date of the very first post and today, and then clamping the range to 0..1. Something like this:

-- Date of my first blog post as a number.
local beginning_of_time = 20090621
-- Today's date as a number.
local today = os.date("%Y%m%d")
-- The entry date looks like `2023-01-31`, if we remove `-` it's formatted like the above.
local entry_date = string.gsub(entry.date, "-", "")
-- Place the entry date on a 0..1 scale, where 1 is today.
-- (`1 -` reverses, otherwise 1 would be the beginning of time).
local date_score = 1 - (entry_date - beginning_of_time) / (today - beginning_of_time)

-- Date sorting is only worth 1/10 of the fuzzy scores.
-- Why? I dunno, 1 was too much and 1/10 felt good.
return series_score + tags_score + title_score + date_score / 10

Okay, I admit it’s a little hacky; but it’s a fun one that fulfills my needs.

Formatting entries

It’s possible to customize how telescope.nvim displays an entry in the results list, see :help telescope.pickers.entry_display.

You’ll use entry_display.create() to create a formatting function that divides the display into columns, then you pass in the columns to produce the line to be displayed.

This is a basic example that divides the line into two parts; an icon and a title, together with a highlight group to colorize the parts:

local entry_display = require("telescope.pickers.entry_display")

entry_maker = function(entry)
  return {
    display = function(entry)
      local displayer = entry_display.create({
        separator = " ",
        items = {
          { width = 1 },
          { remaining = true },
        },
      })

      return displayer({
        { "󰇷", "TelescopeResultsComment" },
        { entry.value.title, "TelescopeResultsNumber" },
      })
    end
    -- ..
  }
end

The display I use to display filetype icon, title, date, tags, and series is a little more complex but the display logic is similar:

local devicons = require("nvim-web-devicons")
local telescope_utils = require("telescope.utils")

local make_display = function(entry)
  -- Djot doesn't have an icon, I just picked something that looked neat.
  local ext = telescope_utils.file_extension(entry.value.path)
  if ext == "dj" then
    ext = "tcl"
  end
  local icon, _ = devicons.get_icon_by_filetype(ext)

  -- Tags may be a string or a table, convert it for display purposes.
  local tags
  if type(entry.value.tags) == "string" then
    tags = entry.value.tags
  elseif type(entry.value.tags) == "table" then
    tags = vim.fn.join(entry.value.tags, ", ")
  end

  local series = entry.value.series or ""

  local displayer = entry_display.create({
    separator = " ",
    items = {
      { width = 1 },
      { width = string.len(entry.value.title) },
      { width = string.len(entry.value.date) },
      { width = string.len(tags) },
      { remaining = true },
    },
  })

  return displayer({
    { icon, "TelescopeResultsComment" },
    -- We can skip highlight groups if we want.
    entry.value.title,
    { entry.value.date, "TelescopeResultsComment" },
    { tags, "TelescopeResultsConstant" },
    { series, "TelescopeResultsOperator" },
  })
end

Since I grouped the display in a function, we need to set that to display in entry_maker:

entry_maker = function(entry)
  return {
    display = make_display,
    -- ...
  }
end

I use nvim-web-devicons to map a Nerd Nerd Font icon to a filetype (also used by telescope.nvim for the standard file pickers if available).

File preview

One of the great features of telescope.nvim is the very fast preview with syntax highlighting, which we naturally must configure.

I searched through the telescope help, and found the functions new_buffer_previewer and buffer_previewer_maker that allows us to define a previewer for a file:

local previewers = require("telescope.previewers")

finder = finders.new_table({
  -- ...

  previewer = previewers.new_buffer_previewer({
    -- Title isn't needed.
    title = "Post Preview",
    define_preview = function(self, entry)
      -- Notice `entry.value.path` that uses our catch-all entry value.
      conf.buffer_previewer_maker(entry.value.path, self.state.bufnr, {
        bufname = self.state.bufname,
        winid = self.state.winid,
        preview = opts.preview,
        -- The file encoding is needed for proper syntax highlighting.
        file_encoding = opts.file_encoding,
      })
    end,
  }),
})

I’m not sure if there’s a less verbose way to define a file previewer, as the only things I configured here are the title and the entry.value.path argument to buffer_preview_maker.

Open the selected file

We have the display of our telescope.nvim picker configured. Now how do we open the file once we’ve found it? By default there’s no way of interacting with an entry, we can only look at it.

Turns out all you need to do is add filename to entry_maker:

entry_maker = function(entry)
  return {
    -- Make standard action open `entry.path`.
    filename = entry.path,
  }
end

At first I implemented opening manually using attach_mappings:

local actions = require("telescope.actions")

finder = finders.new_table({
  -- ...
  attach_mappings = function(prompt_bufnr)
    actions.select_default:replace(function()
      local selection = action_state.get_selected_entry()
      actions.close(prompt_bufnr)
      vim.cmd(":e " .. selection.value.path)
    end)
    return true
  end,
})

The above mapping overrides the default selection action (<CR>) to :edit value.path of our selection, which will open the selected file.

Finding the post data to populate the picker

So far I’ve only used placeholder data for the posts, but we need to search the file system for the markup files for the posts.

It’s not as simple as listing files in a directory, we also need to extract post metadata that’s defined in a frontmatter at the beginning of every markup file:

---toml
title = "Let's build a VORON: Noise"
tags = ["3D printing", "VORON"]
series = "voron_trident"
---

How can we do this?

With ripgrep and regex of course!

xkcd 208

This time though I have a good reason for choosing an external tool rather than asking the backend server: I want to be able to find a post the very first thing I do when opening Neovim, and I don’t want to wait on connecting to a backend service, or requiring one running at all times.

The strategy is to use ripgrep to match the frontmatter in all posts, extract the metadata using some hacky Lua regex, and combine them into a post struct we can feed into the finder we developed.

Here’s one way that uses nvim-nio and ripgrep to find all posts under a path and extract the frontmatter:

local nio = require("nio")
local path = require("blog.path")

nio.process.run({
  cmd = "rg",
  args = {
    "-NoHU",
    "--heading",
    "\\A\\---\\w*\\n(.+\\n)+^---",
    -- Subpath could be `posts/` or `drafts/`, converted to an absolute path.
    path.blog_path .. subpath,
  },
})

Which will produce output formatted like this:

posts/2016-07-29-slackware_installation_notes.markdown
---
layout: post
title: "Slackware installation notes"
tags: Slackware
---

posts/2019-01-25-site_restyle_and_update.markdown
---
title: "Site restyle and update"
tags: ["Blog", "Web Design"]
---

posts/2024-02-27-lets_build_a_voron_more_mods.dj
---toml
title = "Let's build a VORON: More mods"
tags = ["3D printing", "VORON"]
series = "voron_trident"
---

My code for splitting the output and extracting the metadata is really gross:

local lines = vim.fn.split(output, "\n")
local posts = {}

local post = {}
for _, line in ipairs(lines) do
  -- When a newline is encountered save the post and prepare for the next entry.
  if line == "" then
    if post.title then
      table.insert(posts, post)
    end
    post = {}
    -- Skip `---` markers.
  elseif not string.match(line, "%-%-%-%w*") then
    -- Try to extract all key value definitions and store them.
    local key, value = string.match(line, "(%w+)%s*[:=]%s*(.+)")
    if key then
      -- Strip surrounding quotes.
      -- Do this here because there's no non-greedy specifier that could be used
      -- in the key/value regex above.
      value = trim_quotes(value)
      -- Split a sequence.
      local seq = string.match(value, "^%[(.+)%]$")
      if seq then
        local parts = {}
        for part in string.gmatch(seq, "%s*([^,]+)") do
          table.insert(parts, trim_quotes(part))
        end
        value = parts
      end
      post[key] = value
    else
      -- If no key value pair is found, then we should be at the beginning with the file path.
      post["path"] = line
      -- Only posts have a date in the path, not drafts.
      local date = string.match(line, "posts/(%d%d%d%d%-%d%d%-%d%d)%-")
      if date then
        post["date"] = date
      else
        -- Use the modified timestamp for drafts.
        post["date"] = os.date("%Y-%m-%d", util.file_modified(line))
      end
    end
  end
end
-- If output ends we might have an unsaved post.
if post.title then
  table.insert(posts, post)
end

local function trim_quotes(s)
  local stripped = string.match(s, '^"(.+)"$')
  if stripped then
    return stripped
  else
    return s
  end
end

Yes, I’m using regex to parse yaml/toml values.

I could try to find a lua parser, but eeeh…

Stupid decisions aside, with all this we have a working telescope.nvim picker! I may have skipped some details, so take a look at the source code if you’re interested.

Customizing Neovim

2026-04-27T10:16:45+00:00

Scripting is configuration. Configuration is scripting.

TJ DeVries A different take on editing code

I’ve been using Neovim since it forked from Vim almost 8 years ago, and I used Vim many years before that. I feel quite comfortable with Neovim, and I’ve gone down the configuration rabbit hole too many times I’d like to admit, but I never dove deeper by writing something truly custom like a plugin.

That changed when I got inspired by the excellent Developing a Neovim Docker Plugin from Scratch where the creator goes through how to extend telescope.nvim in a very pedagogical manner.

I was only planning to make a simple telescope picker… Yet I fell into rabbit hole again and ended up implementing some cool features such as:

Browse posts using telescope.nvim.
Autocomplete post urls, link definitions, and more using nvim-cmp.
Goto definition.
Diagnostics.
Browser preview with auto refresh and scroll.

Because of my overambitious self, I couldn’t squeeze all these topics into a single blog post, so I split the post into a series. This first post will go through how to get started configuring Neovim with a basic setup and some user commands, leaving the more advanced topics for later posts.

See the source for the Neovim blog integration on GitHub and the site source on Codeberg.

Initial setup

While I could develop this as a normal plugin, because it’s for my personalized blogging setup I decided to organize it under nvim/lua/blog:

lua/blog/
├── autocmd.lua
├── cmp.lua
├── commands.lua
├── content.lua
├── diagnostics.lua
├── files.lua
├── goto.lua
├── init.lua
├── path.lua
├── server.lua
└── telescope.lua

And include the relevant code in my init script at init.lua (well, really lua/config/init.lua but a white lie to make it easier to grokk doesn’t hurt):

require("blog")

This calls lua/blog/init.lua that in turn requires other initialization files:

require("blog.autocmd")
require("blog.cmp")
require("blog.commands")

The above files handles the initial registration, the other files are required when they’re needed.

For example, autocmd.lua registers a { "BufRead", "BufNewFile" } autocommand that establishes a connection to the backend, and registers buffer local keymaps:

-- This way we include other blog related functionality
local path = require("blog.path")
local server = require("blog.server")
local diagnostics = require("blog.diagnostics")

local keymaps = require("config.keymaps")

local autocmd = vim.api.nvim_create_autocmd
local augroup = vim.api.nvim_create_augroup

local blog_group = augroup("blog", { clear = true })
-- Only handle Djot files inside the blog directory
-- (at `~/code/jonashietala`).
local autocmd_pattern = path.blog_path .. "*.dj"

-- The callback function is called whenever a `.dj` file
-- is read or created.
autocmd({ "BufRead", "BufNewFile" }, {
  pattern = autocmd_pattern,
  group = blog_group,
  callback = function(opts)
    -- Register buffer local keymaps.
    keymaps.buf_blog(opts.buf)
    -- Other initialization go here...
  end,
})

One quirk of my Neovim config is that I’ve tried to collect all keymaps in one file, where I added some new keymaps for the blog:

local map = vim.keymap.set

-- Called via `init.lua`.
M.init = function()
  map("n", "gd", require("blog.telescope").find_draft, { desc = "Find blog draft" })
  map("n", "gp", require("blog.telescope").find_post, { desc = "Find blog post" })
  -- Lots of other keymaps...
end

-- Used by the "BufRead", "BufNewFile" autocommand shown above.
M.buf_blog = function(buffer)
  map("n", "<localleader>t", require("blog.telescope").find_tags, { buffer = buffer, desc = "List tags" })
  map("n", "<localleader>d", require("blog.goto").goto_def, { buffer = buffer, desc = "Goto definition" })
end

Where buf_blog is called by the autocommand when editing a blog post.

Creating and moving posts

One of the basic features I want is having user commands that simplify my life a little—like creating a new post.

When I write a blog post I start by creating a markup file in drafts/, that should contain a frontmatter with some metadata like so:

---toml
title = "Customizing Neovim"
tags = ["Lua", "Neovim"]
series = "extending_neovim_for_my_blog"
---

When I feel the post is done I “promote” the draft to a blog post by moving it from drafts/ to posts/, while adding the release date to the path.

I didn’t do this file manipulation manually—that would be crazy—I had it implemented as an option in the blog generation tool (the blog is a static site, generated by a Rust command-line program).

I think it’s better to to have this kind of manipulation inside Neovim, which is a good starting point for our customization.

User commands

I think implementing them as user commands makes sense—I’ll forget them if I create I keybinding for them. (I know, I tried.)

I setup user commands in blog/commands.lua:

local cmd = require("util").create_cmd
local files = require("blog.files")

-- Create a new draft, promote it to a post, or revert it back to a draft.
cmd("BlogNewDraft", files.new_draft)
cmd("BlogPromoteDraft", files.promote_curr_draft)
cmd("BlogDemotePost", files.demote_curr_post)

In Neovim you can use vim.api.nvim_create_user_command to create a user command. Because it takes three arguments, with the third options argument only being empty, I use the helper create_cmd to make it optional:

-- A module file in lua by convention use an `M` table,
-- allowing us to call`require("util").create_cmd(...)`.
local M = {}

M.create_cmd = function(command, f, opts)
  opts = opts or {}
  vim.api.nvim_create_user_command(command, f, opts)
end

return M

New draft

Creating a draft should do two things:

Create a file at drafts/some_title.dj under the blog directory.
Open it and fill in some placeholder data.

Creating a file and opening it can be done using vim.cmd to send the :edit command.

Inserting text from lua was harder to figure out, I tried to search Neovim’s help with :Telescope help_tags but came up short. In the end I found vim.api.nvim_buf_set_lines via Google that can be used to insert lines.

This is the solution I came up with:

local path = require("blog.path")
local nio = require("nio")

local M = {}

M.new_draft = function()
  nio.run(function()
    -- Prompt for the title of the new draft.
    local title = nio.ui.input({ prompt = "Draft title: " })

    -- Create and open the draft for edit (without checking if it exists...)
    -- `path.blog_path` expands to the path to my blog and `slugify` converts
    -- a title to a slug by replacing spaces with underscores and removing symbols.
    local file_path = path.blog_path .. "drafts/" .. M.slugify(title) .. ".dj"
    vim.cmd(":e " .. file_path)

    -- The text the draft will start with.
    local template = {
      "---toml",
      'title = "' .. title .. '"',
      'tags = ["Some tag"]',
      "---",
    }
    -- Insert the text into the current buffer (0) at row 0 (to 0).
    vim.api.nvim_buf_set_lines(0, 0, 0, true, template)
  end)
end

-- Convert a title to a "slug" used in the post path and url.
-- for example, converts `My title` to `my_title`.
M.slugify = function(title)
  title = title:lower()
  -- Remove disallowed characters.
  title = title:gsub("[^ a-zA-Z0-9_-]+", "")
  -- Convert spaces and multiple `_` to a single `_`.
  title = title:gsub("[ _]+", "_")
  -- Remove dashes and underscores from the beginning and end.
  title = title:gsub("^[ _-]+", "")
  title = title:gsub("[ _-]+$", "")
  return title
end

return M

I hope it’s clear what the above code is doing, but I want to call out the usage of nvim-nio. It’s a great library that makes asynchronous programming simple in Neovim.

To start an async task you use nio.run:

nio.run(function()
  -- Code here is run async
end)

For this example of creating a new draft async is overkill. Async is required for some other situations and it’s easy to add so I use it liberally, even when not strictly needed.

Moving files

In my blogging setup I store posts under posts/ with the release date in the path, and drafts under drafts/. So promoting and demoting is accomplished by moving the file:

Promote a draft to a post by moving it from drafts/post_title.dj to posts/2024-04-14-post_title.dj.
Demote a post by moving it from posts/2024-04-14-post_title.dj to drafts/post_title.dj.

Instead of pasting a big chunk of code, let’s go through the most important implementation details:

I want to use the title from the metadata because I’ll often change the title and I want the slug to be updated.

We can extract the title from the post by shelling out to ripgrep that matches against a title = "My title" line.

nvim-nio provides process.run to run a shell command:
```
local proc = nio.process.run(args)
proc.stdout.read()
```
We can use process.run to run ripgrep to search for the title by passing this table as args:
```
{
  cmd = "rg",
  args = {
     "-INo",
     "^title = (.+)$",
    path,
  },
}
```
Because we might get multiple matches (such as in this post), we can extract it using Lua:
```
return output:match('title = "([^%"]+)"')
```
Not the prettiest solution I’ve come up with.

Another solution would be to rely on the Rust blog generation tool to provide the title; it would be more robust since the backend properly parses the file. I started with this route as one of my goals with customizing Neovim was to familiarize myself more with Lua. I may move it in the future if the need arises.

Create the destination path.

For example a post path is created like this:

path.blog_path
  .. "posts/"
  .. os.date("%Y-%m-%d")
  .. "-"
  .. M.slugify(title)
  .. ".dj"

Move the file.

I don’t know what the idiomatic way to rename a file is, or even how to do it in Neovim using Lua. But I do know that with :! you can call an external program… Like mv!

So here’s one way to rename a file, that works for me on Linux:
```
vim.cmd(":!mv " .. from .. " " .. to)
vim.cmd(":e " .. to)
```
Because everything is done in an async context (inside nio.run) we run into a problem: we can’t call the Neovim API. We’ll get an error like this:
```
...e/tree/.local/share/nvim/lazy/nvim-nio/lua/nio/tasks.lua:95: Async task failed without callback: The co
routine failed with this message:
vim/_editor.lua:0: E5560: nvim_exec2 must not be called in a lua loop callback
stack traceback:
        [C]: in function 'nvim_exec2'
        vim/_editor.lua: in function 'cmd'
        /home/tree/.config/nvim/lua/blog/files.lua:82: in function '_rename'
        /home/tree/.config/nvim/lua/blog/files.lua:116: in function s.lua:106>
```
The error to look out for is nvim_exec2 must not be called in a lua loop callback, which I assume means that nio uses the lower level lua loop API for its async system.

What we need to do is yield to the Neovim scheduler before calling vim.cmd to rename the file, which can be done with nio.scheduler():
```
nio.scheduler()
-- Now we can call `vim.cmd` and `vim.fn`.
```

More functionality

I have some more user commands for creating other types of files; series, projects, and standalones (see /uses) but they work exactly the same as creating drafts. There are a few other commands that I’ll bring up in future posts, which will go into more advanced functionality.

Let's create a Tree-sitter grammar

2026-04-27T10:59:37+00:00

One of my favorite features in Neovim is the Tree-sitter integration. It allows for fast syntax highlighting that works well even in an error state (often the case when you’re editing code), and it has additional semantics (you can differentiate between function parameters and local variables).

With nvim-treesitter-textobjects you can also jump between nodes (such as ]c to jump to next class) or target deletion (cif to delete the function body and enter insert mode). An amazing feature as it works across languages, no matter how they look like, as long as they have a Tree-sitter grammar (most do).

But, you might wonder what does a Tree-sitter grammar look like, and how do you create one for a language?

I started thinking about this and before I knew it I was trying to make my own parser for Djot (a markup language similar to Markdown). There are some good tutorials on how to get started, but not on some more advanced things.

I spent quite some time trying to figure it out—while refreshing my 10 year old knowledge of grammars—and decided to document some of my findings.

The post spiraled out of control a little, and it will go through:

How to use an external scanner
Using Tree-sitter’s built-in conflicts resolution
Syntax highlighting with language injection
Use the grammar from Neovim for syntax highlighting and textobjects
Embed the grammar into this Blog for syntax highlighting

The source code for the complete grammar we’ll develop can be found on Codeberg.

Our subset

For the purpose of this blog post, we’ll implement a small subset of Djot, where we’ll support:

Paragraphs
Divs
Code blocks
Emphasis

This will allow us to parse markup like this:

This is a
multiline _paragraph_

:::
This is a paragraph inside a div
:::

```gleam
let x = 2;
```

(Yes, the sdjot highlight uses our grammar.)

At first blush, this seems like it’s too simple to require anything more complex than some simple grammar rules, but later on we’ll see that even these simple rules requires a bit more effort to fully support.

Simple beginnings

The point of this post isn’t to go through how the Tree-sitter grammar description in grammar.js works. The Tree-sitter docs goes through how to get started. I named the project sdjot and this is the grammar.js we’ll start with:

module.exports = grammar({
  name: "sdjot",

  // Skip carriage returns.
  // We could skip spaces here as well, but the actual markup language
  // has significant spaces in some places, so let's remove them here too.
  extras: (_) => ["\r"],

  rules: {
    document: ($) => repeat($._block),

    // All blocks should end with a newline, but we can also parse multiple newlines.
    _block: ($) => choice($.div, $.code_block, $.paragraph, "\n"),

    // A div contains other blocks.
    div: ($) =>
      prec.left(seq($.div_marker, "\n", repeat($._block), $.div_marker, "\n")),
    div_marker: (_) => ":::",

    // Code blocks may have a language specifier.
    code_block: ($) =>
      seq(
        $.code_block_marker,
        optional($.language),
        "\n",
        optional($.code),
        $.code_block_marker,
      ),
    code_block_marker: (_) => "```",
    code: (_) => repeat1(seq(/[^\n]*/, "\n")),
    language: (_) => /[^\s]+/,

    // A paragraph contains inline content and is terminated by a blankline
    // (two newlines in a row).
    paragraph: ($) => seq(repeat1(seq($._inline, "\n")), "\n"),

    // The markup parser could separate block and inline parsing into separate steps,
    // but we'll do everything in one parser.
    _inline: ($) => repeat1(choice($.emphasis, $._text)),
    emphasis: ($) => prec.left(seq("_", $._inline, "_")),
    _text: (_) => /[^\n]/,
  },
});

It recognizes paragraphs with text and emphasis, and it identifies divs and code blocks.

We can create an example-file with these contents:

:::
A paragraph _with emphasis_ inside a div

:::

And parse it with the tree-sitter cli:

$ tree-sitter parse example-file
(document [0, 0] - [5, 0]
  (div [0, 0] - [4, 0]
    (div_marker [0, 0] - [0, 3])
    (paragraph [1, 0] - [3, 0]
      (emphasis [1, 12] - [1, 27]))
    (div_marker [3, 0] - [3, 3])))

Et voilà!

Missing features

But I told you it wasn’t supposed to be this easy, and there are features missing from our parser. Most notably:

There can be an arbitrary number of :, allowing divs to be nested.
Closing a div should close other open blocks (divs and paragraphs in our case).

In essence, we need to be able to parse this:

:::
Top-level div

::::
A paragraph inside a second div,
both closed when the top-level div is closedj
:::

This is… Complicated.

Sure, we can work around the varying levels of : with something hacky like enumerating the number of colons, using something like this:

div: ($) => choice($._div3, $._div4, $._div5, $._div6, $._div7, $._div8),
_div3: ($) => seq(/:{3}/, $._inside_div, /:{3}/, "\n"),
_div4: ($) => seq(/:{4}/, $._inside_div, /:{4}/, "\n"),
_div5: ($) => seq(/:{5}/, $._inside_div, /:{5}/, "\n"),
_div6: ($) => seq(/:{6}/, $._inside_div, /:{6}/, "\n"),
_div7: ($) => seq(/:{7}/, $._inside_div, /:{7}/, "\n"),
_div8: ($) => seq(/:{8}/, $._inside_div, /:{8}/, "\n"),
_inside_div: ($) => prec.left("\n", repeat($._block)),

But it’s not neat, and automatically closing contained blocks is much harder (to my brain it seems impossible, but I’m no expert).

With an external scanner we can do this (and more).

External scanner

A Tree-sitter parser is actually a C program. The grammar we’ve seen has been described in JavaScript, but it’s only used as a description to generate the parser in C. If you’re a masochist, you can take a look at it in src/parser.c after running tree-sitter generate.

An external scanner is just some custom C code that’s inserted into the parser, and it allows us to override the parser precedence, keep track of a context state, or whatever else we might need or want to do.

To get started the official docs was pretty good. Basically you need to:

Create a src/scanner.c and include it in binding.gyp bindings/rust/build.rs.
Setup externals tokens in grammar.js and a matching C enum in scanner.c.
Define and implement five C functions.

Let’s take a look.

Div markers closes open paragraphs

Let’s start by closing a paragraph early when a ::: is encountered. This is simpler because we can solve this without storing any state.

When parsing $.paragraph we’ll give the parser a choice between ending the paragraph on a newline or on our new $._close_paragraph token:

paragraph: ($) =>
  seq(repeat1(seq($._inline, "\n")), choice("\n", $._close_paragraph)),

$._close_paragraph is handled by the external scanner, which is specified using the externals field:

externals: ($) => [$._close_paragraph],

Now let’s turn our attention to src/scanner.c. The tokens in externals gets assigned an incremented number, starting from 0… Just like an enum in C!

// We only have a single element right now, but keep in mind that the order
// must match the `externals` array in `grammar.js`.
typedef enum { CLOSE_PARAGRAPH } TokenType;

The five functions we need to implement are these:

// You should replace `sdjot` with whatever project name you chose.
bool tree_sitter_sdjot_external_scanner_scan(void *payload, TSLexer *lexer,
                                             const bool *valid_symbols) {
  // All the scanning goes here.
  return false;
}

// If we need to allocate/deallocate state, we do it in these functions.
void *tree_sitter_sdjot_external_scanner_create() { return NULL; }
void tree_sitter_sdjot_external_scanner_destroy(void *payload) {}

// If we have state, we should load and save it in these functions.
unsigned tree_sitter_sdjot_external_scanner_serialize(void *payload,
                                                      char *buffer) {
  return 0;
}
void tree_sitter_sdjot_external_scanner_deserialize(void *payload, char *buffer,
                                                    unsigned length) {}

Because we won’t use any state, we’ll only have to update the scan function.

What you’re supposed to do is check valid_symbols for the tokens we can return at any point in time, and return true if any was found:

bool tree_sitter_sdjot_external_scanner_scan(void *payload, TSLexer *lexer,
                                             const bool *valid_symbols) {
  if (valid_symbols[CLOSE_PARAGRAPH] && parse_close_paragraph(lexer)) {
    return true;
  }
  return false;
}

To decide if we’re going to close the paragraph early, we’ll look ahead for any :::, and if so we’ll close it without consuming any characters. This might not be the most efficient solution because we’ll have to parse the ::: again, but it gets the job done.

The matched token should be stored in lexer->result_symbol:

static bool parse_close_paragraph(TSLexer *lexer) {
  // Mark the end before advancing so that the CLOSE_PARAGRAPH token doesn't
  // consume any characters.
  lexer->mark_end(lexer);

  uint8_t colons = consume_chars(lexer, ':');
  if (colons >= 3) {
    lexer->result_symbol = CLOSE_PARAGRAPH;
    return true;
  } else {
    return false;
  }
}

Note that the resulting token will mark any symbol we advance over as owned by that token. So ::: would be marked as _close_paragraph (which will be ignored by the output since it begins with an underscore), instead of div_marker. To prevent this, we turn _close_paragraph into a zero-width token by marking the end before advancing the lexer.

How do we advance the lexer? We call lexer->advance:

static uint8_t consume_chars(TSLexer *lexer, char c) {
  uint8_t count = 0;
  while (lexer->lookahead == c) {
    lexer->advance(lexer, false);
    ++count;
  }
  return count;
}

This is almost all we can do with the lexer. We only process one character at a time, cannot look behind, and our only tool to look ahead is to mark_end at the correct place. (We can also query the current column position.)

With this we have a working external scanner and div tags now close paragraphs:

:::
A paragraph inside a div
:::

$ tree-sitter parse example-file
(document [0, 0] - [4, 0]
  (div [0, 0] - [3, 0]
    (div_marker [0, 0] - [0, 3])
    (paragraph [1, 0] - [2, 0])
    (div_marker [2, 0] - [2, 3])))

Nested blocks

To automatically close other open blocks we need to add some context to our parser, which means we’ll need state management.

The small subset we’re implementing is only concerned with closing divs—because it would be a terribly long post otherwise—but I’ll try to implement this in a general manner, to be more indicative of a real-world parser.

Our strategy is this:

A div can have a varying number of : that must match.

Therefore we’ll parse colons in an external scanner and store it on a stack.
When we find a div marker, we’ll need to decide if it should start a new div, or close an existing one.

We’ll look at the stack of open blocks and see if we find a match.
If we have need to close a nested div, that is if we want to close a div further down the stack, we need to close the nested div(s) first.

Thus we’ll introduce a block_close marker that ends a div, and leave the ending div marker as optional.

First we’ll ask the grammar to let the external scanner manage the begin and end tokens. We’ll use a _block_close marker to end the div, and leave the end marker optional. (You could probably use a choice() between the two, but this made more sense to me when I was implementing it.)

div: ($) =>
  prec.left(
    seq(
      // A rule starting with "_" will be hidden in the output,
      // and we can use "alias" to rename rules.
      alias($._div_marker_begin, $.div_marker),
      "\n",
      repeat($._block),
      $._block_close,
      optional(alias($._div_marker_end, $.div_marker))
    )
  ),

externals: ($) => [
  $._close_paragraph,
  $._block_close,
  $._div_marker_begin,
  $._div_marker_end,

  // This is used in the scanner internally,
  // but shouldn't be used by the grammar.
  $._ignored,
],

And remember to update the list of external tokens in the scanner (order matters):

typedef enum {
  CLOSE_PARAGRAPH,
  BLOCK_CLOSE,
  DIV_MARKER_BEGIN,
  DIV_MARKER_END,
  IGNORED
} TokenType;

Then to our stack of blocks.

I used a Block type to keep track of the type and number of colons:

// In a real implementation we'll have more block types.
typedef enum { DIV } BlockType;

typedef struct {
  BlockType type;
  uint8_t level;
} Block;

I know that level isn’t the best name, but I couldn’t find a very good general name for the number of colons, indentation level, etc. With sum types you could model it in a clearer way, like this:

enum Block {
    Div { colons: u32 },
    Footnote { indent: u32 },
    // etc
}

I will, in fact, claim that the difference between a bad programmer and a good one is whether he considers his code or his data structures more important. Bad programmers worry about the code. Good programmers worry about data structures and their relationships.

Linus Torvalds

But I digress, I’ll go with level like a bad programmer.

Another joy of programming C is that you’ll get to re-implement standard data structures such as a growable stack. It’s not truly difficult, but it’s annoying and bug-prone.

Luckily, during the time I’m writing this blog post, tree-sitter 0.22.1 was released with an array implementation. So now I don’t have to show you my shoddy stack implementation, and we can use their array for our stack instead.

We’ll shove our Array of Block* into a Scanner struct, because we’ll need to track more data later:

#include "tree_sitter/array.h"

typedef struct {
  Array(Block *) * open_blocks;
} Scanner;

When you manage state in tree-sitter, you need to do some data management in the tree_sitter_ functions we defined earlier.

Allocations are managed in the _create and _destroy functions. Also new for 0.22.1 is the recommendation to use ts_ functions for allocations, to allow consumers to override the default allocator:

#include "tree_sitter/alloc.h"

void *tree_sitter_sdjot_external_scanner_create() {
  Scanner *s = (Scanner *)ts_malloc(sizeof(Scanner));

  // This is how you create an empty array
  s->open_blocks = ts_malloc(sizeof(Array(Block *)));
  array_init(s->open_blocks);

  return s;
}

void tree_sitter_sdjot_external_scanner_destroy(void *payload) {
  Scanner *s = (Scanner *)payload;

  // I haven't shown the allocation of the blocks yet,
  // but keep in mind that `array_delete` does not deallocate any memory
  // you store in the array itself.
  for (size_t i = 0; i < s->open_blocks->size; ++i) {
    // I use `array_get` even though you can index the contents directly.
    ts_free(array_get(s->open_blocks, i));
  }

  // The array is a growable one, `array_delete` ensures that the
  // memory is deleted.
  array_delete(s->open_blocks);

  ts_free(s);
}

I allocate the blocks in a push_block helper:

static void push_block(Scanner *s, BlockType type, uint8_t level) {
  Block *b = ts_malloc(sizeof(Block));
  b->type = type;
  b->level = level;

  // Grows the stack automatically.
  array_push(s->open_blocks, b);
}

You also need to define the serialize functions. These store and retrieve the managed state, to allow tree-sitter to backtrack.

unsigned tree_sitter_sdjot_external_scanner_serialize(void *payload,
                                                      char *buffer) {
  Scanner *s = (Scanner *)payload;
  unsigned size = 0;
  for (size_t i = 0; i < s->open_blocks->size; ++i) {
    Block *b = *array_get(s->open_blocks, i);
    buffer[size++] = (char)b->type;
    buffer[size++] = (char)b->level;
  }
  return size;
}

void tree_sitter_sdjot_external_scanner_deserialize(void *payload, char *buffer,
                                                    unsigned length) {
  Scanner *s = (Scanner *)payload;
  array_init(s->open_blocks);
  size_t size = 0;
  while (size < length) {
    BlockType type = (BlockType)buffer[size++];
    uint8_t level = (uint8_t)buffer[size++];
    push_block(s, type, level);
  }
}

And that’s the (initial) state management taken care of!

Div markers

Of course, we haven’t used our state yet. Let’s change that.

First, let’s add the parse_div entry point to our scan function:

bool tree_sitter_sdjot_external_scanner_scan(void *payload, TSLexer *lexer,
                                             const bool *valid_symbols) {
  Scanner *s = (Scanner *)payload;

  // Paragraph needs to be closed before we try to close divs.
  if (valid_symbols[CLOSE_PARAGRAPH] && parse_close_paragraph(lexer)) {
    return true;
  }

  // Check `valid_symbols` inside `parse_div` because of multiple valid symbols.
  if (parse_div(s, lexer, valid_symbols)) {
    return true;
  }

  return false;
}

Because advancing the lexer is primitive, and we cannot “go back a char”, it’s important to only advance it if we really need to. Therefore we always need to check valid_symbols before we continue:

static bool parse_div(Scanner *s, TSLexer *lexer, const bool *valid_symbols) {
  if (!valid_symbols[DIV_MARKER_BEGIN] && !valid_symbols[DIV_MARKER_END]) {
    return false;
  }

  // ...
}

Next we’ll need to consume all colons we’re at, and only continue if we see at least three:

static uint8_t consume_chars(TSLexer *lexer, char c) {
  uint8_t count = 0;
  while (lexer->lookahead == c) {
    lexer->advance(lexer, false);
    ++count;
  }
  return count;
}

static bool parse_div(Scanner *s, TSLexer *lexer, const bool *valid_symbols) {
  // ...

  uint8_t colons = consume_chars(lexer, ':');
  if (colons < 3) {
    return false;
  }

  // ...
}

Opening a new div is simple; we push the block and register the number of colons:

push_block(s, DIV, colons);
lexer->result_symbol = DIV_MARKER_BEGIN;
return true;

But to the decide if we should open or close a div, we need a way to search through the stack. This function does that, while also returning how many blocks deep into the stack we found the div (which we’ll use shortly):

// How many blocks from the top of the stack can we find a matching block?
// If it's directly on the top, returns 1.
// If it cannot be found, returns 0.
static size_t number_of_blocks_from_top(Scanner *s, BlockType type,
                                        uint8_t level) {
  for (int i = s->open_blocks->size - 1; i >= 0; --i) {
    Block *b = *array_get(s->open_blocks, i);
    if (b->type == type && b->level == level) {
      return s->open_blocks->size - i;
    }
  }
  return 0;
}

static bool parse_div(Scanner *s, TSLexer *lexer, const bool *valid_symbols) {
  // ...

  size_t from_top = number_of_blocks_from_top(s, DIV, colons);

  // We could check if either DIV_MARKER_BEGIN or DIV_MARKER_END are valid here,
  // but as the grammar is set up they're both always valid at the same time.
  if (from_top > 0) {
    // Close the current div, and all blocks above.
  } else {
    // No matching div to close, let's open one.
    lexer->mark_end(lexer);
    push_block(s, DIV, colons);
    lexer->result_symbol = DIV_MARKER_BEGIN;
    return true;
  }
}

But we have a problem: when we want to close the div, we want to be able to output multiple tokens.

For example, with this type of input:

:::
:::::
:::::::
text
:::

We’ll have a stack of 3 divs when we see the closing ::: marker:

7 (top)
5
3 (the one we want to close)

In the code above, from_top will be 3 and we need to output 4 tokens: 3 BLOCK_CLOSE (one for each div) and 1 DIV_MARKER_END (for the last :::). But the scanner can only output a single token at a time.

The way I solved this is by introducing more state to the Scanner. Specifically, I introduced a blocks_to_close variable that we’ll use to output BLOCK_CLOSE, and some variables to output (and consume) the DIV_MARKER_END.

typedef struct {
  Array(Block *) * open_blocks;

  // How many BLOCK_CLOSE we should output right now?
  uint8_t blocks_to_close;

  // Delayed output of a token.
  TokenType delayed_token;
  // Allows us to consume the width of a delayed token.
  uint8_t delayed_token_width;
} Scanner;

We need to remember to update the create and serialize functions too.

Serialize:

buffer[size++] = (char)s->blocks_to_close;
buffer[size++] = (char)s->delayed_token;
buffer[size++] = (char)s->delayed_token_width;

Deserialize:

s->blocks_to_close = (uint8_t)buffer[size++];
s->delayed_token = (TokenType)buffer[size++];
s->delayed_token_width = (uint8_t)buffer[size++];

We’ll use IGNORED as the unused token, so we’ll need to reset it when we create the scanner:

s->blocks_to_close = 0;
s->delayed_token = IGNORED;

Now when we scan we should first check blocks_to_close and then delayed_token, before we scan other things:

bool tree_sitter_sdjot_external_scanner_scan(void *payload, TSLexer *lexer,
                                             const bool *valid_symbols) {
  Scanner *s = (Scanner *)payload;

  if (valid_symbols[BLOCK_CLOSE] && handle_blocks_to_close(s, lexer)) {
    return true;
  }

  if (output_delayed_token(s, lexer, valid_symbols)) {
    return true;
  }

  // Scan the other stuff
}

When we see blocks_to_close > 0, we should output a BLOCK_CLOSE and remove the top block (with some sanity checks for good measure):

static void remove_block(Scanner *s) {
  if (s->open_blocks->size > 0) {
    ts_free(array_pop(s->open_blocks));
    if (s->blocks_to_close > 0) {
      --s->blocks_to_close;
    }
  }
}

static bool handle_blocks_to_close(Scanner *s, TSLexer *lexer) {
  if (s->open_blocks->size == 0) {
    return false;
  }

  // If we reach eof with open blocks, we should close them all.
  if (lexer->eof(lexer) || s->blocks_to_close > 0) {
    lexer->result_symbol = BLOCK_CLOSE;
    remove_block(s);
    return true;
  }
  return false;
}

With this we can output multiple BLOCK_CLOSE, and now to handle delayed tokens:

static bool output_delayed_token(Scanner *s, TSLexer *lexer,
                          const bool *valid_symbols) {
  if (s->delayed_token == IGNORED || !valid_symbols[s->delayed_token]) {
    return false;
  }

  lexer->result_symbol = s->delayed_token;
  s->delayed_token = IGNORED;
  // With `delayed_token_width` we can consume the ending `:::`, for example.
  while (s->delayed_token_width--) {
    lexer->advance(lexer, false);
  }
  lexer->mark_end(lexer);
  return true;
}

Another way to design this is to have a stack of delayed tokens and then just pop that. It’s certainly more powerful, I just happened to choose this way when I was playing around with it because it’s more explicit and it felt a little easier to follow what was happening.

Either way, we can now implement the div end handling. In parse_div:

size_t from_top = number_of_blocks_from_top(s, DIV, colons);

if (from_top > 0) {
  // Found a div we should close.
  close_blocks_with_final_token(s, lexer, from_top, DIV_MARKER_END, colons);
  return true;
} else {
  lexer->mark_end(lexer);
  push_block(s, DIV, colons);
  lexer->result_symbol = DIV_MARKER_BEGIN;
  return true;
}

close_blocks_with_final_token is a general helper that sets up the number of blocks to close and the final token:

static void close_blocks_with_final_token(Scanner *s, TSLexer *lexer,
                                          size_t count, TokenType final,
                                          uint8_t final_token_width) {
  remove_block(s);
  s->blocks_to_close = s->blocks_to_close + count - 1;
  lexer->result_symbol = BLOCK_CLOSE;
  s->delayed_token = final;
  s->delayed_token_width = final_token_width;
}

Now we can finally try to close divs:

:::::
:::
:::::::
Divception
:::

$ tree-sitter parse example-file
(document [0, 0] - [6, 0]
  (div [0, 0] - [6, 0]
    (div_marker [0, 0] - [0, 5])
    (div [1, 0] - [4, 3]
      (div_marker [1, 0] - [1, 3])
      (div [2, 0] - [4, 0]
        (div_marker [2, 0] - [2, 7])
        (paragraph [3, 0] - [4, 0]))
      (div_marker [4, 0] - [4, 3]))))

We can see that it parses without error, the last marker closes the second div correctly, and the last marker captures the final :::.

While I’m jumping to a working implementation directly in this post, when I first did this that was of course not the case. I found the -d argument useful to see what characters are consumed and what token is output in each step.

Here’s a part of the output (when scanning the final :::), with some comments to point out some interesting things:

$ tree-sitter parse example-file -d
...
process version:0, version_count:1, state:34, row:4, col:0
lex_external state:4, row:4, column:0
  consume character:':'                         // Scan `:::`
  consume character:':'
  consume character:':'
lexed_lookahead sym:_close_paragraph, size:0    // Output _close_paragraph
reduce sym:paragraph_repeat1, child_count:2
shift state:17
process version:0, version_count:1, state:17, row:4, col:0
lex_external state:3, row:4, column:0           // Still on first `:`
  consume character:':'                         // Scan `:::` again
  consume character:':'
  consume character:':'
lexed_lookahead sym:_block_close, size:0        // Close div with _block_close
reduce sym:paragraph, child_count:2
shift state:12
process version:0, version_count:1, state:12, row:4, col:0
lex_external state:5, row:4, column:0           // Still on first `:`
lexed_lookahead sym:_block_close, size:0        // Close second div with _block_close
reduce sym:div, child_count:4
shift state:12
process version:0, version_count:1, state:12, row:4, col:0
lex_external state:5, row:4, column:0           // Still on first `:`
  consume character:':'                         // Consume `:::`
  consume character:':'
  consume character:':'
lexed_lookahead sym:div_marker, size:3          // div_marker is size 3, marks `:::`
shift state:23

While the output seems confusing, when you know what to look for it’s very useful. I’ve found that a deliberate process, where I look at a single character at a time, helps me get through the problems I’ve encountered so far.

Handling conflicts

Our grammar works pretty well, but there are issues you might want to fix. One issue, that took much longer to figure out than I care to admit, is adding a fallback to text when a markup rule doesn’t match.

A simple example for our grammar is a single underscore in a paragraph:

a_b

I’d assume this would produce a paragraph with text, but instead we get an error:

$ tree-sitter parse example-file
(document [0, 0] - [2, 0]
  (ERROR [0, 0] - [0, 3]))

This is weird, because one of the main selling points of Tree-sitter is the GLR algorithm, which should explore the different interpretations to find something that succeeds. But for some reason, it doesn’t trigger for us.

Let’s take a look. These are the relevant lines from the grammar:

_inline: ($) => repeat1(choice($.emphasis, $._text)),
emphasis: ($) => prec.left(seq("_", $._inline, "_")),
_text: (_) => /[^\n]/,

When we try to match a _ then the grammar can match either emphasis or _text because _ matches both "_" and /[^\n]/. The issue seems to be that Tree-sitter doesn’t recognize this as a conflict.

If we instead add a fallback with a _ string then Tree-sitter will treat it as a conflict:

_inline: ($) => repeat1(choice($.emphasis, $._text, $._fallback)),
emphasis: ($) => prec.left(seq("_", $._inline, "_")),
// prec.dynamic() is used during conflict resolution to choose which
// branch to choose if multiple succeed.
_fallback: (_) => prec.dynamic(-100, "_"),
_text: (_) => /[^\n]/,

And when we call tree-sitter generate we’re made aware of the conflict:

$ tree-sitter generate
Unresolved conflict for symbol sequence:

  '_'  •  '_'  …

Possible interpretations:

  1:  (_fallback  '_')  •  '_'  …
  2:  (emphasis  '_'  •  _inline  '_')  (precedence: 0, associativity: Left)

Possible resolutions:

  1:  Specify a higher precedence in `emphasis` than in the other rules.
  2:  Specify a higher precedence in `_fallback` than in the other rules.
  3:  Specify a left or right associativity in `_fallback`
  4:  Add a conflict for these rules: `emphasis`, `_fallback`

What we want to do is mark them as a conflict that’s supposed to exist in the grammar using the conflicts field:

conflicts: ($) => [[$.emphasis, $._fallback]],

And now we can parse paragraphs containing only a single _ without errors.

So it seems like Tree-Sitter doesn’t recognize a conflict between a string and a regex. Another gotcha is that it doesn’t seem like you can trigger the GLR algorithm with a token returned by an external scanner, because the external scanner overrules Tree-sitter’s lexing behavior.

Some tests

Using tree-sitter parse example-file (with or without the -d or -D flags, try them if you haven’t) is fine for experimental tests, but we really should add the different test cases as proper unit tests. Tree-sitter has a built-in test harness for this purpose.

Let’s add the very first test case to test/corpus/syntax.txt:

===============================================================================
Parsing goal
===============================================================================
This is a
multiline _paragraph_

:::
This is a paragraph inside a div
:::

```gleam
let x = 2;
```

-------------------------------------------------------------------------------

(document
  (paragraph (emphasis))
  (div
    (div_marker)
    (paragraph)
    (div_marker))
  (code_block
    (code_block_marker)
    (language)
    (code)
    (code_block_marker)))

And run it:

$ tree-sitter test
  syntax:
    ✓ Parsing goal

Yay!

We should add (a lot) more tests here, but I won’t bother writing them out in this already too long blog post.

Using tree-sitter for something useful

I like a theoretical excursion as much as the next nerd, but I started looking at Tree-sitter because I wanted to do something with the Grammar, not just play around with it all day. Let’s end the post by seeing some things we can use it for.

Syntax highlighting

Syntax highlighting is made using queries from the highlights.scm file. It’s common to have it placed in the src directory in the same repository as the grammar, but it’s not required.

Here’s an example src/highlights.scm file that highlights the different elements of our markup:

(div_marker) @punctuation.delimiter
(code_block_marker) @punctuation.delimiter

(emphasis "_" @punctuation.delimiter) @markup.italic
(language) @tag.attribute

(code_block) @markup.raw
(paragraph) @markup

What colors to choose is a bit arbitrary, these works well enough I suppose.

See the documentation for more details on how the queries and highlighting works.

Language injection

One big question I had when starting writing my grammar was how to mix multiple parsers in the same document, to for example highlight code blocks using the specified language:

```gleam
let x = 2;
```

Turns out, this is quite straightforward.

With the initial grammar, the code block parses into:

(code_block
  (code_block_marker)
  (language)
  (code)
  (code_block_marker)))

Which we’ll use in src/injections.scm to specify that we want to parse (code) using the grammar specified in (language):

(code_block
  (language) @injection.language
  (code) @injection.content)

When we’ll embed the grammar into a program with highlighting support, it will delegate the text inside the code block to the injected language.

Using our grammar with Neovim

I typically install Tree-sitter grammars in Neovim using :TSInstall provided by nvim-treesitter. But you can install local Tree-sitter grammars as well:

local parser_config = require("nvim-treesitter.parsers").get_parser_configs()
parser_config.sdjot = {
    install_info = {
        -- Change this url to your grammar
        url = "~/code/tree-sitter-sdjot",
        -- If you use an external scanner it needs to be included here
        files = { "src/parser.c", "src/scanner.c" },
        generate_reqires_npm = false,
        requires_generate_from_grammar = false,
    },
    -- The filetype you want it registered as
    filetype = "sdjot",
}

Just make sure you have a "tree-sitter" section in the grammar’s package.json:

"tree-sitter": [
  {
    "scope": "source.sdjot",
    "file-types": [
      "sdj"
    ],
    "injection-regex": "sdjot",
    "highlights": [
      "queries/highlights.scm"
    ]
  }
],

With this you can do :TSInstall sjdot and :TSUpdate sdjot when you make changes.

:TSInstall doesn’t install queries automatically though. What I did was symlink the queries directory into Neovims config directory:

ln -s ~/code/tree-sitter-sdjot/queries ~/.config/nvim/queries/sdjot

:TSPlaygroundToggle is very useful for debugging the grammar, and :Inspect shows you the highlight groups under your cursor. It might be good to check out :help treesitter-highlight-groups if you want to play with your theme, as the theme needs to support the highlight groups we use for coloring to appear.

You also need to have the Tree-sitter grammar for the injected language installed, if you want to highlight the contents of code blocks.

Jumping and selecting with textobjects

I mentioned nvim-treesitter-textobjects as a good example of why Tree-sitter is about more than syntax highlighting.

To make use of our grammar we can add some capture groups to src/textobjects.scm. For example we can register our code blocks as “functions”:

(code_block (code) @function.inner) @function.outer

The objects are arbitrary, but @function is one of the standard objects so I guess it might make sense.

With the symlink ready, you need to register keymaps with nvim-treesitter-textobjects and you’re good to go. I have it setup so I can jump between @function.outer with [f and ]f, and selections with af and if.

This means that with the above textobject definition I can for example jump to the next code block with ]f and then remove all the code inside with cif to end up in insert mode, ready to replace it with some new code.

Although this example is a bit arbitrary, this general functionality is extremely useful for programming languages. For a markup language like Djot, jumping between headings might be a more relevant use-case.

Embedding the grammar with Rust

One of the selling points of Tree-sitter is that you should be able to embed it in any application. Such as this blog!

I’ve been wanting to add Tree-sitter powered highlighting to my blog for a while, and now I have an excuse to do just that.

This blog is a static site generator written in Rust, and tree-sitter-highlight looks like a suitable library to try. Let’s add it to our Cargo.toml:

[dependencies]
tree-sitter-highlight = "^0.20.0"
tree-sitter-sdjot = { git = "https://codeberg.org/treeman/tree-sitter-sdjot.git" }

I use a slightly older version because some other grammars I want depend on the older version, and it’s a big pain but they all need to use a matching version. Bleh.

According to the docs we first need to setup a HighlightConfiguration. I used lazy_static! to create a global map with configurations to be used by any parallel rendering on the blog. It’s not the most beautiful code I’ve written, but it gets the job done:

// All highlights needs to be listed explicitly.
static HIGHLIGHT_NAMES: &[&str] = &[
    // I have +100 entries here, this is for sdjot.
   "markup",
   "markup.italic",
   "markup.raw",
   "punctuation.delimiter",
   "tag.attribute",
];

lazy_static! {
    static ref CONFIGS: HashMap<String, HighlightConfiguration> = init_configurations();
}

fn init_configurations() -> HashMap<String, HighlightConfiguration> {
    [
        // I have more languages here
        (
            "sdjot",
            HighlightConfiguration::new(
                tree_sitter_sdjot::language(),
                tree_sitter_sdjot::HIGHLIGHTS_QUERY,
                tree_sitter_sdjot::INJECTIONS_QUERY,
                "",
            )
            .unwrap(),
        ),
    ]
    .into_iter()
    .map(|(name, mut config)| {
        config.configure(&HIGHLIGHT_NAMES);
        (name.to_string(), config)
    })
    .collect()
}

Notice how all highlight names we’re interested in have to be explicitly specified. This is a big pain, especially if you’re going to include many larger grammars.

The names can be filtered for with ripgrep with something like this:

rg "@[\w.]+" -INo --trim highlights.scm | sort | uniq

I already have syntax highlighting via syntect, so I wrap the highlighters in their own types:

enum HighlighterType<'a> {
    Syntect(SyntectHighlighter<'a>),
    Treesitter(TreesitterHighlighter<'a>),
}

pub struct TreesitterHighlighter<'a> {
    config: &'a HighlightConfiguration,
}

impl<'a> TreesitterHighlighter<'a> {
    pub fn find(lang_id: &str) -> Option<Self> {
        CONFIGS.get(lang_id).map(|config| Self { config })
    }
}

The interesting part is of course the highlight method, that takes a string of code and applies syntax highlighting on it:

impl<'a> TreesitterHighlighter<'a> {
    pub fn highlight(&self, code: &str) -> Result<String> {
        let mut highlighter = Highlighter::new();

        let highlights = highlighter.highlight(self.config, code.as_bytes(), None, |lang| {
            // This callback handles language injection
            // and should return a `HighlightConfiguration`.
            let res = CONFIGS.get(lang);
            if !res.is_some() {
                warn!("Couldn't find treesitter grammar for `{lang}` to inject");
            }
            res
        })?;

        let mut renderer = HtmlRenderer::new();
        renderer.render(highlights, code.as_bytes(), &|attr| {
            // This should return a `&'a [u8]` with the same lifetime as `code`.
        })?;
        let res = renderer.lines().join("");
        Ok(res)
    }
}

I want to point out the API in HtmlRenderer, where we stumble upon a very annoying problem: what should we return from the callback, and how should we do that?

What the callback does is inject the return value into the span element, like this:

<span CALLBACK_RESULT >highlight</span>

So we’d like to return something like "class=\"markup italic\"", using attr which is only a usize into HIGHLIGHT_NAMES:

renderer.render(highlights, code.as_bytes(), &|attr| {
    format!(r#"class="{}""#, HIGHLIGHT_NAMES[attr.0].replace(".", " ")).as_bytes()
})?;

Because we return a slice of bytes into a string that’s created inside the callback, of course the Rust compiler will be mad at us:

error[E0515]: cannot return value referencing temporary value
  --> src/markup/syntax_highlight/treesitter_highlighter.rs:33:13
   |
33 |             format!(r#"class="{}""#, HIGHLIGHT_NAMES[attr.0].replace(".", " ")).as_bytes()
   |             -------------------------------------------------------------------^^^^^^^^^^^
   |             |
   |             returns a value referencing data owned by the current function
   |             temporary value created here

How to dynamically create a string from inside the callback… That outlives the callback itself?

Not easily I tell you.

It would be so much easier if the callback would return a Cow<str> or something. I wonder how the designers of the API expects it to be used? This surely isn’t a very unique requirement, to wrap the attribute in a class?

Oh well. One way to solve this is to store the generated strings in a container that outlives the callback, and reference that (yeah it’s a Fn callback, but there are hacky ways around that). Or you could, you know, write your own HtmlRenderer.

Or you could pre-generate the classes and reference them:

lazy_static! {
    static ref CLASSES: Vec<String> = HIGHLIGHT_NAMES
        .iter()
        .map(|name| format!(r#"class="{}""#, name.replace(".", " ")))
        .collect();
}

renderer.render(highlights, code.as_bytes(), &|attr| {
    CLASSES[attr.0].as_bytes()
})?;

This should be the fastest option and is the one I currently use… But speed isn’t a bottleneck here and I’d rather just return a String with format! and be done with it.

With this I’ve integrated Tree-sitter based syntax highlighting into my blog!

```
With great powers comes great responsibility
```

I could start moving the various languages over from Syntect to Tree-sitter… But I won’t.

There are some issues:

You need a compatible version of tree-sitter for all grammars.

The more grammars you add the more painful the upgrade path becomes.
Syntect gives better highlighting for some languages (like Rust and C).

Neovim has their own highlighter implementation and has made tweaks to certain grammars and gets much nicer highlighting than I got out of the box.

Integrating that code into my site generator is probably possible, but not a rabbit hole I want to jump into right now.
The highlighter library feels a bit immature.

A newer version broke the highlight groups I got from some grammars and I don’t see any support for how to add a language specific class to span for injected languages.

Because of these issues I’ll evaluate what highlighter to use on a case-by-case basis, with Syntect as the default choice.

Within edge-cases lies complexity

If you’ve read the post to the end, congratulations. You made it!

I don’t claim to be an expert at grammars or Tree-sitter, and I’m sure there are plenty of things that can be improved with the way the grammar is made. But I hope it can be helpful as a starting point if you’re curious on how to write a Tree-sitter grammar of your own.

See the tree-sitter-djot repo for how I developed the grammar further to support the full Djot specification (but remember, I’m not an expert).

Just one word of advice before you go. Writing a grammar for simple rules is pretty easy, but in the real world things can get messy quickly. This is especially true if you need to juggle multiple conflicting rules in the external scanner—keeping a sane structure is challenging.

(Even in our simple grammar there are bugs, but I don’t care to fix them.)

The night is dark and full of terrors

George R.R. Martin

Let's build a VORON: Wrap-up

2026-01-29T10:44:59+00:00

It’s finally done™. I’ve built a VORON that prints reliably and I’ve modded it enough to be able to leave it alone for a while, so I think it’s time to wrap up this build series with a little retrospective.

Building the printer was really fun and rewarding

I’ve always seen myself as a software person instead of a hardware person. But I must admit, assembling the printer was a very fun and rewarding experience.

Seeing how you go from bags of bits and pieces to a fully functional printer, and knowing that I—someone clueless about hardware—put everything together, is an awesome feeling.

And to then mod the printer—to print out parts to modify and enhance the printer—was also very cool and one of the best parts of this project. I think I enjoyed the building experience so much that I was seeking out more mods just to extend that sensation.

There’s so much to learn

Even though I’ve tried to include as much details as possible in this blog series, there are still many things I left out that you need to learn if you’re new to 3D printing like I am. For example:

Klipper & G-code configuration
Slicer management and the thousands of settings
Filament selection, stuck filament, wet filament, filament tuning…

You can absolutely start from zero with a VORON like I did, just realize that there’s a lot to learn, and building the printer is only the beginning of the journey.

Take it slow and ask for help, and I’m sure you could do it too.

Some modding is required

Okay, you can use the printer as-is. But in my mind some modding is required to get the most out of it:

HEPA filter seems like a must.

Sure, there are crazy people who even print ABS in their bedroom without an enclosure—but come on. Your health is the most important thing, you should take better care of it.
A smart filament sensor saves you so much grief.

There are a lot of other great mods too, but I concede they’re not required. If you’re building a Trident I’d at least consider these mods as well:

Removable top panel.
Some sort of camera (maybe not the Angry CAM).
RockNRoll (or inverted electronics, but maybe plan for that from the start).

(Modding is also one of the most fun parts, feel free to go nuts!)

Issues with the kit

Overall, the printer and kit was good and I haven’t had many issues with it. I did however have two larger issues:

The printer was loud.
The POM nuts wore out.

This isn’t a knock on the printer design (I think). Maybe it was an issue with some of the parts I received in the LDO Trident kit, but I don’t know. It could also be plain old user error.

Future plans

One might think that the printer is complete and that I won’t touch it anymore, but nooo. Oh no, I’ve a bunch of large mods I want to do with the printer:

Replace the camera with a better one (maybe also a nozzle camera?).
Remove drag chains and go umbilical.
Complete the purge bucket mod.
Try the inverted electronics mod.
Replace Stealthburner with the Xol toolhead for better PLA cooling.
Multimaterial with the Enraged Rabbit Carrot Feeder.

But before that I’ve identified a fatal flaw: I only have a single printer.

What should I do if I find that I’m missing a printed part when I’ve disassembled the printer to mod it? What if I break something? And if I’m doing a long mod the printer will be down and I can’t print things for any other project.

This clearly isn’t a sustainable solution—I need a second printer.

And isn’t that the best compliment one can give? That you haven’t even finished it yet, but you’re already pining for another one?

Let's build a VORON: Major failure

2026-01-29T10:44:28+00:00

The left POM nut got ground down, making the bed fall down.

After 600 hours, the printer met it’s first major failure. I know I earlier described how the extruder starter skipping in a big way, but that was just some filament getting stuck in the extruder. This time a part physically broke down.

What happened was that the rod on one of the Z-motors started to grind down the POM nut that holds up the bed:

It did this so much that the threads got ground down, making the bed fall down.

The POM nuts are considered expendable items, but a failure after only 600 hours “shouldn’t happen”. But here we are.

Potential issues

I’ve tried asking around, and I’ve rounded up a couple of potential culprits:

Tightening the nuts holding the POM too hard.
A gap between the motor mount and the front extrusion.

I found is a gap between the motor mount and the front extrusion.

This should mean that the rod would be tilting backwards at a slight angle, which might mean that the rod would catch against the nut more in that direction, increasing the attrition on the nut.

The theory meshes well with the unevenly ground threads, especially since I mostly print things at a similar Z-height (as you can see in the first photo where the rod has collected a lot of flakes).

The threads aren’t ground down evenly. One side is almost completely flat, while the threads are clearly visible on the other.
I used the wrong grease for the rods (POM is self-lubricating, maybe I don’t even need grease?).
Dust/dirt stuck in the nut or on the leadscrew.
An issue with the LDO kit.

Someone in the VORON Discord said that this is a well-known problem with LDO Trident kits (sigh, I chose the expensive option to avoid problems like these…).

The Z-motor I have is LDO-42STH40-1684CL300T. I don’t know what kind of POM nut I have (it’s black and it came with the LDO kit…)

Solutions/workarounds

I don’t know the actual cause of this, but I’ve done my best to address the potential issues described above. I’ve loosened the nuts on the POM nut a bit, I’ve adjusted the motor mount, and I’ve tried to clean the leadscrews (with a toothpick of all things). In the future I’ll try to avoid the grease as well.

I complained to 3DJake where I bought the kit, and they’re sending me a replacement leadscrew including a POM nut. It’s shipping from China so the wait is very long. In the meantime I bought a few replacement leadscrew nuts (TR8*4, not the TR8*2).

Replacing the nuts weren’t that hard, but I hope it’ll take more than 600 hours until the next major issue.

(I’ve already started seeing dust on the leadscrew… I’ll probably replace it when the replacement arrives and hope it’ll get better.)

Let's build a VORON: Noise

2026-01-29T10:44:42+00:00

The build is going well and the printer is printing tons of random stuff and I’m generally in awe of how cool the printer is.

But there’s one thing that sucks: it’s damn loud.

I knew that it wouldn’t be silent, but I wasn’t prepared for this kind of noise.

Silent controller fans

The very first mod I made (even before my first print) was to replace the LOUD skirt fans with silent Noctua FN-A6x25. When I say the fans were loud, I mean that they were incredibly damn loud. I don’t see how anyone could be near the printer with fans this loud for a prolonged period of time.

Maybe I’m just sensitive, but I digress.

You can run PWM fans, but I didn’t see the point so I went with the simple 3-pin variant. The fans will fit as they are and I only made some small tweaks:

Used the 12V selection jumper for the fan output on the Octopus.
Converted the 3-pin cable to a 2-pin JST connector, and used the existing fan PCB to split the Octopus output. (You can ignore the yellow RPM speed signal cable.)

The connection looks like this:

The fans are connected to the PCB splitter using low-noise adapters. It’s important to move the jumper for the PCB FAN connector.

I altered the extension cables that came with the kit because it leaves the fans intact and I can control the speed using the included low-noise adapters (I used the ultra-low-noise adapters). I didn’t have a compatible 3-pin splitter for the fans so I used the PCB I had on hand.

I also took the opportunity to cleanup the wiring and place the fans on the other side, closer to the Raspberry Pi:

The wiring looks pretty neat. I hope I don’t have to mess with it in a long time.

You could do something smart with the fan management, but I no longer hear the fans so I just leave them on all the time. This is how I set that up in printer.cfg:

[fan_generic controller_fan]
## Controller fan - FAN2
pin: PD12
kick_start_time: 0.5
max_power: 1.0

# Set the controller fan to be on from startup.
# Speed is controlled by noctua low-noise adapter.
[delayed_gcode controller_fan_boot]
initial_duration: 1.0
gcode:
    SET_FAN_SPEED FAN=controller_fan SPEED=1.0

Nevermore fans

Another annoyingly loud part was the fans on the Nevermore filter. I could try to reduce the fan speeds, but that would also reduce the effectiveness of the filtering which I’m reluctant to do.

Then I found an issue discussing that the plenum lid makes the fans loud and weak because it restricts the airflow. I can only confirm that it made a noticeable difference. It’s by no means quiet like the Noctua fans, but now it’s similar in noise level to the hotend and partcooling fans.

It’s ugly because the prints don’t match, but it’s much quieter (and more effective).

Loud stepper noise

Another really annoying noise was the steppers.

The first problem was them being noisy while idle. This was solved by adding stealthchop:

stealthchop_treshold: 999999

But it was still really loud when moving, especially the xy steppers were super annoying.

This seems to be a common issue with some 0.9° steppers and I tried manage this with various config settings:

Lower run_current from 0.8 to 0.6 for x- and y-stepper motors.

This drastically lowered noise during movement. It’s not silent and it’s still too loud, but it really helped.

Some have suggested that raising run_current might help as well, but for me that just made things worse.
Increased microsteps.

microsteps: 128 on xy

As long as the MCU can handle it there should be no downsides(?), and it does help with lowering noise.
I tried interpolate: true, but I didn’t notice any improvements.

While things mostly weren’t that bad anymore, at certain speeds and certain angles the noise was still way too jarring for me to leave it alone. And it wasn’t just too high speeds, sometimes decreasing the speed made it worse!

77dB is loud! This was from long diagonal movement during (non-first layer) solid infill, which was one of the movements that generated the most noise.

So I gave in and ordered two Wantai 42BYGHM810 steppers from Aliexpress that according to the linked discussion should be much quieter. (1.8° degree steppers should generally be much better too.)

After waiting quite a while, the motor I got had the correct label of 42BYGHM810 but marked as 1.8°, despite being sold as a 0.9°. The joy of Aliexpress sometimes…

But it does seem that it is a 0.9° motor, and it was just badly labeled.

Swapping the motors was very easy, just loosen the belts a bit and I could pull them out. With some Molex Micro-Fit 3.0 4-Pin connectors (and some crimping…) I got it to run with a run_current: 1.1 and it’s so much quieter!

The motors run at 52dB in the same conditions as the LDO motors, which is really quiet. I can’t understate how large a 20dB difference truly is. The 63dB peak was from the filament getting pulled from the spool.

Is it silent?

Of course, the printer isn’t nearly as quiet as my water cooled computer—how could it? But these changes have made the printer much quieter, which is important to me as I’m quite sensitive to noise.

It’s still a bit noisy—too much if I want to sit in silence and ponder a difficult problem— but it’s silent enough so I can have it running in the background while I’m working. I’ll probably pause it if I’m in a call, and I won’t have it running all the time during work hours. (The printer is in my office, right behind me.)

Let's build a VORON: More mods

2026-04-27T15:26:20+00:00

The printer is done, but I feel one of the best part of a VORON printer is the ability to modify and personalize it. There a tons of mods you can do, and while I’ve done a few there are lots more that I’d like to do some day.

It’s a wonderful feeling to augment the printer with parts made by the printer itself.

RockNRoll

Flipping over the printer to access the electronics apartment is a huge pain. There’s a very cool inverted electronics bay mod for Trident printers, but it’s a tall ask for me to redo all the wiring at this point.

But then I found the simple RockNRoll mod that allows you to easily tilt the printer. Just having the rockers doesn’t work as the center of gravity is too high for the Trident, but with these additional stilts it works great.

Removable panels

Having to screw and unscrew the panels when modding or messing around with the toolhead got old fast. Therefore I made the panels easily removable by using magnets and snap latches.

The top is completely magnetic using the Magnetic panels with Magnet Inserts mod and is very easy to remove and replace.

Installation of the corner magnets.

I played around with the amazing snap latches mod to hold the panels together:

The latch closes with a very satisfying thud.

But they’re a bit cumbersome to lock and unlock, so I compromised and used the latches in the middle of the side panels and used magnets for the corners:

I also made the bottom panel magnetic using the bottom panel mag clip mod:

Necessary? No—but it feels nice.

Clicky-clack door

I really didn’t like the stock doors on the printer. I was planning to use the same magnetic and/or latch system for the front door, but I realized it would be very bothersome compared to a door you can swing open.

Luckily I found the Clicky-Clack Fridge Door mod that replaces the split panels with a full panel door and that can swing open, provides a better seal than the stock doors, and can easily be removed. It may not win any beauty awards, but it sure is functional.

Angry cam

The mod I most appreciate is probably having an integrated camera. It’s great to be able to just glance at my phone to see how the print is going, instead of having to go down to the basement to check.

I used the Angry CAM USB mod to mount a small camera module in the front of the printer, above the doors. The camera itself showed up in Mainsail and to my relief it worked immediately. To configure resolution you can alter crowsnest.conf like so:

[cam 1]
mode: ustreamer                         # ustreamer - Provides mjpg and snapshots. (All devices)
resolution: 2592x1944                   # widthxheight format
max_fps: 15                             # If Hardware Supports this it will be forced, otherwise ignored/coerced.

To see what resolution and fps the camera supports, you can take a look in ~/printer_data/logs/crowsnest.log.

I used the MJPEG IP Camera integration to get the feed into Home Assistant, using http://192.168.1.32/webcam/?action=stream as the URL and made a quick dashboard for the printer:

Can you smell what the rock is cooking?!

I should probably rework this and all other Home Assistant dashboards one day…

The mount works well, but the camera is far from perfect. It’s good enough for checking in on the print, but a more clear view would’ve been nice. The focus isn’t working well, the colors are off, and I don’t see the whole build plate. Worse, the toolhead often covers up the print so I can’t see if it’s still printing well.

I won’t do anything about it right now, but in the future I’ll probably try to replace it with something else.

Smart filament sensor

Bed adhesion and first layer problems are annoying, but they can be mitigated by watching the first layer go down and if it goes badly you don’t lose that much time.

Something much more annoying is when the filament tangles. According to the internet it “should never happen”, but it has happened with four different spools from different manufacturers and it sucks when the print fails multiple hours in.

See this? This damned spool ruined 4 prints in a row for me. It’s not a real knot, but it’s tangled hard enough that the extruder couldn’t pull it free, and it started to grind down the filament instead of extruding it.

Fed up, I ordered Bigtreetech’s Smart Filament Sensor V2.0 that can detect both running out of filament and these “knotted” spools.

There are some nice mounts for it, but finding a good mounting point was difficult. I ended up moving the spool to the side of the printer, and routing the cable through the back panel:

One difficulty was that the wire was just a tad too short. I got it to reach, but just barely. I couldn’t route the cables to make the underside pretty… But meh.

The Octopus has dedicated ports for the two BTT connectors.

To setup Klipper I used this code:

[filament_switch_sensor filament_sensor_switch]
switch_pin: ^PG12
pause_on_runout: True
insert_gcode:
    M117 Insert detected
runout_gcode:
    M117 Runout detected
    SET_DISPLAY_TEXT MSG="Runout detected!"

[filament_motion_sensor filament_sensor_motion]
switch_pin: ^PG13
detection_length: 10 # ellis recommends to start at 10mm, could maybe adjust this?
extruder: extruder
pause_on_runout: True
insert_gcode:
    M117 Insert detected
runout_gcode:
    M117 Runout detected
    SET_DISPLAY_TEXT MSG="Runout detected!"

You also need proper PAUSE/RESUME macros. I just copied the macros from Ellis’ print tuning guide.

I tested it by holding the filament during the print, trying to simulate a knot in the filament. This worked, but damn was it HARD. The extruder really does have force behind it.

Since installing the sensor it has already saved multiple prints. For sure a huge quality-of-life improvement, and feels like a must-have.

Flex plate stops

Aligning the flex plate isn’t too much of a pain, but adding some flex plate stops makes the process easier.

To fit it at the back I removed the now unused z-endstop (I use Tap instead).

Gridfinity mounts

I’ve been slowly easing into Gridfinity—a free and open organization system. So naturally I wanted to add some some holders to the printer.

I used a combination of top and bottom holders.

Meshed panels

Adding meshes for the panels might be one of the prettiest mods you can do—and I think it’s very pretty—but that’s not why I did it. I added it as a safety measure against my kids (or me) inserting something like a screwdriver inside the electronics while the printer is running.

I didn’t do any fancy filament swapping prints, I just printed the meshes and glued them onto the backs of the panels. It works.

Galileo 2

I replaced the Clockwork 2 extruder with the Galileo 2.

This wasn’t exactly needed, I just thought it would be fun as building the Clockwork was one of the most interesting parts of the build, and this planetary gears thing looked pretty interesting. And the FOMO kicked in as I was following the discussion online, with people hyping about it but not being able to find a kit. So when I happened to find one I couldn’t help myself.

I was planning to make a separate post only about the build, but the build was surprisingly very quick so I think it works if I include it in this blog post.

I was worried about the quality of my printed parts, but they fit well.

The planetary gears.

Time to shove the motor into place.

The drive gear is installed.

The only difficulty I encountered when assembling the extruder itself was to align the drive gear. It touched the printed part, and I was worried my prints came out all wrong. The manual says that you can push down the carrier shaft, but I had to disassemble it and realign it before attaching the motor. After the reassembly it luckily aligned properly.

There were no issues mounting the extruder onto Tap or into the Stealthburner either. The LDO toolhead PCB fit without having to use spacers, although closing the lid was very tight.

Galileo 2 fits well on the printed Tap.

The biggest pain point was the wiring management (yet again). The drag chain mount on the Galileo 2 is higher up than on the Clockwork 2, which meant I had to pull through more wiring to be able reach the PCB.

Opening up the drag chains to pull through more wiring.

I really don’t enjoy opening up the drag chains, it’s just a huge pain. The next time I need to mess with it, I’ll probably go Canbus or Nitehawk and get rid of the annoying chains.

I’ve seen some people complaining that they’ve lost some y-travel, but I don’t understand why. For me the range has been unchanged.

The big question is, does it print better?

It’s a difficult question, because I don’t really know. Maybe it does, but I didn’t make any test prints to really compare. But it’s not an extreme improvement like some people online made me to believe. It’s more an incremental improvement, and the Clockwork 2 would honestly be good enough for me.

I do miss the latch of the Clockwork 2, but I don’t think I’ll switch back right now. Even small improvements to extrusion quality is nice.

Purge bucket & CNC Tap

The kit comes with a steel brush and references the Decontaminator Purge Bucket & Nozzle Scrubber mod that I was quite excited for.

Unfortunately, Tap decreases the range of motion for the toolhead so that the nozzle no longer can reach back behind the bed:

This is as far back the nozzle can go. As you can see, it doesn’t reach the (now unused) z endstop, and there’s no room for a purge bucket / nozzle scrubber.

There are some things I could do:

Ditch Tap and use Klicky probe instead.
Replace the printed Tap with a CNC Tap.

The Chaoticlab CNC Voron Tap v2 should save around 4mm in the y-axis while Vitalii’s version should save around 1.4mm.
Sensorless XY homing might also give back some range.
Moving the bed is a theoretical solution, but that seems difficult to me.

I bought a Chaoticlab CNC Voron Tap, but had I known about the sensorless homing I might have tried that out first.

Installation was straightforward, I just had to be mindful of these things:

Grease the rails.
Apply threadlocker to the screws.
I had to switch the wiring in the Tap–PCB cable.
Use ~!PG15 instead of ^PG15 in the probe config.

But—and here’s the big but—it’s not compatible with LDO’s X/Y Endstop PCB board:

There’s nothing to press the X Endstop switch anymore.

To make this work I’ll have to add an X Endstop to the toolhead (there’s a dedicated mount for it), which is fine. There’s a X Endstop connector in the toolhead PCB… But I don’t see how to get that signal out from LDO’s breakout board in the electronics compartment (it takes it from the X/Y Endstop PCB).

That feels like a lot of effort… And I told myself I would not drag more wires through the drag chain, so I gave up on the mod for now. I’ll revisit this when I move to an umbilical setup, where I plan to move the X and Y endstops anyway to get rid of the drag chains.

But that’s a larger project for the future, at the moment I’m content.

Back in no time.

last words of William S. Burroughs

The eBook for 'Why Cryptocurrencies?' is now available for free

2024-06-27T07:48:59+00:00

The eBook for my book Why Cryptocurrencies? is now available for free.

It’s been almost 4 years since the web version was done, and 3 since the physical copy was available… Which can hardly be called a success.

Things happened, so let’s do a quick retrospective to, maybe, learn something.

The project is done

I’m very good at putting myself down and to focus on the negative parts to the expense of the positive.

I need to learn to take a step back and appreciate the good things I do, and even though it took a log time the book project is now completely done.

No matter how you look at it, actually finishing a large project such as self-publishing a book should be seen as a success. Sure, it took a lot longer than I wanted to wrap it up, but I finished it, and finishing a large project is an accomplishment in itself.

I’ve had this project hanging over me like a dark cloud, painfully aware that it’s almost done—and has been almost done for years—continually increasing my stress levels. But now, I can finally let it go.

Let it go, let it go
Can’t hold it back anymore
Let it go, let it go
Turn away and slam the door

Frozen

(I prefer the Swedish version of the song.)

I made it more difficult for myself than it had to be

Despite reading countless advice to “focus on content”, and to “choose a simple solution”, I added too much complexity and was a tad too ambitious.

I used a non-standard generator, with no native eBook or PDF generation support.

While generating a PDF was easy (it’s basically a copy of the PDF for the printed book), generating a nice-looking and functional EPUB took a bunch of time.
I was very particular with the typesetting and styling.

The result looks great, but styling the web version, the printed version, and then (re)style the epub took a lot of extra time.
I wanted to take payments in crypto, so before I made the eBook I made my own cryptocurrency payment processor.

The project suffered hard from ridiculous scope-creep, and it was far from “just accept a payment” (which was done the first week…). It’s also yet-another “almost finished” project I want to revisit.

In hindsight, the error is obvious. I should’ve written the book in an existing solution that would generate the website, epub, and PDF with minimal intervention from my side. Or at the very least I should’ve setup the epub and PDF generation from the start, instead of rushing the writing and leave the rest until later (leading to a bunch of extra work).

The idea was to make the eBook purchasable with an assortment of crypto—and I did have that for a while—but I really should’ve focused on finishing the eBook in a timely manner instead.

Burnout, procrastination, and losing faith

While I certainly bit off more than I could chew, I faced other challenges during the project:

I got burnt out, hard.
I’m an expert-level procrastinator.
My faith in the cryptocurrency community continued to dwindle.
We got another kid—twice! Now we have three.

I wrote a separate post about my burnout, no need to rehash the details of that unpleasant experience again here. With the burnout (and the depression that tagged along), my heavy procrastination, and the arrival of two kids, maybe the surprising thing isn’t that it took so long, but that I got anything done at all?

Procrastination is about doing the wrong thing

Wait a minute you might think; how can this person claim to procrastinate when he’s done so many other things?

It’s true that I’ve spent a lot of time to do many other things, while neglecting the book project. But to me procrastination isn’t about doing nothing, it’s about doing things with less priority.

For example, instead of finishing the book project I rewrote the blog in Rust, refactored it to use Djot instead of Markdown (despite Markdown working just fine), built a 3D printer, and spent tons of time designing my own keyboard layout…

These are really fun, cool, and even sort-of productive things. But they weren’t the things I should have prioritized, which in the logic of procrastination makes them very appealing to my brain.

I don’t know how to stop procrastinating. The best strategy I’ve found is to try to harness it by directing it towards something productive (such as exploring a new programming language), and accept the fact that progress on other project will sometimes slow down.

I still believe in the potential of crypto….

I still firmly believe that cryptocurrencies has an amazing unrealized potential—and I still stand behind the majority of my arguments in the book, where I focus on what cryptocurrencies can be useful for. In many ways I think the arguments of digital cash are even stronger today than when I started writing the book some 5 years ago.

But I severely underestimated the negative effect “fast money” had on the cryptocurrency community, and how the focus completely shifted from cryptocurrencies being used to buy things in the real world, to just rampant speculation and get-rich-schemes.

The LaserEyes Bitcoin campaign exemplifies everything I loath about crypto.

10 years ago, if you asked people what the point of Bitcoin was, they would’ve said that it’s a new form of money that you can send instantly and very cheaply to anyone in the world, without handing it over to a third-party.

But today people will point at the newly approved Bitcoin ETF, that Bitcoin has tons of institutional investments, and that it’s a “great Store of Value”. Which is all only an euphemism for speculation and a desire to get rich.

Thinking about it makes me tired and sad, and drains me of the energy and makes me want to distance myself from the space, rather than try to improve it. The point of crypto was to improve things for regular people, not this.

…

How’s that for a recommendation for my book that extols the virtues of crypto? :)

Main takeaways

If you want to finish a similar project in a reasonable amount of time, I’d say these are the biggest tips I have:

Fight complexity and scope-creep.

Focus on the content of the book—cut down everything else. Except for marketing, but how to do that competently is a riddle you’ll have to solve yourself.

If I had a setup that could generate a web version, an EPUB, and a PDF from the start the eBook would’ve been completed years ago. But now I let things come between, and time runs quickly when that happens.
Find a way to stay motivated.

I for one love to start projects, but finishing them is tough. If you find a project that you’re really passionate about then you’ll drastically increase the chance for success. And even if you do, if the project takes a long time then it can still be challenging to get the project over the finish line.

External positive feedback is also helpful, even though I believe the best motivation comes from within.

What gave me the last push was that I told myself in very stern words that I have to finish this before I can start my next project. I’ve done this multiple times with varying levels of success, but this time my brain seemed to listen.
Sometimes shit out of your control happens.

I was going to add “don’t get burnt out” as an item, but I should know that it’s not something you easily avoid.

Acceptance that it sometimes take longer is good. I try to tell myself that it’s not a disaster just because it takes a bit longer than initially planned.

How I did the layout for my self-published book

2026-04-27T10:16:42+00:00

This is a rundown of how I typeset and laid out my self-published book for the web version, the EPUB version, and the printed version.

Web page

I started by creating the book in a web format. It’s a static site generator that simply outputs HTML with some custom CSS styling to make it look pretty. I wrote a separate post on how I wrote a book with Pollen, check it out if you want more details.

As I’ve become more proficient with CSS, I would’ve used Flexbox and Grid instead of floats and other hacks. Still, I’m quite pleased with how it looks even though I’d rather not look at the implementation.

I’m absolutely no CSS or design wizard, I just spent quite some time tweaking until I ended up with something decent (I guess design is simple, but not easy).

EPUB

The initial plan was to use Pollen to generate both the web and eBook version from the same source. This is supported in Pollen by branching in the output functions, for example this emphasis function from the tutorial:

(define (emph . elements)
  (case (current-poly-target)
    [(txt) `("**" ,@elements "**")]
    [else (txexpr 'strong empty elements)]))

Unfortunately, I didn’t do this from the beginning and I wanted to create an EPUB after the book, and all the functions, had already been made.

I could of course go back and modify them all, but it was much faster to just branch the repo and modify the webpage until it produced a valid EPUB. Hardly ideal, but it actually wasn’t as bad as it may sound.

Check out the epub3 branch on Codeberg for the complete source for the EPUB.

Creating an EPUB

There are many EPUB generators out there, but those I tried didn’t produce very pretty books (in many cases the results were quite bad). But an EPUB is merely XHTML with some extra files, so it’s fairly straightforward to create one by hand.

There is an EPUB 3 specification one can reference, but I’ve always found that it’s much easier to get going by looking at examples.

For my book, this is how the file structure ended up in the EPUB:

├── META-INF
│   ├── container.xml
│   └── encryption.xml
├── OEBPS
│   ├── content.opf
│   ├── main.css
│   ├── toc.ncx
│   ├── fonts
│   │   └── ...
│   ├── images
│   │   ├── emission-rates-fallback.png
│   │   ├── emission-rates.svg
│   │   ├── generals.png
│   │   └── ...
│   ├── how_do_cryptocurrencies_work.xhtml
│   └── ...
└── mimetype

The .epub file itself is just a zip of the above, with the mimetype first in the archive:

#!/bin/bash

cd _ebook/
zip -X0 why_cryptocurrencies.epub mimetype
zip -Xur9D why_cryptocurrencies.epub *

If you want to take a closer look, you can download the EPUB for free and unzip it.

The mimetype contains the mimetype (without a trailing newline):

application/epub+zip

The entry-point to everything is the META-INF/container.xml file that simply redirects us to OEBPS/content.opf:

<?xml version="1.0"?>
<container version="1.0" xmlns="urn:oasis:names:tc:opendocument:xmlns:container">
    <rootfiles>
        <rootfile full-path="OEBPS/content.opf" media-type="application/oebps-package+xml"/>
   </rootfiles>
</container>

We don’t have to use the OEBPS/ directory, but most of the examples I looked at used it so I ran with it. Maybe it’s some kind of standard or something, I don’t know.

content.opf contains what you think it does: all the content for the book:

<?xml version="1.0" encoding="UTF-8"?>
<package xmlns="http://www.idpf.org/2007/opf" unique-identifier="pub-identifier" version="3.0" xml:lang="en">
    <metadata xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:opf="http://www.idpf.org/2007/opf">
        <!-- There are other meta fields you want to set, this is just an example -->
        <dc:title id="title">Why Cryptocurrencies?</dc:title>
        <meta refines="#title" property="title-type">main</meta>
        <!-- Sets the cover page that shows up in EPUB readers -->
        <meta name="cover" content="images-cover-front" />
        <!-- With EPUB 3 you can also create fixed layouts.
             My EPUB tries to mimic the reflowable web version,
             although you could bundle both in the same EPUB file if you wanted to. -->
        <meta property="rendition:layout">reflowable</meta>
        <meta property="rendition:flow">scrolled-doc</meta>
        ...
    </metadata>
    <manifest>
        <!-- The .ncx file is a deprecated file that EPUB 3 readers should ignore,
             but it may be included to help EPUB 2 readers understand the file.
             Instead the <spine> element is used to describe the reading order of the book.
             I won't describe the file more, if you're curious download the epub and crack it open. -->
        <item id="ncx" href="toc.ncx" media-type="application/x-dtbncx+xml" />
        <item id="style" href="main.css" media-type="text/css" />

        <!-- Every chapter in the book has its own .xhtml file. -->
        <item id="how_do_cryptocurrencies_work" href="how_do_cryptocurrencies_work.xhtml" media-type="application/xhtml+xml" />
        ...

        <!-- All images needs its own entry too. -->
        <item id="images-generals" href="images/generals.png" media-type="image/png"  />
        <!-- This is the cover reference defined earlier in the <metadata> section. -->
        <item id="images-cover-front" href="images/cover/front.png" media-type="image/png"  properties="cover-image"/>
        <!-- Svg images should specify a png fallback. -->
        <item id="images-emission-rates" href="images/emission-rates.svg" media-type="image/svg+xml" fallback="images-emission-rates-fallback" />
        <item id="images-emission-rates-fallback" href="images/emission-rates-fallback.png" media-type="image/png" />
        ...

        <!-- And the fonts needs to be specified as well. -->
        <item id="century_supra_a_regular" href="fonts/century_supra_a_regular.woff2" media-type="application/font-woff" />
        ...
    </manifest>
    <spine toc="ncx">
        <!-- The spine contains the default reading order of chapters
             (or "items", they don't have to be chapters). -->
        <itemref idref="coverpage" />
        <itemref idref="titlepage" linear="yes" properties="page-spread-left"/>
        <itemref idref="dedication" linear="yes" properties="page-spread-right"/>
        <itemref idref="acknowledgements" linear="yes" properties="page-spread-right"/>
        <itemref idref="toc"  properties="page-spread-right"/>
        <itemref idref="about_the_book" properties="page-spread-right"/>
        <itemref idref="eli5" properties="page-spread-right"/>
        ...
    </spine>
</package>

There’s also font “encryption” via encryption.xml (which is only obfuscation) that I had to use because of the license of the fonts I use, but generally it’s not needed.

And that’s basically all an EPUB is. I used a very hacky Python script to move the files into position, generate the spine, image items, and the other stuff I alluded to above.

Why did I write that in Python instead of in Racket, which the rest of the book made with? I really have no idea…

Styling

I had an incredibly frustrating experience trying to style the EPUB to match the web version, with matching spacing, typeset, sidenotes, and the rest. It felt that whatever I tried, every reader would just ignore all the styling and fall back to their own and—in my opinion—horrible appearance.

I even gave up on the eBook for a time because of it.

But then I noticed I had made an EPUB 2 instead of an EPUB 3, and with the newer version all styling worked with little modification. This of course depends on the EPUB reader, but there’s not much I can do about that:

Different Android readers (ReadEra, eBoox, and Lithium) renders the EPUB very differently. Unfortunately, the EPUB won’t look great on all readers.

Validating

With the EPUB created, you should validate it. The commonly recommended idpf validator seems to be down, I instead used epubcheck I found on github.

Turns out I had a few errors in my EPUB:

$ java -jar epubcheck.jar ~/code/why_cryptocurrencies/_ebook/why_cryptocurrencies.epub
Check finished with errors
Messages: 2 fatals / 2183 errors / 2 warnings / 0 infos

And this was after I had made a bunch of corrections. Sigh…

Fixing them was annoying and time consuming, but it wasn’t hard. Most of them were easily fixed by updating the templates and tag generation within Pollen.

Errors I ran into includes xhtml being more strict than html, so I couldn’t nest an <aside> inside a <li>, leading to a nice big refactor of my sidenote generation code.

Another error pointed out that I had to provide .png fallbacks for all .svg images. With the fish shell and inkscape you can mass convert images like so:

for file in *.svg
    inkscape -w 1024 $file --export-filename (basename $file .svg)-fallback.png
end

And then specify the fallback in content.opf as shown before.

Physical book

The initial idea was, again, to use Pollen to create the book. I wanted to use Pollen to generate Latex that could produce the PDF I wanted.

But that’s not the route I went with. Similar to how it was a big challenge to get Pollen to produce an EPUB version in conjunction to a regular HTML version, making it produce a Latex variant was a big task. In addition, making Latex reproduce my sidenote styling and placement wasn’t at all straightforward (maybe I just suck at Latex).

I instead laid out the PDF with InDesign. It required more manual tweaks that I really didn’t enjoy, but on the flip side it was very easy to make manual adjustments to get the layout just right.

XML importer

Of course, we don’t want to manually copy-paste the whole book, that would be silly. InDesign has an XML importer that we can use to import the book, and if we setup styles to automatically apply to certain elements (such as <aside> sidenotes) you get quite a lot of help.

Yes, it’s buggy and not well documented, but it’s still a life-saver.

I had to style the references manually because the importer messed them up…

Styles

To work effectively with InDesign I found that effective use of styles is a must. The most important part of laying out my book was getting sizing and spacing right, and to do that you setup styles for the different cases and apply them (mostly to paragraphs).

Lots of people love to rag on CSS, but CSS is very powerful and it’s relatively simple to for example style a list, with proper spacing before, after, and between elements and text just the way you want it. With InDesign this wasn’t nearly as straightforward, and I ended up with several styles I had to apply depending on the surrounding context:

I ended up with quite a few paragraphs related to lists. The first and last paragraph needed special handling because the spacing was slightly different in order to play nice with other styles. Then there’s “multi” that contains multiple paragraphs in one list item, nested lists, and different types of lists…

All this just to get consistent spacing for my various lists.

I think the lists look nice and are very readable.

Lots of manual tweaks

Most of the time what I did in InDesign is read through the book to make small adjustments. I adjusted sidenote placements, tweaked styles here and there, adjusted page breaks to balance pages, adjusted paragraphs, added index references… And then I did it all over again.

Yes it’s time consuming and annoying, but also weirdly therapeutic. I could satisfy my need for perfection by nudging text boxes around until the end of time.

Who needs therapy when you can lay out boxes?

Printed books have certain expectations

If you upload a book on a website, or even if you create an EPUB, you can almost do whatever you want and it’ll probably be fine. But printed books has certain expectations that should be followed.

For example how a new chapter or section should start on a new page to the right, and leave the left page blank if needed. Or how chapters and sections next to page numbers on the bottom can help you navigate a technical book such as mine. These are things you don’t really notice, unless you come across a book without them. (Fiction has other expectations because you don’t jump around when you read.)

One thing that’s easy to forget about in the internet age the index you can find at the end of many books. It’s designed to help you easily find things in the book, sort of like a curated search engine, but on paper.

A correctly structured index is invaluable. Mine at least exists.

Designing a good index is hard, because it’s not about listing all keywords in the book. It’s about anticipating the needs of the reader, so someone searching for “Bitcoin” may be redirected to the chapter How do cryptocurrencies work?, even though Bitcoin isn’t singled out in the chapter (it discuses cryptocurrencies in general).

The index also acts as a sort of overview of what topics are discussed. (Aren’t you curious why Dakota Skye is mentioned in the index?)

This seems difficult to do well—and I probably failed hard—but I tried.

What I’d do differently

If I would write a book again, I would try to do what I wanted to in the first place: generate all versions from a single source.

I wouldn’t have used Pollen. While it feels really nice to be able to inject code anywhere in your markup, having to maintain 3 different outputs with every function you write is a bit much.

Instead I’d try some kind of standard markup format with preexisting EPUB and PDF generation. I could still set it up to have custom transformations, but it would be so much easier to work with compared to programming the generation completely by myself.

Working with InDesign was actually fine, but keeping the different versions in sync was difficult, so it would still be beneficial to cut it out from the process if possible.

But I’d still want to do the layout myself. It didn’t feel difficult, I mostly enjoyed the process, and I think the result was quite good.

The boxes don’t nudge themselves you know?

Printing Hextraction for my kids

2024-06-27T07:54:09+00:00

A session of Hextraction, a 3D printed board game.

I did it. I made something actually useful with my 3D printer instead of just tinkering with it.

I printed Hextraction, a very cool 3D printed board game for my kids—and they love it.

Hextraction is a gamified marble run, where you place tiles and drop balls in order to reach the end without getting yeeted off the board. It’s kind of hard to explain it in text, so if you’re still confused just watch the video from the creator. He’s hilarious:

https://www.youtube.com/watch?v=Iqz7ZDdP25A

(The first 20 seconds should give you a good idea of what the game look likes.)

Keep it simple

While I love boardgames, I printed this game for my kids to enjoy. Because they’re still young at 6 and 3 years (our 1-year old have to wait) I had to keep the game simpler than I’d personally like.

You see, Hextraction doesn’t only use regular tiles that directs the balls, they also have special effect tiles that have special rules. For example, with the Teleport Tile you can restart your ball from another location or with the Clone Tile you’re supposed to roll another ball from that same tile. The mind boggles with cool and interesting plays with these kinds of tiles…

But they all have their own specific rules that you have to remember or read on a rules card. Having to constantly be reminded of rules isn’t really fun, and our kids can’t read Swedish let alone English yet, so unfortunately the special effect tiles must be ignored for now.

Another thing I’ve avoided are the “launcher” tiles that will launch the balls in the air, so you can try to jump over tiles or onto the goals. Although they look fun—and they would be perfect for my boys—I dislike the idea of launching balls to our 1-year old crawling on the floor.

Other than that the rules we use are very simple:

Place a tile (out of a hand of 3)
Drop a ball
Draw a new tile

And if ever 3 balls (or more) get stuck on a single tile, you’re allowed to remove one tile that the balls are touching.

(Oh, if a ball happens to bounce into a goal, that’s ok and part of the game!)

Boards

Before getting into the tiles—which is the meat of the game—let me first address the board, which is the structure you place your tiles into.

There’s an official board you can use, but I really didn’t like it for one major reason: the balls can easily drop off the board, onto the table and roll down to the floor where our 1-year old might find and try to eat them.

Luckily, Hextraction advertises itself as a hackable game, and Thangs user Inaudible has created two wonderful alternative boards for us to enjoy:

The super fancy remix with full gutters, variable size, ball holders and more.
A modular board you can rebuild into smaller and larger weirdly shaped boards.

Modular board

The modular board. I failed a little with my color selection as the two darker gray colors are way too similar.

I started with the modular board because I thought it would be nice to be able to modify it later, but mostly it was because it had just been released and my monkey brain thought “newer = better”.

I think the design is very cool. You can rearrange the board into cool and weird shapes, and add “blockers” right in the middle where no tiles can go. But we only use it as a regular board, because rearranging it is a bit of a chore, and overkill for my kids.

Pros:

The mind boggles with the possibilities.
Easily repairable if something breaks.
Can be made in a cool varying colorscheme.

Cons:

It was easy to break the goals (they act like levers). I broke three of them.
It’s not so easy to remove the balls from the gutters.

Super fancy remix

The super fancy board remix. I again failed with my color selection, as this is two (very similar) shades of brown.

Because I’m not a reasonable person, I also printed the super fancy remix.

While you can make the board larger, everything is glued together so once the choice is made you’ll have to live with it. I made it the same size as the other board, because… I don’t know really.

While the board is less exciting than the modular one, I greatly appreciate the integrated gutters that funnel the balls to the center of the board. There are some extra things, like dice and ball holders, but it’s not something we use.

Pros:

Feels more robust.
Good gutters that funnels all the balls into one place.

Cons:

Doesn’t have the same coolness factor or flexibility as the modular board.

Which board should you print?

If I had printed this for myself, I would’ve gone for the modular board and played around with other layouts. But for my kids and our use-case, I think the super fancy remix is better because it’s a bit more robust and the fully integrated gutters are superior.

You can of course print them both… But that require quite some time and material, so just pick one. The gutters are a must in my opinion, so I’d rather choose one of these boards over the original board.

Tiles

The fun part of Hextraction is the tiles, and there are lots of different tiles. At first I thought it’d be a challenge to find fun and interesting tiles when I’ve disqualified many of the most fun ones, but there were plenty of tiles for me and my kids to enjoy.

Path tiles

Honestly, a lot of the times when playing the game one of the most appreciated tiles to draw is just a regular tile. Around half of the tiles we use are these basic path tiles. It’s tempting to go nuts with the special tiles, but you need basic tiles to make the reasonable. If everything is special, then nothing is.

The original creator provides a good selection of basic tiles, most with short descriptive names; the DC, DIC, X, J, S, Z, Asterisk, and Peace tiles. I’ve added the K tile, V tile, W tile, Xc tile, Triangle tile, Scissors tile, Rectangle tile, and some Reroute tiles.

Secret tiles

We had some mixed feelings about the secret tiles. On one hand it’s great fun to place a tile that only you know how it works, but on the other hand the ball tends to get stuck inside them quite often, making the “3-ball then destroy the tile” rule difficult to keep track of.

So I replaced them with alternative secret tiles that never blocks a ball path:

This is the tiles before I glued the lid on. Although it wasn’t supposed to, the ball sometimes got stuck in the crossed out tile, so we threw that one away.

I also used the inverted secret lid to make the lid (much) easier to print well.

Trap tiles

The trap tiles add quite a lot of depth to the game.

Of the standard trap tiles, the double one is the best IMHO.

Traps are interesting because they allow you to block paths, allowing you to throw a wrench into your opponents plans at a crucial time. This often leads to the players having to route around existing paths, without blocking them off completely.

The Angry Crab acts as a trap for the middle, and is released from the sides.

Newton’s Cradle is an interesting one. Depending on how you orient the tile, it can act as a trap (that you can release from the other side) or as a regular tile.

Newton’s Cradle and the Angry Crab are probably my two favorite tiles in the game. I should print more of them.

Speed bump tiles

The speed bump tiles decreases the speed of the ball, trapping it if it’s moving too slow. The issue is that the kids gets a bit too frustrated with them, so I’ve reduced the number of speed bump tiles in circulation.

We still have three that we use, mostly because I like the educational aspect of the tiles (it’s physics!).

Flip-flop tiles

Even though it can malfunction at times, the Flip-flop tile is great as it adds a small state machine to the game.

Misc tiles

The Pachinko tile.

I personally really enjoy the Pachinko tile as it’s a great way to add some more randomness.

Zoidberg and UwU gives a face to Hextraction.

Because that level of randomness isn’t enough, the beautiful UwU tile and the Zoidberg tile acts as a random trap tile. But they’re mostly traps.

A loop. You need speed if you want to get through this one.

I also threw in a loop, because it’s silly and it’s fun when you manage to get a ball through it. It has the same pedagogical effect as a speed bump tile while having a cooler effect.

Who doesn’t love a good vortex?

Every marble run needs a vortex, and there’s the Vortex tile to fill that spot in Hextraction. I did have some issues getting it to print the tunnels correctly for my 10mm balls, but some filing took care of that issue.

Is there a better way to store balls than in a tile?

To store the balls I use The Ultimate Hextraction Storage Box. It’s also a tile, although you ~~can’t~~ shouldn’t play with it.

Make the game yours

The best thing about the game is that you can modify it to suit your needs.

Don’t like a tile? Hide it in a box or throw it in the trash.

A box of unused Hextraction stuff.

For example, I liked the idea of the Sozu tile, but I couldn’t get it to work consistently and having an extra rule of “first insert ball here” goes against our simplistic rules policy.

We don’t use any of the special effects tiles, but you can (and should) try them out. You can even make your own tiles, with your own silly rules. The bomb tile for example removes all adjacent tiles when it’s removed, and the angel down tile allows you to remove a trapped ball on any tile below.

It’s a build your own adventure type of a game, and you can even design your own tiles (or boards, if you’re a madman). If you’re like me and haven’t yet learned the dark CAD magic, there are lots of designs out there for you to include into your game.

Print it, play it!

If you have a 3D printer lying around (or have a friend with one), I heavily recommend you to check out Hextraction. It’s a very cool and silly game, which works very well even for young kids with minor tweaks. (To be honest, our 3-year old often uses it as a marble run. But that’s fine too.)

And if you don’t have a 3D printer yet, go ~~buy~~ build one!

Blogging in Djot instead of Markdown

2026-04-27T10:06:41+00:00

What if we weren’t chained to the past? What if we tried to create a light markup syntax that keeps what is good about Markdown, while revising some of the features that have led to bloat and complexity in the CommonMark spec?

John Macfarlane, Beyond Markdown

I recently happened to see an offhand comment on Hacker News about a markup language called Djot. I don’t really have any large issues with the ~~Markdown~~ CommonMark I use to generate the posts for this website, but my brain saw a chance to get sidetracked yet again, and here we are.

The creator of Djot is John MacFarlane, the same philosophy professor that also created Pandoc and CommonMark. These might be two of the most influential projects in the markup space, so you’d get the feeling that maybe there’s something to this Djot thing.

The devil is in the details

I was going to give a few examples of what Djot looks like, but honestly, 95% of the Djot I write looks very similar to Markdown, with only minor differences.

So what’s the point?

The point is to try to take the good parts of CommonMark (the standard, unambiguous syntax specification for Markdown) and improve it in two ways:

Make it easier to parse.
Extend the feature set.

I’m sympathetic to the parsing problem, as it doesn’t sound that fun:

There are 17 principles governing emphasis, for example, and these rules still leave cases undecided. The rules for list items and HTML blocks are also very complex. All of these rules lead to unexpected results sometimes, and they make writing a parser for CommonMark a complex affair. I despair, at times, of getting to a spec that is worth calling 1.0.

John Macfarlane, Beyond Markdown

For this alone I’d be willing to at least try Djot, but there are some added features I’d like to use. It’s true that I probably won’t have much use for things like definition lists or math for my blog posts, but the native support for divs and the ability to add attributes to any element is something I’ve been missing.

Tools

Given that Djot is a relatively young project, I expected the tooling to be lacking. There are things missing, but it wasn’t so bad for my use-case.

I found a Djot Sublime Text grammar I can use for syntax highlighting the blog, and there is Vim syntax highlighting in the Djot repo.

(Sad for those who don’t use Vim I guess.)

More annoying is that there’s no treesitter implementation for Djot. This is unfortunate, as with treesitter for Markdown I get proper syntax highlighting inside code blocks and I have a general treesitter jump command that, for Markdown, jumps between headers with ]g and [g. (In Rust it jumps between structs, implementations, enums, and functions. It’s a general treesitter mapping.)

Not a deal-breaker of course. Using the Markdown treesitter for Djot works well enough for the time being. (Maybe I need to explore how treesitter grammars work one day, and create one for Djot.)

As for parsing I found Jotdown, which is a Rust library with an API inspired by pulldown-cmark, the library I use to parse CommonMark.

Abstracting away markup parsing

I didn’t want to convert my existing Markdown files as I have more than 250 posts. (Yeah, I don’t know how that happened.)

So to add Djot support I had to refactor my site generator a bit and support both Djot and Markdown parsing. I’ve been lazy so this wasn’t as straightforward as I hoped; I had sprinkled calls to Markdown parsing all over the place.

When I don’t really know where to begin unwinding such a mess, I like to begin by modeling the data types in the domain. If I get the data modeling right, the rest has a tendency to fall into place fairly quickly.

One of the things I love about Rust is the enums (or sum types for you fancy people) which makes it easy to model an “either this or that” type:

#[derive(Debug, Copy, Clone)]
pub enum MarkupType {
    Markdown,
    Djot,
}

You can also add data to each variant, like so:

#[derive(Debug, Clone)]
pub enum Markup {
    Markdown(String),
    Djot(String),
}

This is nice because now the type system prevents you from accidentally using the wrong format, which would be easier if you stored a MarkupType and a String separately.

I did indeed store untagged data previously:

pub struct PostItem {
  // Is this in markdown or already parsed to html?
  // Wait, maybe it's in djot!
  pub content: String,
}

To make this harder we should probably create a newtype for html as well:

#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Html(pub String);

Then to parse the markup you can add a parse method to Markup, that delegates to the right parser:

impl Markup {
    pub fn parse(&self) -> Result<Html> {
        match self {
            Self::Markdown(s) => markdown_to_html(&s),
            Self::Djot(s) => djot_to_html(&s),
        }
    }
}

Now posts can hold Markup and Html structs and we can rely on the compiler to ensure we don’t accidentally mix them:

pub struct PostItem {
    pub content: Html,
    pub markup: Markup,
    // Many other fields omitted..
}

With the right types in place the rest of the refactoring follows naturally. Just hide any Markdown and Djot specific implementation behind these types, follow the compile errors, and you’re soon done. Thinking and designing with types is usually a pleasure.

(Yeah, maybe it’s not quite that simple, but it’s a very helpful approach nevertheless.)

See the source for the website for more details.

Customized markup

For the blog I have some markup transformations I apply to Markdown. This includes demoting headers, embedding bare YouTube links, transforming image collections, syntax highlighting, and more.

It’s a bit hacky though.

Epigraphs

For example, I want to be able to turn a quote into an epigraph by wrapping it inside a div:

<div class="epigraph">
  <blockquote>
    <p>This is an epigraph</p>
  </blockquote>
</div>

But the CommonMark parser doesn’t process markdown inside html, so I added an attribute parser to wrap a quote in an epigraph:

> This is an epigraph
{ :epigraph }

The implementation isn’t pretty, and only works for specific elements such as a blockquote. But Djot has a built-in syntax for divs, so I can just write this to produce the same epigraph html output:

::: epigraph
> This is an epigraph
:::

Asides

I still need to do a bunch of transformations to reproduce existing functionality.

For instance, I want html output like this:

<aside>
  <p>This is a notice</p>
</aside>

There isn’t a native way to do this (other than inserting raw html, ew). For my own transformations the div system works well as a starting point, so I can use this kind of input:

::: note
This is a note
:::

And then match on the note class to transform the div into aside, and we’re done.

In Jotdown, like with pulldown-cmark, transformations are made by transforming iterators over events. Here I’m looking for Event::Start(Container::Div, attrs) and Event::End(Container::Div) (I ignore nesting). Transforming with iterators instead of an AST structure is awkward, so keeping the transformations as small as possible is nice.

Images

I used the same div syntax in Markdown to create collections of images:

::: Flex
/images/configura14/octree1.png{ height=300 }
/images/configura14/octree2.png{ height=300 }
:::

This would wrap the images in a flex container to display them side-by-side:

<figure class="flex-50">
  <a href="/images/configura14/octree1.png"><img height="300" src="/images/configura14/octree1.png"></a>
  <a href="/images/configura14/octree2.png"><img height="300" src="/images/configura14/octree2.png"></a>
</figure>

I (naturally) used to do this with Regex in a preprocessor step, and had some fun adding attribute parsing.

Now all I do is transform the div to a figure with the proper class. Even something like this with references outside and attributes works, without any special handling on my end:

::: flex
![][one]{ height=300 }
![][two]{ height=300 }
:::

[one]: /images/configura14/octree1.png
[two]: /images/configura14/octree2.png

(Yeah maybe I gloss over the gross implementation a little.)

Blockquote citations

Quotes are nice, but I want to be able to add author attribution to them sometimes.

The html I want looks something like this:

<blockquote>
  <p>With author attribution</p>
  <footer>
    <span class="author">John Doe</span>
  </footer>
</blockquote>

With Markdown, I used custom attribute parsing to add author metadata:

> With author attribution
{ author=John Doe }

I could’ve done the same thing with Djot, or piggyback on Djot’s general attribute parsing and match on that (the attributes go before the quote, but otherwise looks similar).

But I got inspired by an ongoing discussion on the Djot repo about adding blockquote attribution support where this clean syntax was suggested:

> With author attribution
> ^ John Doe

There’s no support for this yet, so I had to do the transformation myself. But on the upside, by passing through the Jotdown events after ^ during the iteration transformation we can easily support links or other Djot markup in the author field.

So this example:

> With author attribution
> ^ [John Doe](#) ~31/1~

Would produce:

<blockquote>
  <p>With author attribution</p>
  <footer>
    <span class="author"><a href="#">John Doe</a> <sub>31/1</sub></span>
  </footer>
</blockquote>

Other transformations

There are other transformations I do with Djot as well:

pub fn djot_to_html(djot: &str) -> Result<String> {
    let transformed = Parser::new(djot);
    // Demote headers (eg h1 -> h2) and give them an "a" tag.
    let transformed = TransformHeaders::new(transformed);
    // Convert standalone images to figures.
    let transformed = AutoFigures::new(transformed);
    // Embed raw youtube links using iframes.
    let transformed = EmbedYoutube::new(transformed);
    // Syntax highlighting.
    let transformed = CodeBlockSyntaxHighlight::new(transformed);
    let transformed = InlineCodeSyntaxHighlight::new(transformed);
    // Transform divs, such as asides and figures.
    let transformed = DivTransforms::new(transformed);
    // Add a <footer> with author info to quotes.
    let transformed = QuoteTransforms::new(transformed);
    // Warn if any broken links are detected.
    let transformed = BrokenLink::new(transformed, context);

    let mut body = String::new();
    Renderer::default().push(transformed, &mut body)?;
    Ok(body)
}

The ones I didn’t bring up in the blog are pretty similar to their corresponding Markdown implementation. I’m not going to go through them in detail, see the source code if you’re interested.

The future is bright

Djot is a young project but with the more expressive custom markup it has improved my blogging experience. But more improvements are upcoming, with ongoing discussions on quite a few topics that would remove the need for many of my custom transformations, for example:

Native blockquote attributions
Auto block-level figures
Captions for figures/tables
Custom tags support (convert div into aside)

While I don’t currently use most of the added features compared to CommonMark, in the future I might start making use of the other types of lists (who doesn’t love a good list?) and footnotes might be a good addition to the more long-form blog posts I’ve been gravitating towards.

Complaints about Djot

I’ve seen some people dismiss Djot because of its handling of sublists:

Exactly, the sublist newline stuff is a total nonstarter for me. Sorry, I guess I’ll run a markdown parser that takes an extra second or whatever to run.

qbasic_forever

In Djot you have to surround a sublist with newlines. You can’t write this:

- List
  - This is fine in Markdown, but not in Djot

You have to do this:

- List

  - This is fine in both Djot an Markdown

It is indeeed more annoying at times, especially if you use the markup for smaller pieces of text, or use it to maintain a todo list with subtasks. But for more long-form content I don’t think it’s a big deal (which is what Djot targets more I guess).

Another complaint I’ve seen is that Djot doesn’t represent enough of an improvement compared to the different Markdown flavors to overtake them in popularity. This is a fair take—but I don’t care if it ever dethrones Markdown/CommonMark/whatever. It’s useful for me, and that’s all that really matters.

Let's build a VORON: Smaller fixes

2026-04-27T15:25:59+00:00

I’ve been busy. Busy printing stuff.

Which is awesome, because one big worry I had was if I’d actually use the printer or just end up modding and tweaking it until the end of time.

But of course, I’ve been slowly working through my large mods-I-want list. My initial plan was to write one blog post about modding, but for space and sanity reasons I’ve decided to split it up.

This post goes through a bunch of smaller fixes and mods I’ve done to the printer, and I’ll leave the more involved mods to later posts.

Tweaks & tuning

My plan was to take tuning seriously and go through all the tuning guides to get the printer to produce perfect prints. But I didn’t have patience for that and I’ve only made some tweaks when the prints had noticeable defects. Here are the major tweaks I’ve done since the last post:

Bed mesh offset in one corner

It got pointed out to me in the VORON forum that I my right rear Y extrusion was a bit high. The Trident has automatic bed leveling, but because the bed is only attached in three positions it can’t compensate for a difference in the rear that only has a single mount in the middle. If you’re unlucky this might cause issues with bed adhesion.

Turns out I’ve had some problems with bed adhesion. Not a lot mind you, but enough to bother me on some trickier prints. I’ve seen the offset on the corner go down to -0.26, which is more than the standard 0.2 layer height I use, so this might be the cause of some of the issues I’ve seen.

Before adjusting the right Y extrusion.

In the voron_1_trident_questions channel on the VORONDesign Discord there was a pinned message on how to adjust this. I ended up adjusting the front right Y extrusion upwards quite a bit to compensate for this.

After adjusting the front right Y extrusion upwards.

The mesh still isn’t perfect (and it can sometimes look worse than the adjusted picture above), but it’s now a lot better and importantly the rear corners are much more level.

Bulging corners

One significant print issue I’ve had is bulging in the corners on overhangs:

Both edges round upwards and apart from being really ugly, they’ve caused a number of prints to fail when the nozzle has knocked loose pieces from the bed or has caused belts to skip.

It’s really ugly.

Maybe it was overheating? But it happened consistently, with long layer times, with max fans, and for PLA/ABS/ASA. Another idea was over extrusion, but I think that should’ve shown up in other places?

Then I found the Bulging section in Ellis’ Print Tuning Guide that made the issue disappear. These were the changes I made:

Enable external perimiter first
Set overhang threshold for bridge flow to 0
I also experimented with disabling overhangs specific settings completely (set bridge speed and fan to 0 or the disable checkbox), but I’m uncertain how effectual that was compared to the other two settings.

Some of these were specific to SuperSlicer, the slicer I use.

These are two prints that show the difference between the settings. The green is without the changes and white is with the changes. Apart from the overhangs, the green printout looks pretty good, but the overhangs look terrible. The white still has some defects, but it’s so much smoother.

Extruder skipping

I had printed for around 400 hours when the extruder suddenly started skipping. At first it was just minor artifacts, but after a while prints started failing in major ways or refusing to extrude anything at all:

My first idea was that I had messed up the tension in the extruder, so it no longer got a good grip on the filament. (I had some major issues with loading filament at one time, and I started screwing around with everything I could think of.)

But alas I couldn’t solve it with a quick-fix, so I had to open up the toolhead. Which I should have done much sooner, because there were a bunch of broken filament stuck in the gears:

One piece of broken filament inside the CW2, together with a bunch of dirt.

I really didn’t want to disassemble it because I was afraid of the effort to do so, but in the end it was just a few screws and the whole cleaning process took 10 min. Building your own printer has some benefits, I should have more faith in the process.

2mm PTFE between extruder and hotend

There were a lot of leftovers after the build; nuts, screws, belts, etc. But also an unused bag with “Teflon Tubing, 4x2mm”, which surely shouldn’t be completely unused?

Turns out you’re supposed to use a tube with an inner diameter of 2mm between the extruder and hotend, but I had used the regular PTFE tube that had an inner diameter of 3mm. This isn’t ideal and requires more retraction (which I didn’t compensate for), and it can cause stringing issues (which I had).

First layer woes

For a long time I was really happy with how my first layers looked and I could start a print and it would finish without issue most of the time.

But sometimes I had these “blobs” that started collecting:

This is some extra filament that has been pushed around and gotten stuck on the print.

I couldn’t figure out where it was coming from. Overextrusion maybe, but i didn’t find any issues with it and this only happened in the beginning of the print.

And later on I started to get severe issues with bed adhesion where I felt lucky if a part stuck around long enough for the print to finish. The first layer started to look garbage as well:

The worst part is, I didn’t think I had changed anything.

I tried a bunch of things; changing nozzle, recalibrating PA and EM, changing filament, and even replacing the extruder (more on that in a future post) yet the issue remained.

What finally fixed it was recalibrating the z offset and tuning first layer squish once more. I’m not sure why I had to do this again (doesn’t Tap magically solve everything?), but now the first layer is pretty and the bed adhesion problems are almost completely gone. (Some prints have a tendency to warp a little, but I guess it’s hard to get things perfect.)

Much better first layer!

Mods

These are some smaller mods from the LDO kit I hadn’t gotten around to installing, and some other small mods that fixed some annoyances I’ve had.

Handles

The kit includes some very nice handles you can install. But unfortunately they cover up the top panel so you have to remove the handles before you can remove the panel—a gigantic pain.

So I ended up printing some sturdy handles instead. They’re really large comparatively, but they get the job done. I haven’t had that much use for them yet, but I felt obliged installing them since some kind of handles came with the kit.

LED mounts

There were no instructions on how to install the LEDs, so I taped them on top of the included extrusions covers. Turns out you were supposed to print a bunch of LED mounts to get the LEDs pointing inwards towards the print for better lighting:

Before the LED strips were mounted flat.

Now they’re tilted inwards and have shields to direct the light towards the build plate.

Longer spool holder

The stock spool holder to the left, a longer one I printed to the right.

I ran into the surprising issue that some spools were too wide for the stock spool holder (3DJake’s filament for example). So I replaced it with a longer one.

In the future I should probably replace it with a top mounted spool holder, but I got lazy when I saw I didn’t have the required M5 hardware. Maybe another day.

Bowden tube routing

I had some issues with the bowden tube getting stuck behind or under the cable chain, so I tried the bowden tube guide to keep it away. It was difficult to find a route that worked well. Depending on the mount position it had a tendency to cause a bend in the tube that drastically increased the friction on the filament, which I suspect was the cause for some prints failing.

I also use the Trident noodle that’s made to prevent the tube from colliding with the roof of the printer, and this combination works very well.

Display mount

The display mounts I got from the print-it-forward service wasn’t compatible with the screen I got, so I had to hold it together with tape.

So I tried to find the proper parts to print, but I must be missing something because the screw holes to hold the display cover still don’t line up. I don’t care to spend more energy on this; it’s a bit weird but tape does the job well enough.

At least I got the display cover in an accent color.

Improved seal in extrusions

Despite having the Nevermore filter and a HEPA filter exhaust, I could very clearly smell ABS fumes from the printer. Looking at the extrusions, there were large holes in the blind joints and I suspect that doesn’t help.

Therefore I tried to cover up the holes with some Sugru. It’s better, but I should probably replace the front door too.

Are we done yet?

It’s true that the printer can now be considered Done™—and it has been done for a while—but I still have some mods I’d like to document before I wrap up this build series.

Exploring the Gleam FFI

2025-08-11T06:08:20+00:00

My brain is a curious thing. I’m on a business trip right now and I’ve set aside time to finish some important todos I want and need to get done. But instead of focusing on them, I started playing around with Gleam—a young and interesting programming language.

My (current) favorite programming languages are Rust and Elixir. They’re really different from each other, but they work well together as Rust can easily be embedded via Erlang NIFs. This is useful because one of the drawbacks with Elixir (or rather the Erlang VM that Elixir runs on) is raw computational performance, something that Rust excels at.

Another drawback with Elixir is the lack of typing (although improvements are underway). This is what drew me to Gleam, which feels like Elixir but with Rust types on top—a fantastic sales pitch.

A big drawback with young languages is that there aren’t a lot of libraries out there, so you’ll have to roll your own solutions most of the time. But the beauty of targeting existing platforms is that you can also leverage their libraries, which in Gleam’s case means all Erlang and Elixir libraries (or JavaScript, depending on your compilation target). This is accomplished via Gleam’s FFI, which is quite convenient.

Let’s explore.

Prerequisites

If you want to follow along, make sure you have the respective compilers installed. I’ll base the examples from a clean new repo:

$ gleam new myapp

Erlang

As shown in the Gleam Book calling standard Erlang functions is straightforward. You declare foreign functions with the @external keyword and then call them as normal:

import gleam/io

@external(erlang, "rand", "uniform")
pub fn random_float() -> Float

pub fn main() {
  io.debug(random_float())
}

That if run will call the uniform function in the rand Erlang module:

$ gleam run
0.43487935467166317

This works for standard libraries, but you can access other Erlang libraries on Hex by adding them as dependencies in gleam.toml:

[dependencies]
base32 = "~> 0.1.0"

Declare and call it like before:

@external(erlang, "base32", "encode")
pub fn encode_base32(x: String) -> String

pub fn main() {
  io.debug(encode_base32("superhidden"))
}

And Gleam will download and compile the Erlang dependency:

$ gleam run
  Compiling base32
===> Fetching rebar3_hex v7.0.7
===> Fetching hex_core v0.8.4
===> Fetching verl v1.1.1
===> Analyzing applications...
===> Compiling hex_core
===> Compiling verl
===> Compiling rebar3_hex
===> Analyzing applications...
===> Compiling base32
"ON2XAZLSNBUWIZDFNY======"

If you want to write Erlang code yourself and call that, it’s also very easy. The gleam compiler will compile and include .erl files automatically.

For example this file src/erlib.erl:

-module(erlib).
-export([ping/0]).

ping() ->
    io:fwrite("ping~n", []).

Declare and call the function in gleam like before:

@external(erlang, "erlib", "ping")
pub fn ping() -> a

pub fn main() {
  ping()
}

$ gleam run
ping

You can also call Gleam functions from Erlang. With for example this pong function in src/mypong.gleam:

import gleam/io

pub fn pong() {
  io.println("pong")
}

You can call the Gleam function with module:function():

ping() ->
    io:fwrite("ping from Erlang~n", []),
    mypong:pong(). % Call the Gleam function

$ gleam run
ping from Erlang
pong

Elixir

If you want to include Gleam code into an existing Elixir project, look at MixGleam on how to teach mix how to work with Gleam code and dependencies. But if you want to include Elixir code into your Gleam project, you can do that just as easily as with Erlang.

Declaring foreign Elixir functions uses the same @external keyword:

import gleam/io

@external(erlang, "Elixir.RandomColor", "hex")
pub fn random_color() -> String

pub fn main() {
  io.println(random_color())
}

Note that Elixir modules gets an Elixir prefix and that we’re still calling external Erlang code as Elixir gets compiled to Erlang.

Dependencies are added from Hex, exactly the same as with Erlang dependencies:

$ gleam add random_color
$ gleam run
#3724C9

Calling our own Elixir code is just as easy as with Erlang. Just include it in your source directory, like this src/exlib.ex:

defmodule Exlib do
  def ping() do
    IO.puts("ping from Elixir")
    :mypong.pong()
  end
end

And refer to the module as Elixir.Exlib:

@external(erlang, "Elixir.Exlib", "ping")
pub fn ping() -> a

pub fn main() {
  ping()
}

$ gleam run
ping from Elixir
pong

Keep in mind that:

You can’t directly call Elixir macros (they happen on compile time).
If you include Elixir you’ll also include the Elixir standard library.

Erlang might be a better choice if you want something more lightweight.

Rust

In the beginning I wrote that you could easily call Rust code from Elixir via rustler. You can call Rust from Gleam as well, either via Erlang or Elixir. Rustler recommends to use mix with Elixir, but we can do this with Erlang and keep using the Gleam toolchain.

First we need to create a Rust project somewhere. We can create it in the top level of the Gleam repo or in a native/ folder or wherever. For this example I’ll just leave it at the top:

$ cargo new rslib --lib

On the Rust side I’ll use rustler to create the NIF:

$ cd rslib/
$ cargo add rustler

And in rslib/src/lib.rs we’ll tag the function we want to expose with rustler:

#[rustler::nif]
pub fn truly_random() -> i64 {
    4 // Chosen by fair dice roll. Guaranteed to be random.
}

rustler::init!("librs", [truly_random]);

We want to build this as a dynamic library, so we’ll need to update Cargo.toml:

[lib]
crate-type = ["dylib"]

Then build it in release mode:

$ cargo build --release
  ...

This should generate the library at target/release/librslib.so. Yes, my naming choice here sucked, but let’s roll with it.

For Gleam to be able to use this file we need to copy it to priv/ (relative to the Gleam root, not the Rust project):

$ mkdir ../priv
$ cp target/release/librslib.so ../priv/

The file layout should look something like this:

├── README.md
├── build
├── gleam.toml
├── manifest.toml
├── priv
│   └── librslib.so     # The important part
├── rslib
│   ├── Cargo.lock
│   ├── Cargo.toml
│   ├── src
│   │   └── lib.rs
│   └── target
└── src
    └── myapp.gleam

Update 2024-08-30

I only tested this on Linux where the .so extension is used but I didn’t test it on Mac or Windows.

I’m told that on Mac a .dylib file will be generated but you should still copy it to the priv/ folder with the .so extension:

$ cp target/release/librslib.dylib ../priv/librslib.so

On Windows a .dll file will be generated and that’s also the extension that should be used in the priv/ folder.

To include the library we’ll use some Erlang. We’ll use src/rslib.erl similar to before, but with Erlang NIFs:

-module(librs).
-export([truly_random/0]).
-nifs([truly_random/0]).
-on_load(init/0).

init() ->
    ok = erlang:load_nif("priv/librslib", 0).

truly_random() ->
    exit(nif_library_not_loaded).

We now load the librslib library, declare truly_random as a NIF with -nifs(..) and add a function placeholder that will be replaced when the library loads.

With the Erlang code in place what’s left is to call the Erlang function from Gleam:

import gleam/io

@external(erlang, "librs", "truly_random")
pub fn truly_random() -> String

pub fn main() {
  io.debug(truly_random())
}

And now we can call our truly random Rust function!

$ gleam run
4

While Rust is amazing, and it’s great that we can call it from Gleam, there are some drawbacks to be aware of:

The glue is verbose as we need to duplicate the function name a bunch of times.
Building the library and moving it to priv/ isn’t handled by the Gleam toolchain. I’ve seen some people use a Makefile to build the library and then copy it to priv/.
NIFs can crash the whole runtime. While Rust is safer than C, it can still bring the whole runtime down and not just a single Erlang process.

Calling Gleam code from Rust seems harder. I found an example of calling Elixir or Erlang function from Rust, but I haven’t looked at in more detail.

JavaScript

Gleam can also compile to JavaScript, and this blog post wouldn’t be complete without a short example.

To compile for JavaScript we can add target = javascript to our gleam.toml or use the target flag:

$ gleam run --target javascript

Like before when we called Erlang and Elixir files, if you add a JavaScript source file in src/ it will automatically get included. For example this src/jslib.mjs:

import * as gleam from "./mypong.mjs";

export function ping() {
  console.log("ping from JavaScript");
  gleam.pong();
}

And to declare the foreign function, we now use the relative file instead of the library name:

@external(javascript, "./jslib.mjs", "ping")
pub fn ping() -> a

pub fn main() {
  ping()
}

And when run you’ll see that we can call the JavaScript ping function which in turns calls our Gleam pong function:

$ gleam run --target javascript
ping from JavaScript
pong

You can inspect the output JavaScript files in build/dev/javascript/myapp/, which is very useful when debugging or trying to understand the code Gleam generates.

Ending thoughts

I hope this post gives helps you understand how to get started with Gleam’s FFI system. I haven’t looked into Gleam more than a few days, but given how easy it is to get access to my other favorite languages and their ecosystems, I don’t have to worry that I’ll be missing out on some crucial functionality if I’m going to create something real with Gleam.

2023 in review

2024-12-16T08:52:47+00:00

This is my yearly review #14. Amazing that I’ve kept up with this for 14 years.

Even though it’s not anything advanced, I really like looking back at the year to see what has happened. Maybe it’s a very light version of a reverse bucket list, and I can see that it provides some of the same happiness benefits.

2023 Non-Geek Achievements

All my three kids are happy and healthy.

It’s thanks to Veronica, but I’d like to think I’ve contributed something.
Wrote 17 blog posts!

Most of them were written (and published) in the last quarter where I got bitten by the blogging bug.

2023 Geek Achievements

I beat FTL on Hard with all ships in the game.
I built a VORON and got into 3D printing.
Two of my blog posts got to the front page of Hacker News.

I’ve always blogged to write for myself and never because I wanted my blog to be popular, but it was still nice to see some people appreciate it.
I rewrote my Neovim config in Lua.
I gave the blog a sorely needed facelift.
I wrapped up my series about the T-34 keyboard layout.

2023 Misadventures

While I finished the eBook of my book, I only made it available for purchase using cryptocurrencies a short amount of time.

The reason is that I made it available with my payment processor, but I ran out of energy so I shut down the server. I really need to get it together and just upload it somewhere so it’s purchasable normally.

Maybe I should just make it available for free, so I can close the chapter on the book project?
I didn’t read that many books—at least I don’t remember that I did.
Despite me trying to reduce it, the boardgame list of shame grew this year.

There’s a complete stop to Kickstarters and buying new games until I correct this mess.

Plans for 2024

Focus on mental and physical health, with a focus on strength training.
Finally complete the book project by putting the eBook widely available and finishing the How I wrote ‘Why Cryptocurrencies?’ series.
Finish my planned mods on my VORON 3D printer and complete the blog series.
Complete my Git rewrite in Rust project, that i left hanging back in 2020.

I’m already thinking of postponing this again… But maybe I can make some amount of progress at least?
Start a new long-term project.

I’ve promised myself to finish up my ongoing projects before I’m allowed to do this, but we’ll see how that goes. (Not well I suppose.)

Let's build a VORON: Filters

2026-01-29T10:44:48+00:00

I can print, but the printer is missing a very important thing that I alluded to in the previous post: filtering dangerous particles and fumes.

This is mostly covered by the kit, but I was missing some parts from the print it forward and the kit didn’t include a HEPA filter. Because the printer is in the office and health is super important fixing this was needed so I could start printing some ABS and continue modding the printer.

Exhaust cover

I’m missing the exhaust cover where the filter goes in a stock VORON.

The standard VORON comes with a filter in the back, but the LDO kit doesn’t include the fan for the filter and instead uses an exhaust cover to close the hole.

I didn’t receive this part, so the first thing I did was to print that part. This was just a very temporary measure so I printed it in PLA.

Nevermore filter

The Nevermore filter is installed next to the back panel.

The LDO kit includes the Nevermore filter, which removes VOCs. I was confused on how to install it as at the time the LDO docs only mentioned how to install it on a 2.4, not on a Trident. When I brought it up they fixed it so no big deal.

But they wanted me to mount it using a plenum mount, which my parts didn’t have. I think I received an older version of the Nevermore from the print it forward service so I couldn’t use it.

I instead printed out the updated plenum and frame connector myself. Because the point of the Nevermore is to be able to print ABS safely I did this in PLA as well. I know it’s not ideal, but it will have to do. Lazy as I am I’ll run with this and if it breaks I’ll replace it then.

I also added some strips of foam tape to the back of the filter to prevent it from scrambling against the back panel.

Cutting away parts from the fans was horrible. They broke very easily.

I finally got to exercise my (very poor) soldering skills! It was cute how LDO included a small board so that you don’t have to crimp any cables.

HEPA exhaust filter

A new HEPA filter. I wasn’t able to color match with the print-it-forward parts…

While I have the Nevermore filter, it doesn’t filter Ultra-Fine Particulates. For that you need a HEPA filter.

There were a few solutions with combined carbon and HEPA filter, but since I already have the Nevermore I wanted a standalone HEPA filter. I found the Voron HEPA Exhaust Filter that replaces the stock filter that seemed like a good option.

With the Nevermore in place I could print the parts using ABS, and they turned out pretty well.

For silence I used a Noctua FN-A6x25 fan. In hindsight I maybe should’ve used the PWM variant, if only to make the wiring simpler. Now I have this ugly looking wiring in the top corner (it uses the Noctua low-noise adapter).

I also had to create another cable, which wasn’t too difficult:

Converted the 3-pin cable to a 2-pin JST connector and extended it.

I simply ignored the yellow RPM speed signal cable.
Connect to a free fan output on the Octopus.
Used the 12V selection jumper for the fan output.

Klipper setup

With the fans installed you also need to configure Klipper to utilize them.

I setup them both as generic fans, so I can control them from the start and end macros:

[fan_generic nevermore_fan]
##  Nevermore fan - FAN3
pin: PD13
max_power: 1.0
kick_start_time: 5.0

[fan_generic filter_fan]
##  HEPA filter fan - FAN4
pin: PD14
max_power: 1.0
kick_start_time: 5.0

Then in PRINT_START I turn on the fans:

SET_FAN_SPEED FAN=nevermore_fan SPEED=1
SET_FAN_SPEED FAN=filter_fan SPEED=1

After the print has finished I don’t want to just turn off the fans immediately, but have them run a bit after the print has finished to clear out any toxic fumes. I accomplished this with a delayed_gcode:

[delayed_gcode _VENT_OFF]
gcode:
  SET_DISPLAY_TEXT MSG="Venting done"
  SET_FAN_SPEED FAN=nevermore_fan SPEED=0
  SET_FAN_SPEED FAN=filter_fan SPEED=0

That I call in PRINT_END with a timeout:

# Turn off fans after 30 min
UPDATE_DELAYED_GCODE ID=_VENT_OFF DURATION=1800

To prevent the fans from turning off mid-print if I get impatient and start a new print before _VENT_OFF has been called I also clear the delayed gcode in PRINT_START:

# Prevent Nevermore and filter fan from being turned off mid print
UPDATE_DELAYED_GCODE ID=_VENT_OFF DURATION=0

And now the filter fans turn on and off automatically.

Some people run the Nevermore on 50–80% during print and then go 100% at the end, but I don’t know why you can’t run it at 100% all the time so that’s what I do.

Reworked `PRINT_START`/`PRINT_END`

I also rewrote the PRINT_START and PRINT_END macros to make a little more sense to me. Here they are in their entirety:

[gcode_macro PRINT_START]
gcode:
  # Fetch data from slicer
  {% set target_bed = params.BED|int %}
  {% set target_extruder = params.EXTRUDER|int %}
  {% set target_chamber = params.CHAMBER|default(0)|int %}

  # Set temps for bed and extruder without waiting to save some time
  SET_DISPLAY_TEXT MSG="Preheating"
  SET_HEATER_TEMPERATURE HEATER=heater_bed TARGET={target_bed}
  SET_HEATER_TEMPERATURE HEATER=extruder TARGET=150

  SET_DISPLAY_TEXT MSG="Homing"
  G28                                                     # Full home (XYZ)
  G90                                                     # Absolute position
  G92 E0                                                  # Reset extruder

  BED_MESH_CLEAR                                          # Clears old saved bed mesh (if any)
  CLEAR_PAUSE                                             # Ensure that we can't accidentally resume an old pause
  # Prevent Nevermore and filter fan from being turned off mid print
  UPDATE_DELAYED_GCODE ID=_VENT_OFF DURATION=0

  SET_DISPLAY_TEXT MSG="Bed: {target_bed}c"
  # We're in the center of the bed after full home
  M190 S{target_bed}                                      # Sets the target temp for the bed

  # Heating nozzle to 150 degrees. This helps with getting a correct Z-home
  SET_DISPLAY_TEXT MSG="Hotend: 150c"
  M109 S150                                               # Heats the nozzle to 150c

  # Turn on fans to help with chamber heating
  SET_FAN_SPEED FAN=nevermore_fan SPEED=1
  M106 S255                                               # Turns on the PT-fan

  # Waits for chamber to reach desired temp
  SET_DISPLAY_TEXT MSG="Heatsoak: {target_chamber}c"
  TEMPERATURE_WAIT SENSOR="temperature_sensor chamber_temp" MINIMUM={target_chamber}

  # Only turn on filter after chamber has been heated
  SET_FAN_SPEED FAN=filter_fan SPEED=1

  SET_DISPLAY_TEXT MSG="Z-tilt adjust"
  Z_TILT_ADJUST                                           # Levels the buildplate via z_tilt_adjust
  G28 Z                                                   # Homes Z again after z_tilt_adjust

  SET_DISPLAY_TEXT MSG="Bed mesh"
  BED_MESH_CALIBRATE                                      # Starts bed mesh

  # Heats up the nozzle up to target via data from slicer
  SET_DISPLAY_TEXT MSG="Hotend: {target_extruder}c"
  SMART_PARK                                              # KAMP parking routine
  M107                                                    # Turns off partcooling fan
  M109 S{target_extruder}                                 # Heats the nozzle to printing temp

  SET_DISPLAY_TEXT MSG="Purge"
  VORON_PURGE                                             # KAMP purge
  G92 E0                                                  # Reset extruder
  SET_DISPLAY_TEXT MSG="Printer goes brr"

[gcode_macro PRINT_END]
gcode:
  # safe anti-stringing move coords
  {% set th = printer.toolhead %}
  {% set x_safe = th.position.x + 20 * (1 if th.axis_maximum.x - th.position.x > 20 else -1) %}
  {% set y_safe = th.position.y + 20 * (1 if th.axis_maximum.y - th.position.y > 20 else -1) %}
  {% set z_safe = [th.position.z + 2, th.axis_maximum.z]|min %}

  SAVE_GCODE_STATE NAME=STATE_PRINT_END

  SET_DISPLAY_TEXT MSG="Print done"

  M400                                                        # Wait for buffer to clear
  G92 E0                                                      # Zero the extruder
  G1 E-2.0 F3600                                              # Retract filament

  TURN_OFF_HEATERS

  G90                                                         # Absolute positioning
  G0 X{x_safe} Y{y_safe} Z{z_safe} F20000                     # Move nozzle to remove stringing
  G0 X{th.axis_maximum.x//2} Y{th.axis_maximum.y - 2} F3600   # Park nozzle at rear
  M107                                                        # Turn off partcooling fan

  # Turn off fans after 30 min
  UPDATE_DELAYED_GCODE ID=_VENT_OFF DURATION=1800

  BED_MESH_CLEAR
  RESTORE_GCODE_STATE NAME=STATE_PRINT_END

[delayed_gcode _VENT_OFF]
gcode:
  SET_DISPLAY_TEXT MSG="Venting done"
  SET_FAN_SPEED FAN=nevermore_fan SPEED=0
  SET_FAN_SPEED FAN=filter_fan SPEED=0

Let's build a VORON: Printing & Tuning

2026-01-29T10:45:48+00:00

It’s up and running, and now it’s finally printing time! Less exciting—but necessary—tuning the printer to make the prints better.

Filament shipment

Even though I’ve been building the printer for more than a month, I wasn’t ready for it being time for printing so soon. I don’t know what filament is good and what I need, so I decided to get a few different brands and colors to try out:

3DJAKE niceABS Black
eSUN ABS+ Purple
Polymaker PolyTerra PLA Army Dark Green and Army Blue
3DJAKE ecoPLA White & Black
Spectrum PLA Dragon Red
eSUN eSilk PLA Gold

I think I went overboard with the filament order.

Secondary printer tuning

At this point the next step in the VORON docs is making a print. But I had various issues, so I went through the Secondary printer tuning before getting my first successful print.

Gantry racking & squaring

I’ve already done the gantry racking, yay!

Belt tension

I always wondered how tight the belts were supposed to be. Tuning it by measuring the frequency using an app was pretty nifty, and it was quite painless.

It’s around 110Hz, I think?

I tried to tune it to 110Hz, but I’ve seen people aiming for 120Hz.

Bed mesh

To setup a bed mesh you just add something like this to Klipper:

[bed_mesh]
speed: 300
mesh_min: 40, 40
mesh_max: 210, 210
fade_start: 0.6
fade_end: 10.0
probe_count: 5,5
algorithm: bicubic

And then BED_MESH_CALIBRATE will do it’s job:

The bed mesh is situated around 0, nothing unexpected here.

I also setup Klipper Adaptive Meshing & Purging (KAMP) using their setup instructions to dynamically adjust the bed to fit the print size.

Input shaping

The guide references input shaping, which is included in the LDO kit. NERO 3D recommended to wait with input shaping until you’ve printed with it a bit, so I did the input shaping after ~5 hours of printing time.

Input shaping connected.

I didn’t do anything special and just accepted whatever it spat out.

First print

The VORON docs makes the first print seem so simple—just upload the print and eat a bowl of cereal. And I was looking forward to just hitting print and watching it go brr… But of course things wouldn’t go so smoothly.

Problems I’ve had include but isn’t limited to:

Print stopped with Hotend not enough

This happens because the Tap G-code reduces the hotend temperature to 150° when probing to not damage the bed, but then the temperature is too low for printing.

To fix it I had to manually set bed and hotend temperatures after Tap and modifying SuperSlicer to provide these values to the PRINT_START macro as detailed in a better PRINT_START macro.
Filament didn’t load.

And KlipperScreen complains about FILAMENT_LOAD not existing. Sigh.
First layer not sticking to the bed.

A combination of using the wrong temperature and z_offset was to blame.
After a few failed attempts, the filament clogs.

The filament clogged somehow, and I had to disassemble the toolhead to fix it.
Bunch of “Unknown command” errors in the mainsail log.

I assume it’s because Klipper wasn’t selected in the “G-code flavor” in SuperSlicer.
The print coming loose from the bed after a while.

Oh FFS.

I struggled with this a fair bit. I reconfigured z_offset which seemed to work, but maybe it’s extruding too much filament causing the toolhead to hit the print?

After all that trouble I was running into I was expecting for getting an absolutely shit print… But it’s actually not that terrible?

It’s far from perfect, but the lighting is fairly harsh and it looks better in real-life. My friends have shown many 3D prints that look a lot worse.

Functional prints

High on adrenaline I set out to do my first functional print: an exhaust cover for the back of the printer. I’m going to replace it with a proper filter in the future, but I wanted something to cover the big hole in the back when printing ABS, so I wanted to make a temporary in PLA.

But it things can’t go that smoothly:

I messed with the z-offset during print, and the result was this mess.

The printer made some extremely unpleasant sounds, and I was scared that the nozzle was grinding against the bed. I tried to tweak the z-offset during print, but I the sound didn’t stop and I ended up destroying the print.

The nozzle didn’t hit the bed and it was the stepper motors being super loud… But more on that in a future post.

When I re-ran the print and stopped messing with it, the printer spat out a functional print:

Surprisingly good quality.

Other things weren’t that good:

A part needed to mount the Nevermore filter to the extrusion. It’s hard to see in this image, but the top edge is drifting upwards quite a bit.

Simpler models seem to print well, but it struggles with more complex geometry. While I can probably use this Nevermore mount with some sanding, this level of quality isn’t high enough to for example print parts for a VORON.

More tuning is needed.

More print tuning

Ellis’ print tuning guide seems like the go-to guide for tuning your prints. It contains a lot of info, so I won’t write about it too much lest we’ll be here all day. These are the big things I did:

Extruder calibration

This contains the images on how to measure the extrusion distance I was missing from the VORON docs. I redid the calibration but with the top panel removed to get a more accurate measure. Turns out my previous calibration was 10% off. Yikes.
First layer squish

I wasn’t really sure how to do this, but I think the point is to print one square using one z-offset and then change it a little for the next square to see which produces the best print. In SuperSlicer I had to enable the “Complete individual objects” setting for it to print one square at a time.

My previous z-offset using the paper was pretty damn good, but I ended up accepting a -0.01 extra offset (increasing it to -1.050).
Pressure advance

I used the pattern method, although there were so many settings I was unsure about so I don’t know how well it worked out.

Still, I got a value of 0.04 and for some reason I didn’t have any pressure advance setting previously.
Extrusion multiplier

It was super difficult for me to tune this as I wasn’t sure what to look for. I ended up choosing 0.98, but it could’ve just as well be 1.0. Apparently I should do this for every new filament? How bothersome.

There are more things in the guide, but they feel like issues you should keep in mind when printing and not something you tune for from the start. With the massive amount of tuning options both in Klipper and SuperSlicer I’m sure this will be a topic I’ll have to revisit many times.

Some more prints

I printed out another calibration cube and I hoped to have some good comparison pictures here, but truthfully the difference was really small. There were some slight improvements, but not something that shows up well in pictures.

So here are some other parts I’ve printed:

Printer goes brr.

Some of the parts for a HEPA filter housing. If you zoom in you can see some stringing and very visible lines.

The print lines are quite visible.

Despite some artifacts I’m happy with these results, especially since these were new spools of filament that I didn’t do any tuning or drying for (I don’t have a filament dryer yet). The prints were absolutely good enough for me to start printing a bunch of mods for the printer.

Writing lessons learned after writing a book

2024-06-27T07:55:43+00:00

A good writer isn’t born; a good writer is created

It may sound dumb, but one of my reasons for writing a book was to improve my writing ability. Maybe I could’ve practiced on the blog instead, but putting things on paper gave it some added weight I don’t think I would’ve gotten otherwise.

Here are some of my most important writing takeaways I’ve gotten from the process of writing a book. These aren’t original by any means, just things I’ve collected during the process. Many details are from the excellent book On Writing Well: The Classic Guide to Writing Nonfiction that I can’t recommend highly enough.

Writing is a skill

Realize that writing is a skill. A skill can be improved, but it will take conscious effort.

Deliberate practice

Like any skill, the best way to improve it is to practice. Without practice, everything else is meaningless.

But it’s not enough to “just write”, you also need to evaluate your progress and try to notice what you’re lacking and where you can improve.

Be introspective, think about what you’re doing and be your own critic. This is an extremely valuable skill, which will helpful no matter what area you want to improve in.

It can be difficult, here are some questions I try to ask myself whenever I write:

Does the text flow nicely?
Where is the red thread?
Are you making the case succinctly, or is there lots of fluff?
What is the purpose of this section/chapter/paragraph?
Can I remove these words?
Am I repeating myself?
Can I replace any of these words to make it simpler, more succinct, or more correct?
Does the text sound good?
Are the sentences too short? Too long?
Is there sufficient variation in the text?
Are you using the character types; commas, ellipses, hyphens, dashes and brackets?

Remove unnecessary words

My biggest takeaway from On Writing Well is that if you can remove a word or two from a sentence, it’s probably a good idea to do so.

Quite often we use extra words that don’t really add anything of value.
We often use extra words that don’t add anything of value.
We often use redundant words.

It’s not wise to go overboard, but for me it’s been very helpful to keep in mind. If I’m not strict on myself I’ve found that I’m very good at adding redundant words everywhere.

Keep it simple stupid

KISS, a common acronym in software development, is also applicable to writing. Complexity is an alluring mistress, especially for the bright and motivated, but using simpler words and sentence structures is often the better way.

This is especially true in non-fiction where you’re trying to explain a technical concept. By keeping things simpler—often simpler than you’d like—your explanation will be more easily understood by more people.

The reader will be tasked hard enough to understand the subject matter at hand, throwing complicated jargon at them will only make understanding harder.

Yes, it’s difficult to explain a hard subject in simple terms.

If I had more time, I would have written a shorter letter

Attributed to far too many people

Be sure, and make it personal

One common piece of advice I’d like to push back on is to keep the technical writing dry and impersonal. The advice is to avoid “you”, “I”, and “in my opinion” while hedging your bets with “maybe”, “there’s a chance”, and “occasionally”.

It’s much more memorable and interesting to expose your personal opinions and to use strong wording. If you point out every exception to the rule and add dozens of qualifiers to every statement, you will muddy the water so much that the core message will be drowned out.

Instead, focus to deliver the core message to the best of your abilities. Make it colorful and deliver it with confidence. Show your personality; make it interesting, make it funny, and make it memorable. The reader will thank you for it.

Consistency is the most important thing

If you’re going to write a larger piece of work like a book, the most important thing to get it done is working on it consistently.

Anyone can write when motivation runs high, but what separates the wheat from the chaff is if you write when you’re not motivated. It’s exactly like exercising; the people who gets results are those who go to the gym when they don’t feel like it, or who go out for a run even when it’s raining like mad.

It’s comforting to think about very successful authors who only write with the help of inspiration, but I think it’s a trap.

A Song of Ice and Fire is my favorite book series, but I’m sure that if George R. R. Martin had been more focused on writing consistently—instead of waiting for inspiration—we wouldn’t be here still waiting for the next book a decade later, worried that he’ll die before he finishes the series.

And he’s not alone. The Gentlemen Bastard series is just as good, but we’ve been waiting a decade for the next book there too. Although I haven’t read it yet, The Kingkiller Chronicle is another example.

Do yourself a favor and turn yourself into an author that grinds out results, not one who waits for inspiration to strike. The trick is, you can “force” inspiration to come by forcing yourself into writer mode. And the way to do that is by making it a habit.

What worked for me was to allocate 15–30 minutes of writing every morning (which sometimes became much more). Even though I only worked on the book a few hours a week, this consistent work—this habit—worked wonders for me.

Rewrite, rewrite, rewrite

One thing that may hinder the writing process is that the output isn’t great the first time. Most of the time it’s just bad, but often it plainly sucks. And that’s hard to handle, because we don’t want it to suck. We want it to be great!

I think the key here is to let go. Allow it to suck, as long as we get something down to work with. Then you’ll move forward and allow yourself to get into writer mode where the words will flow.

It’s only then that the real writing can start: the rewrite.

I really think that changing, revising, rewriting, and refactoring is the key to writing well. It’s the rewrite that will allow you to:

Make the text fluent.
Make the writing consistent.
Find and fix errors, both large and small.
Reduce fluff.
Ensure that the core message is delivered as clearly and strongly as possible.

In my mind the rewrite is like polishing a gem. Without it, the gem is not much more than a glittering rock— you can see the potential, but it’s nothing special. Yet after the polish it will sparkle and captivate you.

The rewrite is essential to good writing.

Clarity of thought translates into clear writing

Clear thinking becomes clear writing; one can’t exist without the other.

William Zinsser

Writing can be hard sometimes. You have a plan, you get something down and you try to rewrite and mold it to something good. But despite doing everything “right”, what you’ve written still sucks. It’s frustrating.

When this happens to me, the problem isn’t the writing itself—it’s my thoughts.

If your thoughts are muddy and unclear, then what you write will also be muddy and unclear. But if your thoughts are sharp and clear, then the writing will be also be sharp and clear.

In practice this means it’s often better to take a step back and organize your thoughts than to force unfinished ideas on paper.

It may sound like it runs counter to my previous advice of getting something down and then working with it, but I think they compliment each other. Rewriting is one way of organizing your thoughts, but it’s not a panacea.

Have a plan and an outline

Another way of organizing your thoughts is to approach writing top-down instead of bottom-up, where you focus on the big picture and then drill down.

A good way is to formulate a high-level plan, and creating outlines is a simple and effective way of getting some structure. This may not be the best approach for a novel, but for the type of technical writing I do creating outlines has served me very well.

Organizing a book

On the highest level the chapter titles can serve to guide you (both the reader and the writer) through the book, and doubly so if you organize them in sections (real or imagined). For example, even if you’ve never seen my book before, the three main sections should give you a good idea on what the book is about and the journey it’ll take you through:

What is a cryptocurrency?
Properties of a cryptocurrency
How do cryptocurrencies work?
Look out for snake oil
What is money?
Are cryptocurrencies money?

Better digital payments
Cheaper & faster
“Undesirable” businesses
Freezing of merchant accounts
Uncensorable donations
For the unbanked

A better currency
The financial crisis, bad loans and bailouts
The blind leading the blind
A defective system
Private money
A global currency

With this high-level outline all I had to do was to fill it in. Yeah, that’s simplifying the reality a little, but it’s actually pretty close to how I wrote my book:

I had a bunch of ideas that I turned into chapters.
I wrote one chapter at a time (not necessarily in order).
I revised the planned chapters over time.
I rewrote a lot.

It may sound too simplistic and too perfect—surely you cannot plan so well that this is all there is to writing a book? But remember that this is only a rough plan to guide you, in reality the process will be messy. Moving, rewriting and throwing away chapters will be necessary.

Organizing chapters or blog posts

This approach with first creating an outline also works great inside the chapters or in a longer blog post.

I may start with a simple list of things I want to say, but my goal is to turn that into headers and sub-headers. As an example, these are the headers from the post Battling burnout:

Is it burnout, depression or both?
No apparent reason
Red flags
Seeking help
What was the actual cause?
Things that helped me
The only thing that really helped me
Are you ever cured?

Burnout was quite a difficult subject for me to write about, and I didn’t know how to approach it. But with an outline I got past the block and could start to chip away at the post.

Perfectionism is a blessing and a curse

On one hand it’s good to strive for perfectionism. Even if you never reach it, the act of trying to make something as good as it can possibly be will increase the quality.

But on the other hand, trying to be perfect may be a hindrance. It may be paralyzing and I suspect it’s a big contributing factor for the famous “writer’s block”, where the writer is severely slowed down or even becoming unable to produce anything at all.

Perfect is the enemy of good

I felt this effect after I had put way too much time designing the web version and the physical version of the book. I think the result was really good; the book looks beautiful and is pleasing to read, but I burned out hard when I had to do it again with the eBook version. 2 years after the book was done, the eBook/PDF are still not available from regular stores, and truthfully I don’t know if I’ll ever gather the energy to do that.

The problem is that my standard was (is?) too high. I wanted it to look as good as possible, but chasing perfection only led to burnout.

I’m still trying to be satisfied with things that are good enough instead of wanting perfection. But it’s hard.

Summary

To summarize, these are my main takeaways that totally coincidentally corresponds to the headers in this post:

Writing is a skill that can be improved.
Establishing a writing habit is crucial.
Rewriting is very important.
Clear up your thoughts to clear up your writing.
Outlining the book and chapters helps you and the reader.
Don’t strive for perfection.

I am by no means an authority on this matter; these are just some lessons that I learned when writing a book.

Let's build a VORON: Software

2026-01-29T10:45:03+00:00

The build continues, now in a little more familiar territory.

Firmware flashing

To flash the firmware I had to order a microSD card reader. With that on hand the flashing wasn’t difficult. The VORON docs walks you through the installation very well.

Mainsail

I chose to install Mainsail instead of Fluidd simply because I liked the screenshot a little more. From what I understand they’re very similar and the choice doesn’t really matter. I flashed it using pi-imager.

It was great to see the display turning on and being able to ssh to the Pi—such a relief!

The Raspberry Pi and the display are alive and kicking, although the display is rotated 180 degress.

After installing the Octopus firmware on it’s SD card and adding the device to ~/printer_data/config/printer.cfg I could start messing around with the Mainsail web interface.

[mcu]
# This is my serial, not yours
serial: /dev/serial/by-id/usb-Klipper_stm32f446xx_140045000F50535556323420-if00

The Mainsail web interface.

KlipperScreen

It’s good to see my old friend the Linux login prompt on the display, but that’s not really what we want here. Instead we should install KlipperScreen to be able to control the printer via a user-friendly UI. I installed it using a manual install, but in hindsight I maybe should’ve KIAUH. Oh well.

To rotate the screen you edit /boot/config.txt according to the LDO docs:

# Make sure this line is commented
#dtoverlay=vc4-fkms-v3d

# Add these 2 lines to the end
display_lcd_rotate=2
dtoverlay=rpi-ft5406,touchscreen-inverted-x=1,touchscreen-inverted-y=1

The display is rotated and uses KlipperScreen.

Home Assistant

Home Assistant integration with plenty of controls and sensors.

Of course, I had to hook up the printer to Home Assistant. This was easily done using the Moonraker Home Assistant plugin via HACS.

Maybe I’ll actually make a functional dashboard with it… Some day.

Initial config

It’s not enough to install the firmware, there are quite a few things in ~/printer_data/config/printer.cfg that needs to be changed. I used the LDO config as a starting point and went from there. To not bore you to death I’ll try to only document the noteworthy changes I made.

And—very importantly—I installed Neovim on the Raspberry Pi I using snapd. While I have the configuration files in a git repo, it’s far easier to ssh and edit the files directly.

Be careful

As advised in the VORON initial startup docs when testing these things (motors in particular) you should have a tested way of stopping the printer if something goes wrong. Like if you’re ramming the toolhead against the edge or something.

I… Didn’t do this and just saw the “Home” button and thought—I wonder if it moves when I press this?

Luckily the XY motors worked as expected (I hadn’t configured Z yet) but it could’ve been very bad.

Bed

The bed—through the SSR—is connected to HE0, corresponding to the PA2 pin (BED_OUT is PA1):

[heater_bed]
# SSR Pin - HE0
heater_pin: PA2

Hotend

The hotend is connected to the non-standard HE1 (since my cable didn’t come with a fork spade to connect it to BED_OUT, as advised in the LDO wiring docs):

[extruder]
# Heater - HE1
heater_pin: PA3
sensor_type: PT1000

It also took a long time for me to figure out the correct sensor_type value. None of the values in the common thermistors documentation worked for the Phateus Rapido, but I found an off-hand comment somewhere that PT1000 was the correct type.

Tap

Configuring Tap was straightforward, I simply followed the steps in the Updating your Klipper config for Tap instructions.

The one thing that confused me was this this line about PROBE_CALIBRATE:

You’ll need to manually calibrate the probe’s Z offset by using PROBE_CALIBRATE.

Turns out it’s the process described in configuring the Z Offset Adjustment in the VORON documentation, only substituting Z_ENDSTOP_CALIBRATE with PROBE_CALIBRATE. I ended up with this line in the config:

#*# [probe]
#*# z_offset = -1.195

To see if Tap is working I warmed up the enclosure a little bit I ran PROBE_ACCURACY:

probe accuracy results:
    maximum -1.219375, minimum -1.221250, range 0.001875,
    average -1.220500, median -1.220625, standard deviation 0.000612

According to the docs the standard deviation falls within the expected range of a well-built machine:

For well-built machines you can expect to see between 0.0000 and 0.0008 standard deviation.

I doubt that I built everything that well, but I’ll take it!

I’m a little confused what the negative numbers mean; is my z_offset too low, causing the probe values to be negative? Or are they uncorrelated and this is completely fine?

Extruder

It’s weird. In some cases you can move mountains and solve the most difficult problems in a flash, but at other times you’ll stumble on the smallest pebble.

And I stumbled hard on inserting filament into the extruder.

I know I checked it when assembling the Clockwork 2, but by god I couldn’t get it to grab on the filament. After a long time of fiddling, and considering if I should just disassemble it all, I somehow got it to work.

I think it was a combination of the extruder direction being inverted and some filament getting stuck, but I just don’t know. I’ll file it under user error and forget about it.

[extruder]
dir_pin: PF0 # Inverted by removing the `!`

I don’t understand how you’re supposed to properly measure the amount of filament when calibrating the extruder, the VORON docs isn’t particularly clear about it. What I did was to pull it taught and try to measure from there, but I fear it wasn’t that precise.

Maybe it would be easier without the top panel?

The small red mark was 100mm away from the edge of the black holder part before I tried to extrude 100mm of filament. I think this is good enough?

[extruder]
rotation_distance: 20.41105599   # After recalibration

I hope my first print will look better than this mess?

Panel mounting

You may have noticed that the above pictures had panels on them. That’s right, to be able to heat soak the printer I had to have the panels, so I quickly installed them.

It was easier to align the doors with the printer lying down.

How are you supposed to get the right polarity and stick the part on the correct spot on the door? Just place the magnet and then push in the part.

I’ve been impressed with the build so far, but I’m not impressed with the doors. The doors doesn’t have foam tape between them and the frame unlike the rest of the panels.

I wonder why that is? I worry that they will scramble against the frame and it won’t make a good seal, which I think could’ve been avoided. I’ll probably look for mods for the doors; maybe I’ll replace the doors with a magnetically mounted panel or something.

Slicer

I do feel my 3D printing inexperience when I have to setup yet another thing: a slicer. There are quite a few options, but I didn’t care to try out them all—I simply wanted to get up and running smoothly.

I picked SuperSlicer because it works on Linux, has a custom Voron Design profile to import, and seems fairly popular.

Viewing the layers is weirdly satisfying.

I was initially super confused on how to see the layer preview. Turns out there was some error with only using the preconfigured Voron v1 250 0.4mm config I selected in the configuration wizard. Importing the Voron Design profile and selecting it seems to have resolved the issue.

What’s left?

The next thing is finally to print something. Unfortunately I don’t have any filament other than the small sample that came with the LDO kit, so it’s back to waiting for a shipment to be delivered.

And after that there are still things left to do:

I’m missing some printed parts that I need to print out myself.

For example I need a rear exhaust cover (although I plan to add a HEPA filter there) and spacers to mount the handles.
Tuning, tuning and more tuning.

Prints needs to look good.
Mod it.

It feels wrong to build an incredibly moddable printer and leave it without any mods. I’m trying not to keep the “to-mod list” short but I can already sense that I’ll fail miserably.

It works, but it’s not done yet.

Let's build a VORON: Wiring

2026-01-29T10:45:31+00:00

Dread it. Run from it. Wiring arrives all the same.

It’s time for the part of my VORON build that I’ve been dreading: the wiring.

It’s scary because I really have no clue what I’m doing, and mistakes can be very costly and time-consuming.

I’ve taken my time to double- and triple-check everything, and I took lots of pictures. I ran into some issues I’ll document here, but this post will mostly be filled with pictures to gawp at.

Cable chains

There wasn’t a ton of instructions on the cable chains, but I felt it went well.

It was fiddly, but not the end of the world.

If we make the wires pretty from the start, we can just continue like that?

Main power

Yes, I guess I should’ve connected main power before connecting the motor cables, but the octopus isn’t connected yet so it’s fine…

I triple-checked that I don’t mix colors and I checked again that I connected it to the outlet properly.

Note that it says “TO 5V PSU” on the PSU cable. I think that’s a typo…

The green light turns on! I’m glad it didn’t burn up yet…

Octopus power

According to the docs, the SSR should connect to HE0 instead of BED_OUT. Fine.

The Octopus has the required power, but I didn’t check if it turns on at this point…

I mixed the 3 and 4 inputs on the SSR, but luckily I caught it when double or triple-checking.

Breakout cables

I’m following LDO’s wiring guide and the breakout cables are next.

Wrong hotend cable?

When I was about to connect the hotend cable I noticed a problem.

In the wiring guide it says that I should connect the hotend to BED_OUT:

Breakout PCB Cable label (breakout) Controller Cable label (controller)

HE0 **** HE0 HE0/PA2 BED_OUT

****The BED_OUT port in the Octopus controller carries more current than the HE ports, this allows you to use super high power hotends such as the Phaetus Rapido.

Breakout PCB	Cable label (breakout)	Controller	Cable label (controller)
HE0 ****	HE0	HE0/PA2	BED_OUT

But the cable that I got doesn’t fit:

The hotend cable has “pin” type connectors.

What I want is “U” type connectors. (I later found them on Amazon as “fork spade” terminals.)

My suspicion is that I got the wrong cable because the V2.4 wiring guide specifies that the cable goes into HE0 and SSR goes to BED_OUT, while the Trident has it reversed.

I complained about this to 3DJake (where I bought the kit from), who reached out to LDO where I got the response that they’re sorry, but I can connect the hotend to HE1 and change something in printer.cfg to make it work.

Not ideal as I do have the Phaetus Rapido, and according to LDO’s V2.4 errata it’s advisable to switch:

It has been reported that the Rapido hotend (by Phaetus) draws a large amount of current during initial heat-up. If you are using this hotend with our kit, please consider swapping the bed and hotend connections at the Octopus side.

I’m not thrilled about it, but I guess I need to find some spade terminals and change the wires later.

Full picture

A better overview of the wiring with breakout cables (and other things).

Raspberry

The Raspberry Pi uses 5V from the Octopus via some PCBs:

The Raspberry Pi is connected.

Other small details

The major things are done, but there are more things that needs to be fixed.

LEDs

I got a cute little PCB for connecting two LED strips in the kit.

It’s neat. I like it. (I later moved the LED wire so it goes down in the front instead of behind the belts.)

I wasn’t sure how to mount the LEDs, so I added a wire cover below the LED strips to give it a platform to attach on.

Controller fan

I should’ve gotten another PCB mount to mount the fan PCB, but I didn’t get one from the print-it-forward service. Maybe I should’ve mounted the fan PCB with the mount instead of the LED PCB, but I couldn’t be bothered.

Some tape to prevent shorts.

It was hell to get it mounted. Why didn’t I do this before adding wires…?

The wire is stuck between the fan and the plastic part, oops.

Display mount

I didn’t manage to get the display mount to work properly. The screws didn’t align properly and the display cover constantly fell off.

There’s a space here that I couldn’t close no matter how hard I pushed.

The screw hole is slightly off.

I had to use tape to keep it all together:

Tape for the cover so it doesn’t fall off.

Tape for the sides.

It works I guess but I need to print new mounts when I get the printer up and running. I believe the problem is that I have the 2.1 version of the display, while the mount is for the 2.0 version.

The bed

I had delayed installing the bed, but with the wiring needing to be done it was time to install the bed.

I was a bit worried about applying the magnetic sheet, but I think I managed to do it without any bubbles.

The bed is installed and ready.

Maybe the Z-endstop is completely unnecessary as I’m going to run Tap? Probably, but as it’s already installed I won’t bother ripping it out now.

Missing Toolhead cables

When assembling the stealthburner I couldn’t connect the hotend to the toolhead PCB because the connectors didn’t match, and I also didn’t have a cable from the Tap PCB to the toolhead PCB. It was time to rectify that.

I didn’t do it when building the toolhead because I didn’t have the tools for it. So I ordered wire strippers, a crimping tool, JST connectors and some wire from Amazon.

Crimping was fiddly but after a dozen attempts I think I got it down.

After I painstakingly created the Tap cable—with a 3-pin JST on each end—I noticed that the Tap PCB required a smaller connector than the ones I had. Oh no… Do I have to order another connector kit?

But luckily the Tap kit came with one such connector. (Please don’t break it.)

So I tried to change it… But after trying for some time I noticed that the wires I had were too thick, and didn’t fit this smaller connector. I nearly destroyed the connector while trying to insert the wires…

Things aren’t going my way, maybe I need to order (and wait for) new wire?

But wait!

Remember how I complained about the hotend cables having the wrong connector? Turns out the Rapido comes with extension cables with the connectors I wanted. The thermistor extension cable has thinner wires and the same JST connector I have…

Maybe I could shorten that cable and use the leftover wire for the Tap cable?

A shortened extension cable for the hotend thermistor.

Behold! My glorious cable!

I’ve spent an embarrassing amount of time and energy just to create this single cable. It makes me really appreciate that the LDO kit comes with pre-made wiring, I can’t imagine the frustration if I had to create all wiring from scratch (there’s a lot of it).

One problem I still have is the excessive wiring coming out from the toolhead, and I don’t really know what to do with it.

Too many cables. Should I try to hide it inside the cable chain?

Maybe I could try to shorten them all… But I’m not skilled or brave enough to try.

It’s not pretty… It sort of ruins the nice looking toolhead don’t you think?

Gantry racking

When building the printer I’ve been jumping around a little, and somewhere in the middle of the wiring I decided I should try to solve the gantry racking.

I had noticed that the gantry catches a little when moving it around, and I got a tip from the VORON forum that I should rack the gantry to try to fix it.

And it did solve the issue! The movement isn’t as smooth as in NERO 3D’s video, but at least it doesn’t catch anywhere.

Lack of range for the toolhead

After installing the bed and racking the gantry, I noticed a big issue with the toolhead: it doesn’t reach the corners of the bed and the bed doesn’t reach up to the toolhead.

The toolhead is at max x, but it’s far from the edge.

The toolhead doesn’t reach the edge on the y-axis either.

I tried to raise the bed as high as possible, but it doesn’t come close to the toolhead, let alone raising it for tap to function.

Turns out I had made a mistake when installing the cable chains, as they’re all too short and they max out too soon, stopping the movement.

There were 4 extra links in the kit, but I didn’t know what to do with them so I forgot about them and took for granted that the three cable chains would work as-is. Maybe this is assumed knowledge, but when installing them—and before running the wires through—I should’ve checked the range of motion to be sure they were long enough.

Now I had to break open the chains and add the extra links afterwards. This was super annoying because I had to pull more wire to the chains, meaning I had to undo all the wiring work for all the motors and toolhead cables.

Opening up the xy cable chains.

I added two links to the z chain and one link each to the x and y chains. For x and y I also had to add some extra space by offsetting them so the chains aren’t flush to the edge of the extrusion holder or toolhead.

I had to add some extra spacing on the x and y chains to get the required range of motion. I wish I hadn’t clipped away the tab, so I could zip tie the cables to it.

It’s all coming together

All the wiring is in place. (You may notice an unconnected cable in the upper right, it’s for the Nevermore filter I haven’t built yet).

I may clean it up a bit after I’ve verified that things work. It may not be r/cableporn neat, but it could be worse.

A better overview of the wiring with skirts and all.

Let there be light

With everything prepared I closed my hands, curled my toes, and clenched my ass and turned on the power…

And the lights are glowing! Huzzah!

The lights are glowing, and there’s no smoke from the Octopus. I disconnected the hotend and Raspberry as a safety measure before turning it on.

The Raspberry Pi also has some lights when turned on.

The status lights are promising, but I can’t tell for sure before flashing.

I designed my own keyboard layout. Was it worth it?

2024-11-27T09:30:28+00:00

Almost two and a half years ago I embarked on the journey to change keyboard layout. At first I tried out existing ones, but it didn’t take long before I figured it’s better to develop my own—and things went downhill fast from there.

(Some) combos of the T-34 layout.

But now that I haven’t made any changes to the layout for over a year, I think it’s time for some introspection and ask the dreaded question: was it worth it? And should you—the dear reader—do the same?

What were my goals in creating my own?

I essentially had two big goals with my layout:

Relieve my RSI

I had started to develop RSI in my right hand that I really wanted to cure. Especially in the area of my right thumb, I wanted to relieve my right hand in general.

I also wanted to reduce pinky usage—particularly for my right pinky that I had broken earlier and felt very weak.
Optimized for my usage

I had three main use-cases I wanted to optimize for:
- Vim usage
- Write Swedish and English
- Coding in a myriad of different programming languages

Did I succeed with the goals?

For the first I can say that in combination with the Ferris—a split keyboard with 34 keys—my RSI did indeed get a lot better.

The Ferris, my keyboard that helps with RSI.

As for the second—if it’s optimized for my usage—I don’t really know how to answer. When I was in the middle of designing the layout I probably would’ve pointed out the low SFB values (Same Finger Bigram), the redirects and generated interesting graphs and heatmaps.

But now I’m satisfied with saying that it just feels really good.

You have to be a little crazy

It’s quite extreme to design your own layout and I think you have to be a little crazy to do it. I know I was.

There I was; awake in the middle of the night carrying our baby in a harness, standing in front of the computer trying to learn this new stinking layout while ignoring his cute smile, hoping he would fall asleep soon.

I was trying to learn the BEAKL 15 layout but it just wasn’t working for me. Maybe I could tweak it a little—so I did. Maybe I could tweak it some more? I did that too.

Eventually the sleep deprivation took over and I abandoned it and started to design my own layout.

And that’s how I mostly designed my layout: I designed, tweaked and learned it in the middle of the night as I was trying to get our little kid to sleep.

I don’t think you have to be crazy to design a keyboard layout—but it probably helps to overcome the healthy fear of overoptimization and diminishing returns.

What could I have done differently?

I’m not motivated to make any large changes or experiments with the layout now, but there are some things I wish I had tried out more:

One shot shift on the thumb instead of E.

The one shot shift seems like such a fantastic feature, but that would require me to move E away from the thumb, which would snowball into an entirely different layout.

Using a combo for one shot shift is another thing I’d like to try that wouldn’t be too invasive.
Home-row mods.

Home-row mods is another very popular feature that would unlock a lot of extra space on the keyboard (as it would allow secondary effects on long-press instead of shifting and reduce the amount of combos I have).

I did try it out a little bit, but maybe I could get used to it with more effort?
32 keys instead of 34.

It would be fairly simple to go down to 32 keys, with only a single key for each thumb. The idea appeals to me, but I don’t think there are any practical benefits for me to do so. I might do it in the future if/when I build a new keyboard.
More practice.

I’m not close to my old QWERTY speed of +120 wpm simply because I got bored of practicing typing.

Would I recommend you to create your own layout?

Let’s summon Betteridge’s law of headlines that says:

Any headline that ends in a question mark can be answered by the word no.

I wouldn’t go quite that far, but you need to realize that there’s very real diminishing returns of completely designing your own layout.

In the vast majority of cases it would be good enough to switch to something like Colemak-DH or Hands Down, and depending on what you’re after switching to a more ergonomical keyboard would probably suffice.

Or maybe not do anything at all. Lot’s of people have been happy with a regular keyboard and QWERTY.

When should I make a change?

I think it comes down to two things:

What benefits are you looking for?
How motivated are you?

First an important note: changing the layout because you want to type faster will probably not work out. Chances are you’ve been using QWERTY for many years and the amount of practice you need to catch up to and surpass your QWERTY speed will be staggering. Most will burn out long before reaching that point (including me).

The biggest benefit I see with an alternative layout is comfort. If you’re worried about RSI, and you foresee yourself spending a few decades more in front of the computer, then switching layout might be a good idea.

Another benefit is if you have some special requirements with your layout. In my case for example I wanted to be able to comfortably type Swedish on a tiny keyboard, and just using Colemak-DH or something wouldn’t really support that well because I couldn’t fit åäö on the base layer.

But with my own layout I could have åäö easily accessible (by toggling between ()_ and åäö with a layer).

And of course, if you find the idea of designing your own layout interesting or fun, you should totally do it! I honestly thought it was really fun (even though learning it was a pain).

A layout is more than alpha characters

Symbols are very important for a programmer.

Something that people seem to miss with alternative layouts—even people designing them—is that a layout is much more than where the alpha characters goes.

I’ve spent much more time on where to place the symbols, how to handle numbers, what type of modifiers I want, a navigation layer, and shortcuts than the base layer, and that’s also where most of the benefit of my layout comes from.

Symbols for example are very dependent on the programming languages you use, so there’s lots of benefit to a symbols layer optimized for those. It’s much more productive to spend time on optimizing symbols placement than to try to improve Colemak-DH, which is already pretty darn good.

Even simple things like adding a navigation layer (with arrow keys under your fingertips) or moving Escape are hugely beneficial. And of course, avoiding the gymnastics of pressing Ctrl in the lower left corner with the pinky is a big win.

My recommendation

If you want to make a change to your setup, these are my recommendations sorted from least to most effort:

Get a programmable keyboard.

For example, moving Escape to Caps Lock and behave like Ctrl when held are great modifications for a regular keyboard. (You might be able to do that on the OS level too.)
Get a more ergonomical keyboard.

I think a split keyboard with tenting is a great start. If you want to go the extra length try to make it smaller.
Tweak the big buttons to avoid large and awkward motions.

For a Vim user, remapping Escape is a classic. Ctrl, Shift, Alt, and Enter are also good candidates for moving to a thumb button, a combo or a Mod-Tap.
Add a navigation layer (or two or three).
Start tweaking the symbols and numbers (and other things you can come up with).
Use an alternative layout such as Colemak-DH, Hands Down or MTGAP 2.0.
Make your own completely custom layout.

You don’t have to do everything at once and you can try out the different levels to see how painful and time consuming the changes are.

How do you even learn a new layout?

The T-34 base layer. There’s not a trace of QWERTY left.

Say that you’ve decided to learn a new layout. Now what?

The simple answer is that you just need to practice. But here are some tips to make the process more efficient:

Don’t look at a reference of the layout and use blank keycaps.

Being forced to remember is painful but recall helps you learn faster.
Practice in small bursts.

Small and frequent sessions are better than few but larger ones.
Learn to touch type.

Might as well learn it properly from the start.

Note that you don’t have to be super strict. I press the upper corners with my ring fingers instead of the pinky for instance (because I’m weird and it feels better).
If you want to retain the ability to type QWERTY, use a different setup.

A different keyboard for a different layout can help keep them separate. Pressing space with a different thumb is another trick that may help.

There are very good online tools to help you learn a layout. Here are some I like:

It’s important to stress how much motivation matters. Even though I feel that I want to pick up the practice again when I’m writing this, I don’t think that will actually happen as I’m not really motivated enough. But if you start using a new layout you have to practice, and you have to practice quite a lot at least at the beginning.

My practice died off hard a year ago when I got good enough, around 70 wpm.
(Some of this was spent practicing numbers and symbols.)

FAQ

You dodged the question; Was it worth it?

Hell yes it was. The massive amount of nerd points alone is enough.
I still want to use QWERTY on a regular keyboard

If you continue using it regularly you’ll be fine. After 2 years I can still type faster with QWERTY on my laptop than with my own layout on my ergonomical keyboard, and I can use both an English and Swedish layout (symbols move around and åäö are added).
How long does it take to learn a new layout?

Impossible to say as we’re all different. The first layout I learned took ~16 hours of practice time on keybr until I got up to ~40 wpm and with the second layout it took ~12 hours. At ~40 wpm I felt I could write without wanting to throw the keyboard through the monitor.

Beyond that it depends on how diligent you are with practice.
Sounds like a massive effort, I don’t think it’s worth it?

If this sounds too much for you, it probably is.

I rationalized it by saying that I’ll spend a few decades more programming, so a big investment now will pay for itself with time as long as there’s some benefit.

(This is indeed the trick on how to waste time on Very Productive™ things like rewriting your Neovim setup.)

The killer features of the Steam Deck

2024-07-01T05:28:09+00:00

In the beginning of the year I gave myself a late Christmas gift and bought a Steam Deck for myself. There were two main reasons I decided to buy it:

I wanted my kids to play games instead of passively consuming endless amounts of YouTube.
I wanted to combat my burnout and depression by picking up gaming again.

And boy did it deliver. The Deck is probably the most impressive thing I can remember buying since… I don’t know, maybe my first smartphone?

I think it impresses me so much thanks to these five killer features:

Killer feature #1: Sleep mode

For me, as a father of three where my gaming time is very limited and can be interrupted at any time, the one truly outstanding feature of the Deck is the sleep mode.

It works like this:

Press the sleep button, and the Deck will turn off in about a second.
Press the sleep button again, and the Deck will turn on and resume exactly where you were, in a second.

This has worked perfectly for me for every game I’ve tried. And it’s revolutionary.

It’s no exaggeration to say that without this one feature, nothing else could’ve allowed me to find time to game. The ability to instantly put it down and go to the screaming baby has been crucial, and being able to instantly teleport myself back into an immersive gaming experience has been fantastic.

If you’re a parent who wants to game, this is the feature you’ve been waiting for. Even if you’re not a parent this is an amazing feature.

If a portable gaming device doesn’t have this, don’t bother.

Killer feature #2: The steam library

The second feature I want to highlight is access to Steam. It’s the largest distributor of PC games by a wide margin, and the amount of games available on the platform should be enough for anyone.

And I must mention the Steam sales. Many games are heavily discounted over the year, and you can even get AAA games for cheap if you’re patient enough. Contrast this with Nintendo where the games are never on sale.

To be sure, the Steam Deck is a handheld and won’t be able to run the most demanding games and it also runs Linux so it will have compatibility issues with a lot of games. But the device is surprisingly powerful, and the work Valve has put in to make Windows games work on Linux is astounding, so a lot of the games will work outright or with some minor tweaks (by changing the Proton version or tweaking graphics settings).

Just to give you a taste, here’s a variety of games that are installed on my Deck that all work great:

LEGO RPGs

LEGO City Undercover. It’s GTA but for kids!

The LEGO games have been popular, although they’re a bit too difficult at times for my kids. LEGO Star Wars: The Skywalker Saga, LEGO Jurassic World and LEGO City Undercover have all been very well received.

Overcooked! 2

As great as the LEGO games are, Overcooked! 2 is my favorite game for kids. The beauty is how it forces you to collaborate with each other in a very nice way.

Forza Horizon 5

Forza Horizon 5 is another game that works great on the Deck. It hasn’t been played as much as other games because it’s still a bit too difficult, even with driving assist.

Teenage Mutant Ninja Turtles: Shredder’s Revenge

I went with the boys to watch Teenage Mutant Ninja Turtles: Mutant Mayhem on cinema. They, and I, loved it. Shredder’s Revenge has also been very well received, but alas, once again, it’s a little too difficult for my young kids. Or should I say; they haven’t learned to handle defeat properly yet.

Faster than Light

I rediscovered one of my favorite games of all time, and spent 231 hours to beat it on hard with all the ships. Make no mistake, this game is really hard.

Parkitect

Parkitect is an ode to one of my favorite games of all time: Rollercoaster Tycoon. And I must admit, Parkitect is even better.

Grim Dawn

People were hyping on Diablo 4 so much. Me being so over Blizzard, I instead played some Grim Dawn. According to the internet it’s an objectively better game. Regardless if that’s correct, the game does work very well on the Deck.

(I actually haven’t played it that much—I didn’t enjoy the ARPG grind.)

Tony Hawk’s Pro Skater 1 + 2

I have very fond memories of playing Tony Hawk games on the GameBoy Advance and on the PC. I couldn’t help myself and had to relive those memories.

And the game runs like a dream.

Killer feature #3: Steam input

You may have noticed that I listed some games you wouldn’t think worked well on a handheld. Parkitect for instance heavily relies on the mouse, and Faster than Light is a decade old game that’s also mouse based and doesn’t have an gamepad specific mappings. What gives?

With Steam Input the Deck allows you to remap any key or command to whatever input you want. Combine that with the Deck’s excellent trackpads and you can comfortably play any game (well, maybe not RTS games or FPS games like Counter-Strike).

As an example here’s my configuration for FTL:

Some notable features to mention:

Right trackpad as a mouse.
Buttons for the most common utilities (doors, teleport, hacking, return to stations…).
Sticks for number rows (weapon and drone selection) and M for mindcontrol.
Shift and control are relegated to back buttons.
In FTL there are two pause buttons (space bar and mouse middle click). By pressing them quickly in succession you can micro pause and advance the game just a few frames. I’ve bound a single button on the Deck to do this, with a small delay between.

This may seem scary, but for most games you won’t need to change anything. But when you do, Steam Input is a godsend.

Killer feature #4: An open platform

What first got me excited about the Deck was actually that the Deck might represent the first big leap forwards in making Linux a valid gaming platform. And thanks to Proton I think that’s absolutely true, but the real value for the Steam Deck owner is that it’s an open platform and you can do what you want with it.

Want to use other game stores?

Sure!
Do you want to install native Linux games not on Steam, like Veloren or Clone Hero?

They work great!
Want to watch a movie instead of gaming?

Launch desktop mode and it’s just a regular computer.
Don’t want to bring your laptop, but need to do some development on the go?

Just setup your environment and go. You can program using the virtual keyboard, but it sucks in a major way, so bring a keyboard.

My Neovim config running on the Deck. See this post on how to install Neovim on the Steam Deck.
Do you just want to install Windows?

Absolutely. Do you want to install it on the SD-card or on the Deck itself?

I’m a strong believer in that you should be allowed to do whatever you want with your device, and with the Steam Deck you can.

Killer feature #5: Emulation

The last feature I want to bring up ties into the previous: the Steam Deck is an amazing platform for emulation.

I’m new to emulation, but it was very easy to setup using EmuDeck. The device itself is powerful enough to run basically any older game, and even many popular Switch games.

You may ask, if Steam already has tons of games, why bother with emulation?

I’ve got a few reasons:

Many good games aren’t on Steam (Nintendo, I’m looking at you).
Nostalgia.
Experience the classics.
Some gaming experiences aren’t replicated well by the newer styles of games.
If you look at the many “best games of all time” lists out there (which I did when I asked myself what have I been missing out on during my years of not gaming) you’ll find that a lot of them are from older systems.

For example, maybe you’ve heard of The Legend of Zelda? I have, but I’ve only ever played a single game (Link’s Awakening). This is super unfortunate because some of the Zelda games are rated as the best games in history.

But if you want to play through the Zelda series you’d have to collect almost every Nintendo console.

Or you can play the whole series, including the newest Switch games, on the Deck.

I admit this is a contrived example because I haven’t done this yet (I plan to play through the most popular ones at some point), so here’s a list of games that we’ve actually played:

Mario Kart 8 Deluxe

Both of my boys (6 and 3 years) love Mario Kart. The best feature is probably the driving assist, so the younger kid can play even if all he does is press the jump button and shout.

Super Smash Bros

Mario Kart has been our most played game, but it’s quickly being overtaken by Super Smash Bros that my older boy has been playing non-stop for weeks now.

But I understand him, it’s an awesome game and it was my favorite Nintendo game when growing up.

Pokémon Snap

My oldest is in a Pokémon craze at the moment. Since he hasn’t learned to read yet the “real” Pokémon games are a bit too much to play by himself, but taking pictures of Pokémon works very well.

Punch Out

Punch Out is pure nostalgia for me. Amazing.

Pokémon Unbound

Speaking of nostalgia, of course I need to mention Pokémon. I had difficulty deciding what Pokémon game to play—there are a few—and then I just happened to discover the rabbit hole of Pokémon ROM hacks.

According to my pre-study Pokémon Unbound is the best ROM hack there is, so that’s where I started. But there’s a lot here to explore. Maybe I’ll get there eventually.

Isn’t there more to the Steam Deck?

There’s absolutely more to like about the Deck. For instance:

It’s a handheld you can dock.
The processor is very capable given the amount of power it uses.
You can connect a lot of things to it; controllers, fight sticks, Wii guitars etc.
The trackpads are very good as a mouse replacement.
The year of Linux has finally arrived!

While nice, they don’t quite qualify for my killer features list. And most importantly: I wanted to keep it simple and only select five killer features.

Let's build a VORON: Bed & electronics

2026-01-29T10:45:17+00:00

I’ve made a lot of progress on my VORON. Electronics and other stuff are installed to the degree that I’ve begun wiring, but I’m going to separate the wiring into it’s own post.

This will be a short post about bed preparation and installing electronics components.

Feedback from the VORON forum

I’ve gotten some feedback from the friendly VORON forum on some issues I should take a look at:

Verify that the frame is built square (I’ve tried to do so).
The front Z motor mounts were swapped.

Front Z motor mounts now have the VORON logo at the front.
I should check the gantry racking to get rid of it catching (I haven’t done that yet, I want to finish up the wiring first).

Misaligned extrusion

When I was going to insert the top cover I noticed that the Z motor didn’t fit into the cutout, and I discovered that the center extrusion wasn’t right in the middle:

I have a small memory that I measured it, and the spacing was off by a little, but then maybe I forgot to do something about it? Just goes to show how my plans of taking the build slowly and trying to be thorough doesn’t prevent me from doing silly mistakes.

The buildplate

Even though the assembly manual says that you should install the buildplate at this point, I decided to skip it. I got the tip from Nero3D to only install it at the very end, even after wiring, because it’s heavy and makes the printer more annoying to flip around during the build.

These screws were extremely hard to screw down… Maybe I need better tools?

Other than the small screws murdering my fingers, installing the final extrusions was straightforward.

Bed mount installed.

Electronics

And now the part of the build I’ve been most worried about begins; avoiding blowing up the electronic components.

Well, that requires wiring so maybe I’ll blow it up in the next post.

I couldn’t find the LDO Beefy Raspberry Pi Mount in my printed parts. But why would I need it, the standard parts work well?

The big electronic components are laid out.

Again, laying out the components were no big deal. Embarrassingly, the most trouble I had was locating the microSD slot for the Raspberry Pi (it’s underneath).

Next up is the dreaded wiring.

Let's build a VORON: Toolhead

2026-01-29T10:44:55+00:00

Since the last update I’ve made some good progress:

All the motors are installed
The x-axis and belt are installed
Tap is installed
The toolhead with Stealthburner + Clockwork 2 is also installed

Purple means Pretty.

I’ve run into a few problems on the way that I’ll try to document, but other than that the build has been really fun so far. The design of Clockwork, Stealthburner and Core XY is really cool and it’s been very interesting to assemble them to see how it all comes together.

X-axis and belts

I didn’t encounter any issue assembling the x-axis or the belts.

I’m slightly worried that I messed something up as moving the gantry from front to back has a very slight hiccup in the middle, but it doesn’t come up when I move it from back to front or if I move it slowly.

Toolhead

Up to here it’s been fairly straightforward. Just follow the official assembly guide and don’t forget to read the LDO Build Notes/FAQ.

But assembling the toolhead (or printhead, what’s the difference?) was not so simple and I had to reference several sources:

This was confusing and I managed to trip up on several things.

Tap

My plan wasn’t actually to build Tap from the start, and instead rely on the standard inductive probe. Even though the kit stated the probe was included, it wasn’t listed in the parts checklist so I assume it wasn’t included in the kit?

No big deal. Instead of building the Klicky probe just to tear it down and replace with Tap later, I decided to build Tap from the get-go.

Tap in progress.

The first thing that confused me was the printed parts. In the Tap manual the main printed part had the VORON logo, yet my part did not. There were some other minor differences, so maybe I got the printed parts from an older revision of Tap?

But the manual also didn’t seem updated to the latest version as it was missing items from the errata (which I only discovered after assembling Tap). There were no mentions of the tall reinforcement screws (that I could install afterwards), belt covers (that I didn’t use) or how to install the 2 extra magnets (that now lie unused).

I got the Hardware Kit + OptoTap rev2.4.1 5v or 24v OPB666N HIGH TEMP + D2HW “kitchen sink” kit, but the amount of unused parts worries me.

Still, I got it assembled and it seems to work? Crosses fingers.

Tap is mounted and ready to go.

Clockwork, mod or no mod?

For the top part of the Stealthburner, I did the component prep and then I noticed that the LDO documentation refers to a revision that called for using alternative printed parts.

Okay, okay. I redid installed heatset inserts on those parts as well and went to work. It went well until I had to install the PCB and the printed mount (from the revision) didn’t fit.

Alright, improvisation time:

I didn’t find how to attach the PCB in the documentation, so I improvised with heatset inserts. I feel so clever!

Of course later on I found a plastic part that was made for the job and replaced the mount:

This is how the PCB is supposed to be mounted.

… And then I found out why it didn’t fit. There was this line in the revision:

THIS MOD NO LONGER REQUIRED for V2.4 Rev. C - the kit includes the Stealthburner PCBs and works with the stock parts.

I’m not building a V2.4, so I didn’t think it applied to me. But now I think it was a bad assumption. I’m building the Rev.C of the Trident, which seems to have the new version of the PCB that fits the standard parts.

At first I was going to leave it like this cause why bother, but then I read a note hidden in the wiring guide that for the new PCB I needed to use a specific cable cover that of course wasn’t compatible with the modified parts…

So I redid everything.

And then I discovered that the specific cable cover I had was missing the thermistor holder:

My printed part doesn’t have this holder.

Darn it.

But I think (hope) it should finally be finished enough; I can probably tuck the thermistor somewhere to get it to print.

Now I think it’s built as it should be?

Installing a hotend

When I was going to install the Rapido UHF hotend that I got I had a small panic.

I couldn’t find any VORON documentation on how to install it (the assembly manual only shows another hotend). From Rapido I got a very nice looking card pointing to https://www.phaetus.com/rapido-hotend that led nowhere.

And when I tried searching for it online I found that Rapido UHF actually wasn’t supported!

Oh no!

No matter how I look at it, this won’t fit? How are you even supposed to attach it? It does say P-RPD but I don’t understand…

I was sure I read that the UHF version also contained HF parts, but maybe that was wrong? Do I need to buy new printed parts from someone? Or maybe a new hotend? Buy the Rapido HF instead of the UHF I got?

I’m off watching reviews on the newly released Rapido 2.0…

Luckily I found a YouTube video showing how to install it:

Oooh, you just remove the top part (and don’t install the UHF parts) and it fits!

Crisis averted; all is well.

Stealthburner assembly

Before connecting it all.

It was slightly scary that you had to break off and cut into a fan—I really didn’t want to mess it up permanently. But after watching NERO 3D do that I managed to collect the courage to do it as well.

When I was going to plug in the hotend I noticed it didn’t connect to the PCB properly:

Nope, the cable doesn’t go into that connector.

Tap also didn’t have a cable I could just use, so now I had to mess with the wires. Tough luck, I didn’t have any 2-pin or 3-pin connectors (or extra cable), so I left this until later.

That’s a future me problem. Screw that guy.

Missing some minor parts

At this point I discovered I’m missing a few things:

Printed part for the input shaper.

Maybe I just haven’t found it, but either way it’s not a big deal. Input shaper seems to be a temporary thing that you should remove after some calibration, so I guess I can just tape it temporarily.
The LDO specific cable cover I mentioned before.
2 Locking Washer, M5

Maybe I can find two of these things in the hardware store somewhere? Ordering these online for only two pieces seems like a hassle.

I’ve contacted 3Djake about the washers, maybe they’ll find some replacement parts for me. But even if they don’t it’s no big deal.

I thought I was missing the neopixels and the inductive probe, but they were hiding in a bag in the cable box.

How does it feel?

Even though I’ve had a fair amount of trouble sorting through documentation and other issues, the progress has felt good. It’s really fascinating to assemble things like the belt system and the toolhead and see how they come together.

Let's build a VORON: Build start

2026-01-29T10:45:40+00:00

The end goal, as rendered by Autodesk’s online viewer

I’m not sure where it came from, but it was suddenly very important that I got myself a 3D printer. Maybe it was an important insight, but it maybe it was only a fix idea I got that somehow became this all-import thing.

Either way, I now have lots of parts for a VORON Trident 250 and I figured I’ll try to document the journey of building it (or failing to).

Why a VORON?

The first step to building a 3D printer is deciding on what printer to build. This was roughly my selection process:

An Ender 3 seems like a cheap and popular printer, maybe that’s a good place to start?
Hmm, the quality of an Ender 3 doesn’t seem that great and the internet says that you’ll spend a lot of time to tweak and modify it until you get something good.
The Prusa MK4 has just released, and their printers have historically been really solid.
Prusa seems open-source friendly (well, sort-of) but I’d probably want an enclosure as well…
There is a Prusa enclosure, but holy crap it’s large and expensive. Maybe there’s something else that has a built-in enclosure?
Damn, this VORON thing looks amazing and at around the same price range of the Prusa.

And that’s how I ended up wanting a VORON.

Now, a VORON is a really cool printer and there are lots of things that drew me towards it:

It’s completely open source.
The footprint is small and it comes with an enclosure.
You can mod it to your hearts content.
You build it from scratch, meaning you’ll get the knowledge of how to mod and repair it (I hope).

At this point it didn’t matter that I’m a complete 3D printer noob and that a VORON is not recommended for beginners. I wanted one, and settling for something else would just leave me filled with regrets and I would’ve just bought a VORON later anyway. So I bought the printer I wanted directly instead.

I got the 250mm version over the 300 and the 350 simply because it’s much easier to fit in my office and in my storage. I’m not planning to make any larger prints so the larger sizes felt unnecessary to me.

Now as I said a VORON isn’t a beginner printer, but I did take some countermeasures to hopefully make the build more manageable for me:

I Bought the expensive LDO kit as it’s as close to a “just build it” kit you can find.
I went with the Trident over a 2.4 because the Trident is supposedly a little easier to build.

I also made one choice that probably makes it a little more difficult for myself:

Even though the kit comes with the Klicky Mod, I want to use VORON Tap because I got this idea that Tap would be better.

At the moment I’m not planning to install Klicky at all, but we’ll see how that goes.

As I don’t have a printer I used the print it forward service to buy the printed parts for the printer.

What I got

I’ve got a bunch of boxes

These are the items I’ve ordered:

LDO VORON Trident 250
Phaetus Rapido Plus Hotend UHF
VORON Tap hardware kit
Printed parts

Preloading the t-nuts

Assembling the frame wasn’t too bad. I took it easy to make sure I put the extrusions the right place, rotated as they should be.

But my big worry—that still isn’t resolved—is the preloading of the t-nuts. Apparently LDO’s combination of nuts and extrusions is very tight and you can’t (or it’s super difficult) to insert them after assembling the frame, so you have to insert them before.

There is a helpful video, but I’m still very worried that I’ve placed one of them wrong or missed some, and I have to disassemble the frame at a later stage.

Assembling the frame. I really, really hope that I’ve placed the t-nuts correctly.

Heatset inserts

What to do with the heatset inserts? The LDO kit comes with a heatset insert tool… But it didn’t fit the soldering iron I had. What to do?

Turns out you don’t need it, and you can just use the soldering iron with a regular tip:

This works great. Except that I shouldn’t use this particular part in the build. Oops.

Set screws

Another source of great worry for me was this line in assembly manual:

Loose set screws account for the majority of issues that our users report. Save yourself hours of troubleshooting and apply thread locker to all set screws during the build.

And I don’t even know what a “thread locker” is.

After some research time it seems I really do want a thread locker, but I live in a really small community and I don’t know where to buy this (except ordering online and waiting for a week).

Well maybe nail polish works just as well? So armed to the teeth with fire red ~~lipstick~~ polish I was ready to tackle the problem…

And I see that thread locker has been pre-applied to the set screws. Maybe it will pay off with the more expensive kit after all?

Greasing the rails

Greasing the rails is another thing that bothered me, because grease (and cleaning) wasn’t found in the kits I bought. My partners little brother came to the rescue and found a NLGI 1 grease (as recommended by the LDO guide) and some break cleaner to clean the rails.

That’s great, but I also don’t have a syringe so I ended up removing the carriage and applying grease that way. To my surprise they were full of small balls that had a tendency to jump out at me.

The balls jumped out on me. I hope I found them all? (No, I later found some missing balls…)

At first I applied a bunch of grease on the balls as well, but then carriage moved really slowly over the rails, so in the end I applied a little grease only in the middle.

They still don’t move as smoothly as they did when I opened the boxes, I hope it’ll be okay…

Best part of the build so far

This is Loke’s hand. I don’t want to publish pictures of my kids, so this is what you get.

So far the best part has been that both of my boys (5 and 3 years) have been helping me out, and they’ve been really enjoying being there and helping me tighten some screws.

I really want all my kids to build and be creative. Be it LEGO, sand castles, programming or 3D printers. So far this project has been promising, and at least the older one is super hyped about the prospect of building his own Nerf guns. I also want to build some toy robots and—when they get older—maybe a Quadcopter or two.

Where I’m at right now

The frame is built and I’ve added three of the rails.

I’ve had the printer for almost one month and progress has felt slow.

Computer upgrade

2023-10-09T18:04:30+00:00

After 5 years or so I’ve made a large upgrade to my desktop, and this post contains details and some pictures about the process.

It was time

I didn’t really want to do an upgrade right now, but I felt I had to do it. Sometimes the lag had gotten very noticeable, for example when running multiple Neovim instances with several different LSPs in Rust and Elixir.

That was frustrating, but the biggest reason was this ghastly discovery in my liquid cooling loop:

If you can’t spot it (no shame on you), there’s a huge ball of gunk that’s stuck hanging down beneath the graphics card, and it almost seems like it’s blocking the liquid from passing through properly (more on that later).

I know that you’re supposed to check on your loop once a year or so. But things just sort of happened. We moved, I worked and we got three kids. Sometimes it’s just hard to take time for these things, but now I just had to do it or I might not have a computer left to work on.

The new things

CPU: AMD Ryzen 9 7950X
RAM: Kingston 32GB DDR5 5200MHz CL40 FURY
Motherboard: ASRock B650 PG Lightning
Fans: 8x Noctua NF-A14 PWM 140mm
SSD: Kingston KC3000 M.2 2280 NVMe SSD 2TB
Water cooling: New tubing, fitting, a large reservoir and probably something more

Taking apart the computer is a pain, so I decided to do an upgrade as well. I landed on a Ryzen 9 7950X, a beast of a CPU that should leave me with no slowness complaints (well, as few as possible I guess). With that I also had to get a new motherboard and new DDR5 RAM memory.

The fans were some gravy as some of the old fans occasionally stopped spinning and the SSD was just an impulse buy (it was big, fast and cheap).

I redid the water cooling loop a little as well. The position of the reservoir/pump combo wasn’t good and I wanted to try to get a position for better airflow.

Tearing down the loop

Building the liquid cooling loop was all fun and game 5 years ago, but now it was time to pay. I had installed a drain, but it failed to drain most of the liquid. There was something in the tube that blocked it, and the drain was mounted too high so it couldn’t drain the lower radiator properly.

Come on little disgusting thing, I know you want to come out.
I failed to drain most of the liquid trough the drain, so things got messy.

Why couldn’t I be satisfied with air cooling?

Rebuilding the loop

Building a computer isn’t hard, but adding in a custom loop makes the build take twice or thrice as long.

But to be completely honest, it’s also a little fun.

I used loop cleaner + superflush to properly clean the system. Because of the previous gunk, I was worried about dirt in the GPU block, the pump and radiators. It’s hard to be sure, but I think I got rid of most of it.

I was a good boy and added a fill valve to easily fill the loop.

How the valve connects to the reservoir.

I liked the idea the valve, but the first time I tried to fill up using it the liquid didn’t enter the reservoir properly and things got really messy.

At first I thought that the tube had an U-bend in it, but what ultimately fixed it was me replacing the reservoir top so I could open up an air intake.

It’s… Not perfect

Despite my best efforts of planning the loop, the drain system ended up sucking. While I managed to drain most of the liquid, there were some parts like the lower radiator and the reservoir where the liquid got stuck, and I had to resort to flipping the computer upside down and shake to get rid of it.

Yet again.

Plenty of liquid left in some weird places.

It’s alive

Building a computer is a little scary because you don’t know if it’s going to work when you’re done. And especially so with this kind of build, where disassembling would be a major endeavor.

But it worked! And it’s glorious!

Ah, the beautiful cable management.

My 3-year old really enjoys this view.

The Noctua fans are amazing.

Yes, I replaced all the fans.

Language spec in code blocks

2024-07-09T12:10:58+00:00

Even though I just recently restyled the blog and wasn’t going to touch it, there was one thing I wanted to add, but it felt a little bothersome so I skipped it. It was to display the highlighted language in code blocks:

The code spec displays what programming language the code block contains.

As it happens, my little girl—the fountain of joy that never stops giving—decided to not sleep last night. (I can’t really be angry with her, she’s only 10 months and she’s getting sick.)

So there I was, carrying her in a harness and trying not to play with her because I just want her to fall asleep. I usually do this in front of the computer so she can listen to music and fall asleep (her favorite is In Flames: Only for the Weak). But that’s also time I can use to to work on weird things, and in this case I reworked the code block display.

Previously, code blocks were generated like this:

<pre>
  <code class="highlight viml">
    ...
  </code>
</pre>

The problem was that I couldn’t just add a div inside the pre tag because I want the code to be scrollable when it overflows:

pre {
  overflow-wrap: normal;
  overflow: auto;
}

But then the contents cannot exist partially outside of the tag, since that would be hidden, and scrolling would also move the language spec element.

So instead I used another div to wrap everything:

<div class="code-wrapper">
  <div class="lang viml"></div>
  <pre>
    <code class="highlight viml">
      ...
    </code>
  </pre>
</div>

This allows me to use the ::before pseudo-class to insert the language description depending on the class (viml in this example). See the relevant styling:

.code-wrapper .lang {
  // Move the language spec to the right.
  display: flex;
  justify-content: right;
  align-items: flex-start;
  // Use the ::before pseudo-class for the actual language spec.
  &::before {
    // Match the code block style.
    @include font-size("s");
    font-family: $code-font-family;
    color: var(--melange_a_ui);
    background-color: var(--melange_a_float);
    // Give the text some surrounding space.
    padding: var(--space-3xs) var(--space-xs);
    border-radius: var(--space-3xs) var(--space-3xs) 0 0;
    // Offset so it partially overlaps the code block and move it toward the middle a little.
    position: relative;
    top: 1.2rem;
    left: -2rem;
    // This ugly looking things tries to remove the height of the child element,
    // so we get consistent spacing around the code block.
    margin-block-start: calc(var(--flow-space) - (2ch + 2 * var(--space-xs)));
  }

  // For each class insert the corresponding language text.
  &.python::before {
    content: "python";
  }
  // etc.
}

The reason I used a pseudo-class for the language description instead of directly like <div class="lang">viml</div> is to hide it from other reading modes, such as the RSS feed, Firefox’s reader view or screen readers. These readers typically remove most or all of the styling, but then the language description would appear in the middle of nowhere without context. Using a pseudo-class is a bit annoying as I need to insert some CSS for every single language I want to display, but it provides a better experience for people using these readers.

I also changed the font to my custom Iosevka for the website as well. Now I’m happy with how things look.

Giving the blog a facelift

2024-07-09T12:14:25+00:00

When I rewrote the blog in Rust I tried not to touch any of the styling, but some things annoyed me:

It wasn’t pretty (even ugly in some parts).
No dark mode support.
Some elements were broken, for instance images or code blocks overlapping the header when it was floating to the side.
I wanted to promote my series and projects more.

A better landing page

The old landing page was too simple for my taste.

My thinking when I last updated the style was to keep things as simple as possible. I think I mostly succeeded with that, but I really don’t think the landing page was pretty.

So this time I wanted to:

Make it prettier
Spotlight posts, series and projects

As it happens I had remade the archive, projects and series pages already, and it just fell out well to simply include some partial contents and shove them into the homepage.

I’m sure you could make a bunch of improvements, but the design fulfills my goals at least.

Automatic dark mode

I’ve been using dark mode when coding for ages, but it’s only recently I tried to switch everything to dark by default.

Some sites use a dark mode switcher button, but I think it’s better if the sites detect your preference automatically. It’s surprisingly easy in CSS using prefers-color-scheme, and here’s a small example:

:root {
  --color-text: black;
}
@media (prefers-color-scheme: dark) {
  :root {
    --color-text: white;
  }
}

// Then you just use the variables like so:
.element {
   color: var(--color-text);
}

To test this out, in Firefox (and I’m sure other browsers) you can change your preference and the site will update immediately:

You can change dark mode preference in Firefox.

I prefer the dark variant, but the light is also quite nice.

New colorscheme

I recently fell in love with the colorscheme melange-nvim for Neovim. This was a big deal for me so naturally I want to use the colorscheme everywhere.

This doesn’t just apply to the code highlighting, but to the colorscheme of the entire blog itself. Go big or go home.

Systematic CSS

People love to hate on CSS, and maybe I’m damaged but I quite like CSS. Things have come a long way since I styled my first webpage. Back then you had to do all types of weird incantations even to do simple things, and IE 6 still found a way to mess it up.

While there are browser incompatibilities today, it’s not nearly as bad and the browsers today support a lot of really nice features that makes modern CSS quite neat.

Here are some things I utilized this time around:

Fluid size scales

Sizing fonts is more annoying than one might think. One thing you’d like to do is to have a slightly larger font for larger screens, and smaller sizes for smaller screens (such as your phone). It makes it easier to read on both devices, but it’s a bit annoying to setup.

Previously I used media queries, but a neater solution is fluid size scales. I just used some generator I found online and it seems to work well:

// From https://www.fluid-type-scale.com/
:root {
  --font-size-2xs: clamp(0.51rem, 0.03vw + 0.5rem, 0.53rem);
  --font-size-xs: clamp(0.64rem, 0.12vw + 0.61rem, 0.7rem);
  --font-size-s: clamp(0.8rem, 0.25vw + 0.74rem, 0.94rem);
  --font-size-m: clamp(1rem, 0.45vw + 0.89rem, 1.25rem);
  --font-size-l: clamp(1.25rem, 0.76vw + 1.06rem, 1.67rem);
  --font-size-xl: clamp(1.56rem, 1.2vw + 1.26rem, 2.22rem);
  --font-size-2xl: clamp(1.95rem, 1.83vw + 1.5rem, 2.96rem);
}

Now it’s not perfect, and on my monitor I feel the jump from m to s is a bit too big, but this is good enough (for now).

I also utilize a fluid scale for spacing:

// From https://utopia.fyi/
:root {
  --space-3xs: clamp(0.31rem, calc(0.31rem + 0vw), 0.31rem);
  --space-2xs: clamp(0.56rem, calc(0.54rem + 0.11vw), 0.63rem);
  --space-xs: clamp(0.88rem, calc(0.85rem + 0.11vw), 0.94rem);
  --space-s: clamp(1.13rem, calc(1.08rem + 0.22vw), 1.25rem);
  --space-m: clamp(1.69rem, calc(1.62rem + 0.33vw), 1.88rem);
  --space-l: clamp(2.25rem, calc(2.16rem + 0.43vw), 2.5rem);
  --space-xl: clamp(3.38rem, calc(3.24rem + 0.65vw), 3.75rem);
  --space-2xl: clamp(4.5rem, calc(4.33rem + 0.87vw), 5rem);
}

Lobotomized owl

It’s always fun to find weird things that are also very useful. The lobotimized owl selector is just that.

// Hoot-hoot
     * + *

For a great explanation see My favourite 3 lines of CSS, but in short it enables you to set consistent spacing between child elements.

It’s super useful, and I use this mixin for it:

@mixin flow($space: false) {
  & > * + * {
    margin-block-start: var(--flow-space);
    @if $space {
      --flow-space: $space;
    }
  }
}

Why didn’t I use the stack + flow as described in the linked blog post? Honestly, I had forgot about it and only searched for the post now as I’m writing this. Their way is probably better, but I can’t be bothered to refactor it right now. 🤷

Measure to limit text width

A big readability tip is to limit the line length to 45–90 characters. I do this using max-inline-size and a variable to control the length that’s on by default:

:root {
  // Measure limits the width of text to be more readable.
  --measure: 60ch;
}
* {
  // Limit everything to --measure by default.
  max-inline-size: var(--measure);
}
// Opt-out instead of opt-in, makes it a bit more manageable honestly.
html,
body,
div,
header,
nav,
main,
footer,
pre code,
pre {
  max-inline-size: none;
}

If I want to use a different line length I can just alter --measure, or override max-inline-size if I don’t want it for some elements.

CSS Grid is awesome

I haven’t used grid that much previously, but it’s one of these newer features that makes CSS a pleasure rather than a pain to work with. You can accomplish things that were previously hard to do with just some commands. Here are some examples of how I use grid:

Image gallery: 3-column layout

A 3-column layout with grid.

figure.gallery {
  display: grid;
  grid-template-columns: repeat(3, 1fr);
  grid-gap: var(--space-3xs);
}

Tags: variable number of columns

If you want to fit as many columns as possible, you can use this setup that I use on the tags page:

.tags {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(12em, 1fr));
}

Post: overflow images and code blocks

Constraining the width of text is good, but I wanted to allow images and code blocks to extend past that a little if needed. See this image:

Most content exists between grid lines 3 and 4, but the image may span between lines 2 and 5, essentially overflowing the article width.

In my previous design I used media queries and relative offsets to accomplish it, but with grid it’s easier and fluent. With this setup you can also allow an image to extend the entire screen (“full bleed”), but so far I haven’t find a use for it.

The main article includes this wrapper:

@mixin full-bleed-wrapper {
  display: grid;
  grid-template-columns:
    1fr
    minmax(0, var(--overflow-size))
    min(var(--measure), 100%)
    minmax(0, var(--overflow-size))
    1fr;
  max-inline-size: none;

  // Place all content in the main content area by default
  & > * {
    grid-column: 3;
  }
}

This sets up 5 areas: the main middle content, constrained by --measure, the overflow with --overflow-size and the rest. On narrow screens everything except the content collapses to zero width.

Then you override grid-column for the items you want to overflow:

// For overflowing the article.
@mixin overflow-bleed {
  width: 100%;
  grid-column: 2 / 5 !important;
  // This resets the --measure constrain I have on by default.
  max-inline-size: none;
}
// For items that should span the entire screen.
@mixin full-bleed {
  width: 100%;
  grid-column: 1 / -1 !important;
  max-inline-size: none;
}

Mixins like these are why I prefer sass over raw CSS, it makes creating these systems more practical and maintainable.

What am I not satisfied with?

I quite like sitting and making small tweaks until I like how things look. Even if the process can be slow I still enjoy it.

But I really don’t like how brittle it feels. I’ve tried to namespace rules, so in css/local/_tags.scss I have rules only for the tags page:

article.tags-list {
  .tags {
    // ...
  }
}

But most things are shared across pages, and if I make a change somewhere I may accidentally break some obscure styling somewhere. Having unit tests for the layout would be nice, but I’m not keen of maintaining a rendering of all pages and doing an image diff to find errors.

Of course I could make everything local, but then I’d miss out on the usefulness of the general rules, and the maintenance burden would be even higher.

Maybe I’ll just leave the styling alone for the next couple of years until I feel I want to remake everything again?

Rewriting my Neovim config in Lua

2025-01-19T07:16:57+00:00

This screenshot betrays just how much productive time was wasted setting this up.

I’ve got tons of things to do; clean the bathrooms, prototype an idea for a SaaS and ponder world peace. So naturally the procrastination took over and I rewrote my Neovim configuration in Lua.

But why?

No, but seriously, I’ve had my Neovim configuration since before Neovim existed and it’s been working fine. Why would I then rewrite it, and using Lua to boot?

My config has collected a lot of cruft over the years, and it was about time to do a cleanup. So I figured the best way was to do it all from scratch, only adding things from the old config if I really needed them (and if I knew what they were doing there!).

I was also curious on how well it would work to configure Neovim using Lua instead of Vimscript, and if there were some new fancy things I was missing.

Just a few plugins or many?

As is common knowledge, there are these great divides in the developer community. Issues so great that it makes the Israeli-Palestinian conflict feel like kids fighting in the sandbox.

I’m of course talking about the age-old questions of Vim vs Emacs, if you should use an IDE or a Text Editor and gasp if you should use tabs or spaces.

And even inside the Vim community we have our own great question: should you amass as many plugins as possible, pimping out your Vim so it can be mistaken for an IDE, or should you keep it minimalistic, staying true to the Raw Vim experience?

So where do I stand in this? On which hill will I die on?

As I’m writing this I’m up to 77 plugins, with a bunch more on my “plugins to check” list, so I guess I’m dying on the “use all the plugins” hill.

If that makes you feel like I’ve betrayed Bram the creator, then my only defense is this:

I tried, but I failed.

Where to start?

The inspiration for this was ThePrimeagen’s video on 0 to LSP: Neovim RC From Scratch that I watched several months ago.

While ThePrimeagen’s video was great as inspiration (look how easy it is!), I don’t think it’s the best configuration to reference. I instead used other sources:

LazyVim is a popular Neovim distro that you can use if you don’t want to configure everything from scratch or—the horror—anything at all.

A distro is absolutely not my thing, but the LazyVim source was quite useful as a reference for me.
Distros may be overkill, a better alternative might be the small configurations that are made to help you get going with your own config.

Take a look at kickstart.nvim and TinyVim for example.
There are lots of people who have their configs on GitHub.

I used catgoose as the config was really clean, including lots of plugins to inspire me.
Speaking of plugins, neovimcraft is a good site to find plugins.
dotfyle is another great site with plugins, configurations and the fantastic This Week in Neovim newsletter.

Structured configuration

One of the big problems with my previous setup was that init.vim was huge and it was hard to organize it. I tried using folds and having a logical grouping, but it never felt good.

With lua and lazy.nvim you can organize settings and plugins in different files quite nicely. This is how I did it:

I wanted to have a split of config/ and plugins/, so ~/.config/nvim/init.lua just loads ~/.config/nvim/lua/config/init.lua:

require("config")

Then in ~/.config/nvim/lua/config/init.lua I load the configurations and plugin manager:

-- Setup <leader> and <localleader> before loading plugins
require("config.leader")

-- Use lazy.nvim for plugin management
require("config.lazy")

-- Continue with the configuration, possibly overriding settings that some
-- plugins might set.
require("config.options")
require("config.colorscheme")
require("config.keymaps").init()
require("config.commands")

With lazy.nvim you can split up plugin specifications into separate files:

-- Basic lazy.nvim setup as copied from the readme
local lazypath = vim.fn.stdpath("data") .. "/lazy/lazy.nvim"
if not vim.loop.fs_stat(lazypath) then
  vim.fn.system({
    "git",
    "clone",
    "--filter=blob:none",
    "https://github.com/folke/lazy.nvim.git",
    "--branch=stable", -- latest stable release
    lazypath,
  })
end
vim.opt.rtp:prepend(lazypath)

-- Load plugin specs from lua/plugins/*.lua
require("lazy").setup("plugins", {
  defaults = {
    lazy = true, -- Default to lazy loading, optional
  },
  change_detection = {
    notify = false, -- I find the config changed notification super annoying
  },
})

This will automatically load any .lua file in the lua/plugins folder. For example this is lua/plugins/replacer.lua:

return {
  "gabrielpoca/replacer.nvim",
  opts = { rename_files = false },
  keys = require("config.keymaps").replacer,
}

Incredibly nice when you have lots of plugins, and some have large configurations (like lspconfig, treesitter or cmp).

One last big thing is I wanted to have all global keymaps in one single file. lazy.nvim supports adding keymaps in the plugin specification using keys = { } option. I accomplished this by simply returning a “module” table from config/keymaps.lua:

M = {}

M.replacer = {
  {
    "<leader>rq",
    function()
      require("replacer").run()
    end,
    silent = true,
    desc = "Make quickfix editable for replacing in",
  },
}

-- And other plugin keymaps like this
M.trouble = {
  ...
}

return M

Not all keymaps can be defined using the lazy.nvim specification, in which case I returned a function and called that where applicable. For instance for LSP:

M.buf_lsp = function(_, buffer)
  local map = vim.keymap.set
  map("n", "<localleader>D", vim.lsp.buf.declaration, { silent = true, buffer = buffer, desc = "Declaration" })
  map("n", "<localleader>d", vim.lsp.buf.definition, { silent = true, buffer = buffer, desc = "Definition" })
  -- etc
end

And set it up in plugins/lspconfig.lua in the on_attach callback:

local on_attach = function(client, buffer)
  keymaps.buf_lsp(client, buffer) -- Will add the keymaps when LSP attaches to the buffer
  lsp_status.on_attach(client)
end

One last thing; for the regular mappings you don’t want to just remap them in config/keymaps.lua because multiple files will run require("config.keymaps"), so I wrapped it in an init function:

M.init = function()
  local map = vim.keymap.set
  map("n", "<leader>p", '"*p', { silent = true, desc = "Paste from mouse" })
  map("n", "<leader>P", '"*P', { silent = true, desc = "Paste before from mouse" })
  -- etc
end

Which is why config/init.lua looked a bit weird:

require("config.options")
require("config.colorscheme")
require("config.keymaps").init() -- Notice the weird init() call here
require("config.commands")

It’s true that keymaps.lua has grown quite large and isn’t super easy to read. Maybe I’ll break it out into more keymap files (config/keymaps/lsp.lua etc) in the future, but right now I think it’s nice to have all the maps in one single file.

Favorite new-to-me plugins

While doing the rewrite I went through my existing plugins to see if they were still relevant, or if I could replace or just remove them. And of course, if I could add some new ones.

I won’t create a list of my favorite plugins, as it would be boring to see yet another list with LSP, treesitter and cmp, I’ll instead highlight some good plugins that were new to me:

lazy.nvim: A modern plugin manager

Observe the glory of a modern package manager

I’ve been using vim-plug as my plugin manager since forever. It’s been working well, but I figured I should try one of these newer managers to see if I was missing something. And boy, did I. lazy.nvim has some really nice features that I now can’t live without:

Split plugin specifications in separate files as I wrote about earlier in the post.
Specify plugin dependencies.
Pin plugin versions.
Track plugin versions in lazy-lock.json, so you can identify what plugin version breaks your setup so you can pin it to a known good version.
Lazy loading. It’s nice to have for those rarely used but heavy plugins.

melange-nvim: An amazing colorscheme

It’s just pleasing to my eyes.

The design idea is that control flow should use warm colors and data should use cold colors. So here, functions are warm yellow and strings and data are colder purple and green.

I’ve been a gruvbox user since I started using Vim almost 15 years ago. I’ve tried tons of different colorschemes but nothing has ever come close to gruvbox for me. Most of the popular colorschemes are just too blue, or have too little (or too much) contrast or I just don’t like them for some random reason.

I had almost resigned to becoming a gruvbox-lifer, unable to ever change colorscheme.

And then, melange-nvim appeared. And it’s glorious! Now after many long years, I’ve finally switched to a new colorscheme, and I’m content.

(No, switching from the original gruvbox to gruvbox.nvim to gruvbox-material and back again doesn’t count.)

Also a shout-out to kanagawa (dragon, the dark variant without blue background) which is the only colorscheme I’ve found that I didn’t eject in horror after 5 minutes, except for gruvbox and melange.

Sorry kanagawa. It’s not you, it’s me.

vim-cool: Turn off search highlight

Forget <C-l>, this plugin will turn off search highlight when you move your cursor away from it. Simple, but raises the quality of life a lot.

conform: Format on save

I’ve used neoformat before, but had some issues where I saved then quickly stared modifying something, but then formating kicked in and removed my changes.

With conform I haven’t had these issues, and configuration was quick and easy and LSP fallback is super sweet. Excellent plugin.

nvim-treesitter-textobjects

A common misconception about treesitter is that it only adds semantics to syntax highlighting:

BASE and REPEAT are enum members, while the other keycodes are defined as macros.

I think that’s very nice, but treesitter is more than that. And a great example of that is nvim-treesitter-textobjects where you can operate on treesitter nodes. I have for example:

]f jump to next function.
]c jump to next class.
]g jump to next function or class.
<leader>s swap next parameter.
if textobject for inner function. So cif would delete the function body and enter insert mode.
ax textobject for outer comment, to easily delete/change comments.

The beauty is that these work on treesitter nodes, so they work equally well across languages for functions like fn myfun() { }, function myfun() ... end or a def myfun() do .. end. (Given that the treesitter implementation supports these options. Markdown doesn’t have the concept of a function for instance.)

Neogit: Git management

magit is widely regarded as the best Git client/integration there is. When I used Emacs for work (oh yes, the horrors) I did use magit and yes it was great (although too slow on Windows).

I don’t think I need to say more than that Neogit is magit, but for Neovim, and it is also great. (It doesn’t have feature parity with magit yet, but it’s good enough to have replaced fugitive for me.)

alpha-nvim: Dashboard

My startup screen

I’m going to be honest here: I’ve always thought that a dashboard was unnecessary fluff and people who used them were just pimping Neovim for the sake of pimping.

And now, I also use a dashboard.

While it’s something I could absolutely live without, by now I’d rather have it than not.

Okay, saving a keypress by using f instead <leader>f isn’t a big deal. And yeah, showing lazy.nvim stats is probably unnecessary.

But having a list of keymaps that I should internalize is actually really nice. It helps remind me of these cool new keymaps I’ve added, so they don’t get forgotten for years until my next config rewrite.

Yes, the list of keymaps is currently just hardcoded in the dashboard config. But I would like to implement keymap tracking and use it for spaced repetition. Maybe even have a floating window on startup that you need to clear every day, similar to “flashcards”. This is a nice idea for a plugin that I may or may not write in the future…

flash.nvim: Navigational plugin

Once upon a time there was vim-sneak that added the motion s to jump to any location by specifying two characters. It was great, and it spawned a slew of other similar plugins that expanded on the idea. (I’m not sure this is completely historically accurate, but it felt like a good narrative.)

The plugin I’ve landed on is flash.nvim. What I really like about it is the idea of typing as many characters as possible. Even with sneak I didn’t always arrive where I wanted, so having the option of typing out more things felt good for me.

Extra functionality such as doing a “remote yank” (search, yank something, then cursor goes back to where it was) and enhancing f/F/t/T// is just gravy.

nvim-colorizer: Colorizer plugin

What are these colors again? It’s the palette of melange-nvim of course!

After vim-hexokinase got archived I had a minor panic. It was a neat little plugin that highlighted colors inline, but without altering the highlight of the colors themselves, which is what all the other colorizer plugins seemed to do.

Luckily I found nvim-colorizer that does the same, and without having to build an external binary like hexokinase that always managed to break for some weird reason.

I love when things just work.

Custom behavior

Becoming a Pokémon master by collecting all the plugins is great, but one of the benefits of Lua over Vimscript is that it’s a much nicer language for general programming. While I haven’t really taken advantage of it that much yet, I’ve made a small addition that worked quite well for me.

I’m trying out neorg as my knowledge base and note taking and I’ve separated it into four folders:

~/norg/projects
~/norg/areas
~/norg/resources
~/norg/archive

I don’t remember where I saw this recommendation, but it made some sense to me at the time.

What I want to do with this is either:

Open a file in one of these folders
If no file exists, create and open one

I could make shell scripts and use fzf as a fuzzy finder, but as I kind of live in Neovim I wanted to do this from within Neovim.

Using telescope (fuzzy finder) and plenary (path helpers) this is what I came up with:

-- Find files using telescope in a subfolder of `~/norg`.
-- @param base_folder: string: base folder
M.open_norg = function(base_folder)
  local action_state = require("telescope.actions.state")
  local actions = require("telescope.actions")
  local Path = require("plenary.path")

  local folder = vim.fn.expand("~/norg/") .. base_folder .. "/"

  require("telescope.builtin").find_files({
    attach_mappings = function(prompt_bufnr, map)
      -- Creates a file using the telescope input prompt.
      -- Useful to quickly create a file if nothing exists.
      local create_file = function()
        -- It ain't pretty... But maybe it's good enough...? T.T
        local current_picker = action_state.get_current_picker(prompt_bufnr)
        local input = folder .. current_picker:_get_prompt() .. ".norg"

        local file = Path:new(input)
        if file:exists() then
          return
        end
        file:touch({ parents = true })

        actions.close(prompt_bufnr)
        vim.cmd("e " .. file .. "| w")
      end

      map("i", "<C-e>", create_file)
      return true
    end,
    cwd = folder,
  })
end

I’m sure this can be improved upon in many ways, but it serves the purpose at least. <C-e> is used to create the file, as sometimes telescope finds similar files so creating a new file if telescope is empty doesn’t really work.

Another related function I wanted is to create a weekly journal file. There is support for a daily journal in neorg, but I specifically wanted a weekly one. This is how I made it:

-- Open a weekly journal in `~/norg/areas/weekly_journal/`.
-- Create using a template from `~/norg/areas/weekly_journal/template.norg` unless it exists.
M.open_weekly_journal = function()
  local Path = require("plenary.path")

  -- Should probably make this more general in the future.
  local pwd = vim.fn.expand("~/norg/areas/weekly_journal/")
  local journal_file = pwd .. os.date("w%W") .. ".norg"

  local file = Path:new(journal_file)
  if not file:exists() then
    local template = Path:new(pwd .. "template.norg")
    template:copy({ destination = file, override = false })
  end

  vim.cmd("e " .. journal_file .. "| w")
end

As a bonus here’s how I created a fish alias to start Neovim and call the above functions that are defined in ~/.config/nvim/lua/config/norg.lua:

alias ep "nvim -c \":lua require('config.norg').open_norg('projects')\""
alias ej "nvim -c \":lua require('config.norg').open_weekly_journal()\""

The weird mnemonics are the same I use from within Neovim, so <leader>ep opens telescope in ~/norg/projects for example.

Is lua worth it?

One reason why I didn’t convert to Lua until now is that to me it looked fairly verbose.

Even though Vimscript isn’t a good programming language, it’s still a DSL specifically for Vim so it’s quite easy to do common things like set options or add autocommands. And Lua is nice, but it doesn’t support adding a custom DSL on quite that level, so I was worried I’d have to bend over too much to accomplish things.

-- Having to specify `vim.opt` isn't too bad
vim.opt.relativenumber = true
vim.opt.number = true

-- Autocommand creation is slightly more verbose,
-- but they're also a bit more readable than the Vim equivalent in my opinion.
local autocmd = vim.api.nvim_create_autocmd
local augroup = vim.api.nvim_create_augroup

autocmd("TextYankPost", {
  callback = function()
    vim.highlight.on_yank()
  end,
  desc = "Briefly highlight yanked text",
  group = augroup("yank", { clear = true }),
})
-- Hide statusline on dashboard
autocmd("FileType", {
  pattern = "alpha",
  group = augroup("filegroup", { clear = true }),
  command = "setlocal laststatus=0 noruler",
})

-- It's true that keymaps are also a more verbose, and having to wrap things
-- in strings here and there is slightly annoying.
local map = vim.keymap.set
map("n", "(", "[", { remap = true })
map("n", "]q", ":cnext<cr>", { desc = "Next quickfix" })
map("n", "<leader>ej", require("config.norg").open_weekly_journal, { desc = "This weeks journal" })

While the above examples are more verbose than the Vimscript alternatives, it doesn’t feel that bad.

And the upside of Lua is that you don’t have to bash your head in when you battle with Vimscript’s idiosyncrasies, which more than makes up for the added verbosity during simple configuration. Easily being able to access the Lua API of important plugins anywhere is also pleasant.

You could of course mix Vimscript and Lua, but for me the consistency of having everything in the same language, using the same file structure and the same development environment makes it worth using Lua all the time.

Was the rewrite worth it?

The million dollar question: was rewriting my entire configuration worth the time I spent doing it?

If you view it from a cold efficiency point-of-view, where every minute needs to pay itself back in the future thanks to increased productivity…

It’s debatable.

Maybe if I don’t touch the configuration file for many years, it’ll pay off. But I admit I spent far too much time on this for it to be considered truly productive time.

To be fair, a lot of this time was spent evaluating +100 plugins to see if I wanted to use them or not, and then fiddling with them to see if I could tweak them to my liking.

If all you want to do is convert your existing Vimscript config to a Lua config, it would be much faster. And if you only need to setup LSP or Treesitter or whatever, just look at an existing config and you’ll get setup in no time. You can also reference my config files, but do so on your own risk. (Seriously, with lspconfig, mason and mason-lspconfig configuring LSP doesn’t take that much time.)

But let’s be real here. The joy of fiddling with configurations and tweaking small things until they’re just right will always be worth it.

I’ve spent far too much time being productive and producing value, it was about time I spent some time alone.

Just me and my config.