<?xml version="1.0" encoding="utf-8"?><rss version="2.0"><channel><title>tea☆</title><link>https://qtea.me</link><description>Posts by tea</description><language>en</language><item><title>Deciding to write a Static Site Generator</title><link>https://qtea.me/posts/deciding-to-write-a-static-sitegen/</link><description><![CDATA[<p>For a while I’ve grown increasingly frustrated with my current static site generator (Gatsby).
It does the things I want well enough, but also adds way too much bloat to the site (which you can partially remove with a plugin…).
My main frustration with it arose when I wanted to add support for a new image format, but its plugin architecture (while presumably “powerful”) made this way too complicated.</p>
<p>So at the start of September I gradually arrived at the only logical conclusion of having to write my own static site generator that would fit my needs.
(Insert <a href="https://xkcd.com/927/">xkcd #927</a> but it’s less about standards and more about making something that works well for me.)</p>
<p>If you don’t care about my history with Gatsby feel free to skip to <a href="#trying-out-stuff">Trying out stuff</a>.</p>
<h2 id="how-we-got-here">How we got here<a href="#how-we-got-here" aria-label="Link to heading 'How we got here'" data-heading-content="How we got here" class="anchor"></a></h2>
<p>Some time in 2022 I started making a site with <a href="https://carrd.co">Carrd</a> to showcase some of the art I had commissioned.
I chose Carrd because I knew a lot of artists who use it to showcase their portfolio and it seemed like a simple option at that time to get things running quickly.
And tbh if I’d written something from scratch I never would’ve made the site anyway (oh how the turntables have turned).</p>
<p>This worked well enough for a while, until I ran into the restriction of “max. 50 elements per page” of the free Carrd account.
Since I’m a software developer I of course didn’t see a reason to pay for a pro account when I could just make a site myself and host it for free with <em>Whatever</em> Pages.</p>
<p>Making my own site would also give me more freedom to design things (not being tied to their WYSIWYG editor) and potentially ease the process of adding new images.</p>
<p>With Carrd, my current flow of adding an image looked like this:</p>
<ol>
<li>Each image is wrapped in a container, together with its description</li>
<li>So I would select the Container and duplicate it</li>
<li>Then select the image and replace it by uploading a new one</li>
<li>Then update the description</li>
<li>And finally publish my changes</li>
</ol>
<p>I was hoping to get to a flow like this:</p>
<ol>
<li>Have a config file in the repository which describes for each image where it’s located and what its metadata (description etc.) should be</li>
<li>So I would add the new image to an “images” folder</li>
<li>Update the config file with the data for the image (filename, description, …)</li>
<li>Commit everything</li>
<li>A pipeline runs, the page rebuilds based on the config file, and everything gets automatically deployed!</li>
</ol>
<p>So in May of 2023 I started looking for static site generators to hopefully replace the Carrd site – with a focus on it being able to read data from some kind of file and maybe even automatically resizing the images.
I ended up with <a href="https://www.gatsbyjs.com">Gatsby</a> since it seemed to tick all the boxes.
Its static site generation was built on React and GraphQL, which I had both never worked with before, but I had some experience with Angular and how hard could it be.</p>
<h2 id="using-gatsby">Using Gatsby<a href="#using-gatsby" aria-label="Link to heading 'Using Gatsby'" data-heading-content="Using Gatsby" class="anchor"></a></h2>
<p>So for the past 1.5 years I managed my site with Gatsby.
And for the most part without any issues.</p>
<p>Here’s a short rundown of how it worked.</p>
<p>I have a <code>data.yaml</code> file which contains an array, each element containing a map of the following data:</p>
<ul>
<li><code>file</code> – the relative path to the file in the repository</li>
<li><code>artistName</code> – the name of the artist who drew it</li>
<li><code>artistUrl</code> – an URL to the artists social media page</li>
<li><code>rendering</code> (added fairly recently) – sets the <code>image-rendering</code> CSS attribute, so pixel graphics are scaled properly</li>
</ul>
<p>Gatsby then has a couple of plugins, which discover the resources and do image transformations.
I was using the following plugins:</p>
<ul>
<li><code>gatsby-source-filesystem</code> – this adds the <code>data.yaml</code> as well as the “images” folder to Gatsby’s GraphQL pipeline</li>
<li><code>gatsby-transformer-yaml</code> – this automatically creates GraphQL nodes for our <code>data.yaml</code></li>
<li><code>gatsby-transformer-sharp</code> – this converts our images to different sizes and formats</li>
<li><code>gatsby-transformer-ffmpeg</code> – this converts video to different sizes and formats</li>
<li><code>gatsby-plugin-image</code> – support for displaying responsive images with <code>gatsby-transformer-sharp</code></li>
<li><code>gatsby-plugin-manifest</code> – for generating favicions and a web manifest</li>
<li><code>gatsby-plugin-no-javascript-utils</code> – to remove all the unnecessary stuff Gatsby puts in our page, even though we don’t use any JavaScript</li>
<li>and finally <code>gatsby-plugin-sharp</code> and <code>gatsby-plugin-ffmpeg</code>, which are called by the transformers to invoke the respective libraries</li>
</ul>
<p>This is a lot of stuff!
But the documentation was mostly fine and I didn’t have many issues writing the GraphQL that returns nodes for the transformed images and videos, and subsequently integrating them into the page.</p>
<p>The frustrations started when I wanted to add an animated image in form of a GIF.
This in itself didn’t cause any issues because the transformers would just skip any files they didn’t support and I could add the unprocessed file to my site.
But it still would be nice to resize them and have automatic conversion to other animated formats like APNG and WebP.</p>
<p>The easiest way (apart from not caring) would be to convert everything locally and add support for multiple image sizes to the <code>data.yaml</code>.
But it felt weird to mix these approaches: Locally generated AND transformed with Gatsby plugins.</p>
<p>So I went the route of trying to write my own Gatsby plugin…
I’m not gonna go into too much detail except that the whole thing is very complicated.
When you create a plugin you add functions to <code>gatsby-node.js</code> and <code>gatsby-worker.js</code> which are called at different steps by Gatsby after registering it.
And despite offering TypeScript support pretty much all plugins are written without it, which makes it even harder to follow how things work and how changing some parts could break the entire thing.</p>
<p>I spent a week or two trying things out by first using the ffmpeg and then the sharp plugin (+ transformer) as a base, but in the end gave up because adding such a simple thing as “call external program to transform the GIF” really wasn’t worth all the headaches.</p>
<p>What followed were three weeks of not really <del>thinking about it</del> trying anything.
What I had now worked well enough and while I occasionally thought about writing my own thing – it always seemed like “too much” to warrant all the potential hassle involved with it.</p>
<h2 id="trying-out-stuff">Trying out stuff<a href="#trying-out-stuff" aria-label="Link to heading 'Trying out stuff'" data-heading-content="Trying out stuff" class="anchor"></a></h2>
<p>Last Friday (Sep 13) I decided to just put “rust generate static html” into my search engine of choice and maybe find some inspiration that way.
Evaluating some options and figure out what other people are doing to generate simple static sites.</p>
<p>It’s been about a year since I last tried out Rust and the recent discussions (drama?) about Rust in the Linux kernel lead to it being fresh on my mind.
And it also seemed like a good choice, maybe, if I was looking for something performant.</p>
<p>The third result “<a href="https://kerkour.com/rust-static-site-generator">Building a static site generator in 100 lines of Rust</a>” immediately caught my intention.
Only 100 lines? That could give me a good starting point for some ideas and it should be easy to develop it further into the direction I needed.</p>
<p>So I quickly created a new project named “Ocarrd” (since the repository for my current site was named “carrd” due to its origins, combining it with “OC” and maybe the “o” could also mean “open”) and initialized a new Rust project.
After copy-pasting the 100 lines of code and making sure the example worked I went about changing things.</p>
<p>For the record here’s a short summary of what the example provides and my thoughts on it:</p>
<ul>
<li>Web Server – nice so I don’t have to manually run <code>python3 -m http.server</code> on the build directory</li>
<li>File Watcher – while not super important it’s nice that it rebuilds automatically when a file changes</li>
<li>Split between the layout as plain HTML in strings (<code>templates.rs</code>) and the content generated from Markdown files</li>
</ul>
<p>I like the idea of having the HTML be part of the code.
It makes it easier to conditionally apply things and you don’t have to prepare some kind of structure that gets passed to a template file.</p>
<p>So I tried out and rewrote the existing <code>templates.rs</code> using <a href="https://maud.lambda.xyz">Maud</a>, which seemed to do everything I wanted:</p>
<pre class="syntax-highlighting"><code class="language-rust"><span class="sh-source sh-rust"><span class="sh-meta sh-function sh-rust"><span class="sh-meta sh-function sh-rust"><span class="sh-storage sh-modifier sh-rust">pub</span> <span class="sh-storage sh-type sh-function sh-rust">fn</span> </span><span class="sh-entity sh-name sh-function sh-rust">render_body</span></span><span class="sh-meta sh-function sh-rust"><span class="sh-meta sh-function sh-parameters sh-rust"><span class="sh-punctuation sh-section sh-parameters sh-begin sh-rust">(</span><span class="sh-variable sh-parameter sh-rust">body</span><span class="sh-punctuation sh-separator sh-rust">:</span> <span class="sh-keyword sh-operator sh-rust">&amp;</span><span class="sh-storage sh-type sh-rust">str</span></span><span class="sh-meta sh-function sh-rust"><span class="sh-meta sh-function sh-parameters sh-rust"><span class="sh-punctuation sh-section sh-parameters sh-end sh-rust">)</span></span></span></span><span class="sh-meta sh-function sh-rust"> <span class="sh-meta sh-function sh-return-type sh-rust"><span class="sh-punctuation sh-separator sh-rust">-&gt;</span> Markup</span> </span><span class="sh-meta sh-function sh-rust"><span class="sh-meta sh-block sh-rust"><span class="sh-punctuation sh-section sh-block sh-begin sh-rust">{</span>
  <span class="sh-support sh-macro sh-rust">html!</span> <span class="sh-meta sh-block sh-rust"><span class="sh-punctuation sh-section sh-block sh-begin sh-rust">{</span>
    <span class="sh-meta sh-group sh-rust"><span class="sh-punctuation sh-section sh-group sh-begin sh-rust">(</span><span class="sh-constant sh-other sh-rust">DOCTYPE</span></span><span class="sh-meta sh-group sh-rust"><span class="sh-punctuation sh-section sh-group sh-end sh-rust">)</span></span>
    html lang<span class="sh-keyword sh-operator sh-assignment sh-rust">=</span><span class="sh-string sh-quoted sh-double sh-rust"><span class="sh-punctuation sh-definition sh-string sh-begin sh-rust">&quot;</span>en<span class="sh-punctuation sh-definition sh-string sh-end sh-rust">&quot;</span></span> <span class="sh-meta sh-block sh-rust"><span class="sh-punctuation sh-section sh-block sh-begin sh-rust">{</span>
      head <span class="sh-meta sh-block sh-rust"><span class="sh-punctuation sh-section sh-block sh-begin sh-rust">{</span>
        meta charset<span class="sh-keyword sh-operator sh-assignment sh-rust">=</span><span class="sh-string sh-quoted sh-double sh-rust"><span class="sh-punctuation sh-definition sh-string sh-begin sh-rust">&quot;</span>utf-8<span class="sh-punctuation sh-definition sh-string sh-end sh-rust">&quot;</span></span><span class="sh-punctuation sh-terminator sh-rust">;</span>
        meta name<span class="sh-keyword sh-operator sh-assignment sh-rust">=</span><span class="sh-string sh-quoted sh-double sh-rust"><span class="sh-punctuation sh-definition sh-string sh-begin sh-rust">&quot;</span>viewport<span class="sh-punctuation sh-definition sh-string sh-end sh-rust">&quot;</span></span> content<span class="sh-keyword sh-operator sh-assignment sh-rust">=</span><span class="sh-string sh-quoted sh-double sh-rust"><span class="sh-punctuation sh-definition sh-string sh-begin sh-rust">&quot;</span>width=device-width, initial-scale=1<span class="sh-punctuation sh-definition sh-string sh-end sh-rust">&quot;</span></span><span class="sh-punctuation sh-terminator sh-rust">;</span>
      </span><span class="sh-meta sh-block sh-rust"><span class="sh-punctuation sh-section sh-block sh-end sh-rust">}</span></span>
      body <span class="sh-meta sh-block sh-rust"><span class="sh-punctuation sh-section sh-block sh-begin sh-rust">{</span>
        nav <span class="sh-meta sh-block sh-rust"><span class="sh-punctuation sh-section sh-block sh-begin sh-rust">{</span>
          a href<span class="sh-keyword sh-operator sh-assignment sh-rust">=</span><span class="sh-string sh-quoted sh-double sh-rust"><span class="sh-punctuation sh-definition sh-string sh-begin sh-rust">&quot;</span>/<span class="sh-punctuation sh-definition sh-string sh-end sh-rust">&quot;</span></span> <span class="sh-meta sh-block sh-rust"><span class="sh-punctuation sh-section sh-block sh-begin sh-rust">{</span> <span class="sh-string sh-quoted sh-double sh-rust"><span class="sh-punctuation sh-definition sh-string sh-begin sh-rust">&quot;</span>Home<span class="sh-punctuation sh-definition sh-string sh-end sh-rust">&quot;</span></span> </span><span class="sh-meta sh-block sh-rust"><span class="sh-punctuation sh-section sh-block sh-end sh-rust">}</span></span>
        </span><span class="sh-meta sh-block sh-rust"><span class="sh-punctuation sh-section sh-block sh-end sh-rust">}</span></span>
        br<span class="sh-punctuation sh-terminator sh-rust">;</span>
        <span class="sh-meta sh-group sh-rust"><span class="sh-punctuation sh-section sh-group sh-begin sh-rust">(</span>PreEscaped<span class="sh-meta sh-group sh-rust"><span class="sh-punctuation sh-section sh-group sh-begin sh-rust">(</span>body</span><span class="sh-meta sh-group sh-rust"><span class="sh-punctuation sh-section sh-group sh-end sh-rust">)</span></span></span><span class="sh-meta sh-group sh-rust"><span class="sh-punctuation sh-section sh-group sh-end sh-rust">)</span></span>
      </span><span class="sh-meta sh-block sh-rust"><span class="sh-punctuation sh-section sh-block sh-end sh-rust">}</span></span>
    </span><span class="sh-meta sh-block sh-rust"><span class="sh-punctuation sh-section sh-block sh-end sh-rust">}</span></span>
  </span><span class="sh-meta sh-block sh-rust"><span class="sh-punctuation sh-section sh-block sh-end sh-rust">}</span></span>
</span><span class="sh-meta sh-block sh-rust"><span class="sh-punctuation sh-section sh-block sh-end sh-rust">}</span></span></span>
</span></code></pre>
<p>This looks nice!</p>
<p>It’s easy enough to read and you can insert Rust code wherever you want using <code>()</code>.
There’s support for control structures with <code>@if</code> and <code>@for</code> – which introduces a new syntax but that would be a trade-off I’d be willing to make.</p>
<p>It also has a nice feature that allows you to put classes and IDs right after the tag name.
Which might not add much, but would definitely reduce some boilerplate.</p>
<pre class="syntax-highlighting"><code class="language-rust"><span class="sh-source sh-rust"><span class="sh-support sh-macro sh-rust">html!</span> <span class="sh-meta sh-block sh-rust"><span class="sh-punctuation sh-section sh-block sh-begin sh-rust">{</span>
  input <span class="sh-keyword sh-operator sh-rust">#</span>my<span class="sh-keyword sh-operator sh-arithmetic sh-rust">-</span>id <span class="sh-punctuation sh-accessor sh-dot sh-rust">.</span>class<span class="sh-punctuation sh-accessor sh-dot sh-rust">.</span>another<span class="sh-keyword sh-operator sh-arithmetic sh-rust">-</span>class <span class="sh-storage sh-type sh-type sh-rust">type</span><span class="sh-keyword sh-operator sh-assignment sh-rust">=</span><span class="sh-string sh-quoted sh-double sh-rust"><span class="sh-punctuation sh-definition sh-string sh-begin sh-rust">&quot;</span>button<span class="sh-punctuation sh-definition sh-string sh-end sh-rust">&quot;</span></span> value<span class="sh-keyword sh-operator sh-assignment sh-rust">=</span><span class="sh-string sh-quoted sh-double sh-rust"><span class="sh-punctuation sh-definition sh-string sh-begin sh-rust">&quot;</span>My Button<span class="sh-punctuation sh-definition sh-string sh-end sh-rust">&quot;</span></span><span class="sh-punctuation sh-terminator sh-rust">;</span>
</span><span class="sh-meta sh-block sh-rust"><span class="sh-punctuation sh-section sh-block sh-end sh-rust">}</span></span>
</span></code></pre>
<p>Being optimistic that I could work with this I went about fixing some of the issues I had with it.
For example if I ran <code>cargo run</code> it would always look for the <code>content</code> directory in the current directory and try try to create the <code>public</code> directory in the current directory as well.
Small issue, should be easy to solve. Right?</p>
<p>After searching for a bit I found out about the environment variable <code>CARGO_MANIFEST_DIR</code>, which always points to the directory of the <code>Cargo.toml</code> – so the project root!
I quickly updated the code to add new variables that join the Manifest directory with the existing constants but…
As it turns out the constants were used in quite a lot of places, inside of nested closures, and while I did fight the borrow checker trying to solve this issue, my motivation to keep using Rust quickly evaporated.</p>
<p>So I went to bed, and while being unsatisfied with the outcome searched for other ways for HTML templating.
This time in Elixir.</p>
<h2 id="trying-it-again-but-with-elixir">Trying it again, but with Elixir<a href="#trying-it-again-but-with-elixir" aria-label="Link to heading 'Trying it again, but with Elixir'" data-heading-content="Trying it again, but with Elixir" class="anchor"></a></h2>
<p>I’ve learned about Elixir last year because of its usage in the <a href="https://akkoma.dev">Akkoma</a> fediverse software, and while being interested in it I didn’t have enough of a reason to try it out.
Until December when <a href="https://adventofcode.com">Advent of Code</a> (AoC) came along.<sup class="footnote-ref"><a href="#fn-aoc-2023" id="fnref-aoc-2023" data-footnote-ref>1</a></sup></p>
<p>I tried solving the problems with it until Day 20, when I finally lost motivation because I didn’t vibe with AoC’s approach of making you recognize patterns in the input file instead of asking for a purely generic solution…
Since then I constantly had the urge to maybe get a bit deeper into the language, but was always blocked by my main problem of not having anything I want to work on in my free time.</p>
<p>Alright.</p>
<p>I’d still like to make my own static site generator.</p>
<p>I’m pretty frustrated with both Gatsby and also my failed attempt at using Rust.</p>
<p>So maybe I can find something cool for templating in Elixir?
At least I wouldn’t have to fight the borrow checker.</p>
<p>The options for templating in the Elixir ecosystem (or I guess in general) boil down to two kinds:</p>
<ol>
<li>Your template is only partially connected to the code around it and can only use data passed to it in a special struct</li>
<li>Your template is fully integrated with the code around it and has access to all variables and functions of the surrounding scope</li>
</ol>
<p>The first option seems to be the most common one in all templating engines I’ve looked it.
Elixir has it’s own string templating with EEx (Embedded Elixir), which can be stored in a separate “.eex” file.
The Phoenix web framework (a popular Elixir project) provides an extension for it called HEEx (HTML+EEx), but regardless of how you use it the strings or files can’t integrate code directly and you have to pass all data to them.
In HEEx specifically this is done with an <code>assigns</code> parameter that must contain all the data you want to display or perform conditional logic on.
If you want to integrate existing templating engines like Mustache it works pretty much the same way.</p>
<p>And even my initially biggest hope – <a href="https://hexdocs.pm/temple/Temple.html">Temple</a> – unfortunately also works the same way (due to it wanting to be compatible with HEEx).
You may be able to write code that looks similar to what I liked about Maud, but it still requires everything to be put in an <code>assigns</code> variable.
Here’s a short example:</p>
<pre class="syntax-highlighting"><code class="language-elixir"><span class="sh-source sh-elixir"><span class="sh-meta sh-function sh-elixir"><span class="sh-keyword sh-control sh-module sh-elixir">def</span> <span class="sh-entity sh-name sh-function sh-public sh-elixir">render</span><span class="sh-punctuation sh-definition sh-parameters sh-elixir">(</span><span class="sh-punctuation sh-section sh-function sh-elixir">)</span> <span class="sh-keyword sh-control sh-module sh-elixir">do</span></span>
  title <span class="sh-keyword sh-operator sh-assignment sh-elixir">=</span> <span class="sh-meta sh-string sh-elixir"><span class="sh-string sh-quoted sh-double sh-elixir"><span class="sh-punctuation sh-definition sh-string sh-begin sh-elixir">&quot;</span>My Site<span class="sh-punctuation sh-definition sh-string sh-end sh-elixir">&quot;</span></span></span>
  assigns <span class="sh-keyword sh-operator sh-assignment sh-elixir">=</span> %<span class="sh-meta sh-sequence sh-tuple sh-elixir"><span class="sh-punctuation sh-section sh-sequence sh-begin sh-elixir">{</span><span class="sh-constant sh-other sh-keywords sh-elixir">title<span class="sh-punctuation sh-definition sh-constant sh-elixir">:</span></span> title<span class="sh-punctuation sh-section sh-sequence sh-end sh-elixir">}</span></span>

  temple <span class="sh-keyword sh-control sh-elixir">do</span>
    <span class="sh-meta sh-string sh-elixir"><span class="sh-string sh-quoted sh-double sh-elixir"><span class="sh-punctuation sh-definition sh-string sh-begin sh-elixir">&quot;</span>&lt;!DOCTYPE html&gt;<span class="sh-punctuation sh-definition sh-string sh-end sh-elixir">&quot;</span></span></span>

    html <span class="sh-keyword sh-control sh-elixir">do</span>
      head <span class="sh-keyword sh-control sh-elixir">do</span>
        meta <span class="sh-constant sh-other sh-keywords sh-elixir">charset<span class="sh-punctuation sh-definition sh-constant sh-elixir">:</span></span> <span class="sh-meta sh-string sh-elixir"><span class="sh-string sh-quoted sh-double sh-elixir"><span class="sh-punctuation sh-definition sh-string sh-begin sh-elixir">&quot;</span>utf-8<span class="sh-punctuation sh-definition sh-string sh-end sh-elixir">&quot;</span></span></span>
        title <span class="sh-constant sh-other sh-keywords sh-elixir">do<span class="sh-punctuation sh-definition sh-constant sh-elixir">:</span></span> <span class="sh-variable sh-other sh-module sh-elixir"><span class="sh-keyword sh-operator sh-definition sh-constant sh-elixir">@</span>title</span>
      <span class="sh-keyword sh-control sh-elixir">end</span>
    <span class="sh-keyword sh-control sh-elixir">end</span>
  <span class="sh-keyword sh-control sh-elixir">end</span>
<span class="sh-keyword sh-control sh-elixir">end</span>
</span></code></pre>
<p>You can’t pass the <code>title</code> variable directly.
You have to make it a key of the <code>assigns</code> map first.</p>
<p>The section option is what Maud does and what I was also used to from JSX – being able to integrate the surrounding scope directly with the template.
This is what I liked about the most about Gatsby (or rather React) and if I couldn’t do it I might as well put all templates in separate files.
Unfortunately the templating options for this are much rarer.</p>
<p>Being frustrated again I looked at the one project I had immediately brushed off because it hadn’t been updated since early 2018 – <a href="https://github.com/ijcd/taggart">Taggart</a>.
It might be unmaintained, but it looked like it would offer the same things I liked about Maud – and apparently even more.</p>
<p>One problem with Maud was that it used just one Macro that you write your HTML in, which lead to requiring special syntax at a lot of places (Rust code wrapped in <code>()</code> and control structures prefixed with <code>@</code>).
Instead Taggart has one macro for every, single, HTML tag.
This allows mixing it (almost) seamlessly with Elixir code, because each macro returns the HTML it represents as a string.<sup class="footnote-ref"><a href="#fn-iodata" id="fnref-iodata" data-footnote-ref>2</a></sup>
And the inner body is just plain Elixir code.</p>
<p>So if you write for example:</p>
<pre class="syntax-highlighting"><code class="language-elixir"><span class="sh-source sh-elixir"><span class="sh-meta sh-function sh-elixir"><span class="sh-keyword sh-control sh-module sh-elixir">def</span> <span class="sh-entity sh-name sh-function sh-public sh-elixir">render</span><span class="sh-punctuation sh-definition sh-parameters sh-elixir">(</span>content<span class="sh-punctuation sh-section sh-function sh-elixir">)</span> <span class="sh-keyword sh-control sh-module sh-elixir">do</span></span>
  html <span class="sh-keyword sh-control sh-elixir">do</span>
    head <span class="sh-keyword sh-control sh-elixir">do</span>
      meta <span class="sh-constant sh-other sh-keywords sh-elixir">charset<span class="sh-punctuation sh-definition sh-constant sh-elixir">:</span></span> <span class="sh-meta sh-string sh-elixir"><span class="sh-string sh-quoted sh-double sh-elixir"><span class="sh-punctuation sh-definition sh-string sh-begin sh-elixir">&quot;</span>utf-8<span class="sh-punctuation sh-definition sh-string sh-end sh-elixir">&quot;</span></span></span>
      title <span class="sh-meta sh-string sh-elixir"><span class="sh-string sh-quoted sh-double sh-elixir"><span class="sh-punctuation sh-definition sh-string sh-begin sh-elixir">&quot;</span>omg does this actually do everything I want<span class="sh-punctuation sh-definition sh-string sh-end sh-elixir">&quot;</span></span></span>
    <span class="sh-keyword sh-control sh-elixir">end</span>
    body <span class="sh-keyword sh-control sh-elixir">do</span>
      content
    <span class="sh-keyword sh-control sh-elixir">end</span>
  <span class="sh-keyword sh-control sh-elixir">end</span>
<span class="sh-keyword sh-control sh-elixir">end</span>
</span></code></pre>
<p>It would insert <code>content</code> as is, because the result of the <code>body</code> macro is just a string containing <code>&lt;body&gt;</code>, the passed <code>content</code> and <code>&lt;/body&gt;</code>.
Likewise this string gets used as the text content for the <code>html</code> macro (along with the result of other macros and Elixir variables).
So this function returns a string of all the HTML!<sup class="footnote-ref"><a href="#fn-safe-html" id="fnref-safe-html" data-footnote-ref>3</a></sup></p>
<p>And the best part is there is (almost) no need for special syntax because everything is Elixir code!</p>
<p>Write:</p>
<pre class="syntax-highlighting"><code class="language-elixir"><span class="sh-source sh-elixir">div <span class="sh-constant sh-other sh-keywords sh-elixir">class<span class="sh-punctuation sh-definition sh-constant sh-elixir">:</span></span> <span class="sh-meta sh-string sh-elixir"><span class="sh-string sh-quoted sh-double sh-elixir"><span class="sh-punctuation sh-definition sh-string sh-begin sh-elixir">&quot;</span>my-cool-class<span class="sh-punctuation sh-definition sh-string sh-end sh-elixir">&quot;</span></span></span> <span class="sh-keyword sh-control sh-elixir">do</span>
  <span class="sh-keyword sh-control sh-elixir">if</span> some_boolean <span class="sh-keyword sh-control sh-elixir">do</span>
    <span class="sh-meta sh-string sh-elixir"><span class="sh-string sh-quoted sh-double sh-elixir"><span class="sh-punctuation sh-definition sh-string sh-begin sh-elixir">&quot;</span>optional content<span class="sh-punctuation sh-definition sh-string sh-end sh-elixir">&quot;</span></span></span>
  <span class="sh-keyword sh-control sh-elixir">else</span> <span class="sh-meta sh-string sh-elixir"><span class="sh-string sh-quoted sh-double sh-elixir"><span class="sh-punctuation sh-definition sh-string sh-begin sh-elixir">&quot;</span><span class="sh-punctuation sh-definition sh-string sh-end sh-elixir">&quot;</span></span></span> <span class="sh-keyword sh-control sh-elixir">end</span>
<span class="sh-keyword sh-control sh-elixir">end</span>
</span></code></pre>
<p>And since <code>if</code> in Elixir returns its <del>content</del> last statement it’s really easy to render an empty <code>&lt;div&gt;</code> if <code>some_boolean</code> evaluates to <code>false</code>!</p>
<p>Having made sure everything worked I got <em>really</em> excited and proceeded to fork the unmaintained repository to update its dependencies (and fix a couple smaller issues I encountered later on).<sup class="footnote-ref"><a href="#fn-webassembly" id="fnref-webassembly" data-footnote-ref>4</a></sup></p>
<p>And then started to work on other things like an automatically started web server and file watcher to give me some of the comfort of <code>gatsby develop</code> back.</p>
<p>But more on this in the next blog post!</p>
<section class="footnotes" data-footnotes>
<ol>
<li id="fn-aoc-2023">
<p>All available <a href="https://codeberg.org/qtea/advent-of-code-2023">here</a> if you feel like judging my code <a href="#fnref-aoc-2023" class="footnote-backref" data-footnote-backref data-footnote-backref-idx="1" aria-label="Back to reference 1">↩</a></p>
</li>
<li id="fn-iodata">
<p>Actually it returns <a href="https://hexdocs.pm/elixir/1.17.3/IO.html#module-io-data">IO data</a> which is even better <a href="#fnref-iodata" class="footnote-backref" data-footnote-backref data-footnote-backref-idx="2" aria-label="Back to reference 2">↩</a></p>
</li>
<li id="fn-safe-html">
<p>It actually returns <code>{:safe, html}</code> and when wrapped in another macro it checks whether it receives unsafe data that still needs to be processed, or already safe data. <a href="#fnref-safe-html" class="footnote-backref" data-footnote-backref data-footnote-backref-idx="3" aria-label="Back to reference 3">↩</a></p>
</li>
<li id="fn-webassembly">
<p>Funny aside: While doing so I figured out why Taggart has been unmaintained. <br />
The author found out shortly after creating it that there’s a similar project – <a href="https://github.com/wkhere/webassembly">WebAssembly</a> (which predates what is commonly know as “WebAssembly” today) – that does pretty much the same thing. <br />
But the small differences still make me prefer Taggart and since I’ve already forked it I have the option to easily add features I might need. <a href="#fnref-webassembly" class="footnote-backref" data-footnote-backref data-footnote-backref-idx="4" aria-label="Back to reference 4">↩</a></p>
</li>
</ol>
</section>
]]></description><guid>https://qtea.me/posts/deciding-to-write-a-static-sitegen/</guid><pubDate>Sun, 6 Oct 2024 00:00:00 +0000</pubDate></item><item><title>So I thought you wanted to write a Static Site Generator</title><link>https://qtea.me/posts/i-thought-you-wanted-to-write-a-sitegen/</link><description><![CDATA[<p>I did!</p>
<p>It’s been a while now since I <a href="../deciding-to-write-a-static-sitegen/">posted about</a> why I decided to write my own static site generator, what I chose to use for templating and teased that I would post more about it.</p>
<p>So it has been pretty much done now for a while (at least for my current use case) – I just never felt like writing anything about it.
Let’s do a quick (maybe not so quick after all) rundown of how it works and what I ended up writing.</p>
<h2 id="part-1-where-i-ramble-about-umbrella-projects">Part 1: Where I ramble about Umbrella Projects<a href="#part-1-where-i-ramble-about-umbrella-projects" aria-label="Link to heading 'Part 1: Where I ramble about Umbrella Projects'" data-heading-content="Part 1: Where I ramble about Umbrella Projects" class="anchor"></a></h2>
<p>I decided pretty early on to split the sitegen into two separate Elixir applications:</p>
<ol>
<li>The sitegen itself. <br />
This way I can easily run it in CI with the minimal dependencies necessary to build my site.</li>
<li>The development server. <br />
It still doesn’t have a functional file watcher, but it’s nice during development to quickly have a preview of what the site looks like (even if I have to restart it for every build).
Its dependencies are marked as <code>only: :dev</code> so they can be skipped if one (read: CI) is only interested in the sitegen itself.</li>
</ol>
<p>Both are contained in the same repository as part of an Elixir <a href="https://hexdocs.pm/elixir/1.18.1/dependencies-and-umbrella-projects.html#umbrella-projects">umbrella project</a>).
I fought for a while with how this works, because there are a couple issues with it if you want to run the applications independently.</p>
<p>Umbrella projects are designed to start all applications they contain, there’s just no good way around it.
If I do a <code>mix run</code> in the repository root it will always start both the sitegen and the development server (as well as all applications I added as dependencies).
This means if I install only the production dependencies for the sitegen in CI (<code>mix deps.get --only prod</code>) it will fail to compile, because Mix (the Elixir build tool) will try to compile and run all applications.</p>
<p>I played around a bit with ways around this, including <code>mix cmd --app ocarrd mix run</code> (which is somewhat deprecated?) and the newer <code>mix do --app ocarrd run</code>, but neither offered a satisfying solution.</p>
<ul>
<li>The <code>mix cmd</code> approach actually worked.
This is because it changes to the directory of the application to execute the given command – which can be any command and not just those provided by Mix.
The only issue I had with it is that color in the application log didn’t work.</li>
<li>The <code>mix do</code> approach did not work.
It is mainly meant to chain multiple Mix tasks like performing different build steps and (I assume) less for actually running the applications.</li>
</ul>
<p>Since I run everything through a <code>justfile</code> anyway I eventually decided to just <code>cd</code> to the sitegen directory in CI, this way easily solving the issue I had with <code>mix cmd</code> instead of spending more hours coming up with a way more complicated solution.</p>
<p>The actual communication between the applications is more straightforward (if we skip over the part where I overcomplicated it for a while).
But first I gotta confess that–</p>
<h2 id="part-2-theres-actually-three-applications">Part 2: There’s actually three applications<a href="#part-2-theres-actually-three-applications" aria-label="Link to heading 'Part 2: There’s actually three applications'" data-heading-content="Part 2: There’s actually three applications" class="anchor"></a></h2>
<p>This is not surprising at all if you think about it.</p>
<p>Apart from the sitegen and the development server you also need a site itself!
I could’ve come up with a configuration-only approach, but having the site as its own application gives me way more flexibility in deciding what a specific site needs.
More on that in a bit, but first we have to finish talking about the development server.
So let’s break down what each of the applications does when it starts:</p>
<ol>
<li>The sitegen starts the builder process and listens for requests (it doesn’t build anything yet).</li>
<li>The development server registers itself as an observer with the sitegen.
It then waits for a message from the sitegen telling it that there’s something to build.
Finally it asks the sitegen to (re)build whatever it has.
This could support building multiple sites in the future.
It would even work with new site applications being started while the sitegen and development server are still running.
I still haven’t implemented a file watcher.
But if it <em>was</em> implemented the development server could just ask the sitegen to rebuild itself again.</li>
<li>The actual site.
It always tells the sitegen “these are the things you need to do to build me”.
Currently it has logic that checks whether the development server is available.
If the server is available, it doesn’t do anything (apart from telling its requirements to the sitegen).
If it is not, it triggers a build.
I should probably refactor this logic so it is part of the sitegen.
Hmmm.</li>
</ol>
<p>Now that we’ve gotten the development server out of the picture we can focus more on what the sitegen actually does.</p>
<h2 id="part-3-so-what-about-the-sitegen">Part 3: So what about the sitegen<a href="#part-3-so-what-about-the-sitegen" aria-label="Link to heading 'Part 3: So what about the sitegen'" data-heading-content="Part 3: So what about the sitegen" class="anchor"></a></h2>
<p>The sitegen contains a couple modules that a site can use to build itself.</p>
<h3 id="the-builder">The Builder<a href="#the-builder" aria-label="Link to heading 'The Builder'" data-heading-content="The Builder" class="anchor"></a></h3>
<p>This is the only actually required module.</p>
<p>The site defines a list of tasks (function references) that it hands over to the <em>Builder</em>.
For my current site these are the following:</p>
<ul>
<li>Pages:
This uses another module from the sitegen to build all its pages.</li>
<li>Static Images:
These are static images that should be copied to the output directory as is.</li>
<li>Sass:
This runs the Sass compiler to generate all the CSS.
I’m barely using any Sass features, but this was the easiest way to to inject some config and also minify the CSS.
(Without adding NodeJS dependencies. I really do not want to do that.)</li>
</ul>
<p>What I like about this is that apart from what is done inside the <em>Pages</em> task, everything else is defined entirely in the site itself.
The site defines how to copy the images to the output directory.
The site defines how to run the Sass compiler and inject SCSS into it to set the base URL for image references etc.</p>
<p>It probably makes sense to move some of these functions into modules inside the sitegen at some point.
Not all sites need images or custom stylesheets or–.
If I were to move my personal website (the one you’re on right now) away from Pandoc and a bunch of shell scripts I could, for example, easily add a task that generates an RSS feed.
And if that RSS generator works well enough I might move it into the sitegen itself or create a separate application or I could easily plug in an existing generator.
I could only migrate some parts and create a task that calls Pandoc to still render the blog posts.</p>
<p>If you remember my frustrations with Gatsby it probably makes sense (I hope) why it ended up this way.
I wanted to have pluggable building blocks that just <em>do</em> a thing and don’t require you to implement stuff that interacts with The Framework™.</p>
<p>Anyway.
The <em>Builder</em> takes this list of tasks and executes them in parallel.
Since my current tasks don’t depend on each other this seemed like a good way to do things.
And if <em>your</em> site (or more likely my next one) has tasks that depend on each other you can just do your own thing.</p>
<h3 id="the-pages">The Pages<a href="#the-pages" aria-label="Link to heading 'The Pages'" data-heading-content="The Pages" class="anchor"></a></h3>
<p><em>Pages</em> are mainly a registry that a site can register its pages in.
Each page consists of a <em>path</em> that it should be served under and a <em>function</em> that generates it.</p>
<p>The path is automatically sanitized of symbols that shouldn’t appear in URLs, and if it contains a plain name (without <code>.html</code> at the end) the registry assumes that it should create a directory with an <code>index.html</code> file instead.</p>
<p>The function simply returns a string containing the final HTML.
Due to the nature of the Taggart library (see my <a href="../deciding-to-write-a-static-sitegen/#trying-it-again-but-with-elixir">previous post</a> for more details) all you have to do is call a function that contains a template.
Or you can do whatever you want!
While my sitegen has other modules that depend on Taggart it does not require it at all to generate the pages.
You can load your own HTML file from disk and return its contents inside the function.<sup class="footnote-ref"><a href="#fn-safe-html" id="fnref-safe-html" data-footnote-ref>1</a></sup>
Or load any other file you want to serve and maybe run some preprocessing on.</p>
<p>Finally you simply call <code>Pages.write_all()</code> to write all pages inside the registry to the output directory.</p>
<p>One last thing that the <em>Pages</em> registry does is that it allows you to verify if a page actually exists.
For example if you use the <em>Link</em> component provided by the sitegen it will throw an error if you link to a page that does not exist.</p>
<h3 id="components">Components<a href="#components" aria-label="Link to heading 'Components'" data-heading-content="Components" class="anchor"></a></h3>
<p>We’re finally getting to the things that I actually wrote the sitegen for.</p>
<p>I wanted to easily add new media formats that weren’t supported by Gatsby plugins, so I wrote an <em>Image</em> and a <em>Video</em> component (as well as the mentioned <em>Link</em> component) to offer a simple way to add responsive media of different file types to a page.
A “component” in this case simply being a function that accepts a map of all the different media and then additional data like the alt text to attach to the HTML element.</p>
<p>For example the function for the <em>Image</em> component looks as follows (slightly simplified in order to take up less space):</p>
<pre class="syntax-highlighting"><code class="language-elixir"><span class="sh-source sh-elixir"><span class="sh-meta sh-function sh-elixir"><span class="sh-keyword sh-control sh-module sh-elixir">def</span> <span class="sh-entity sh-name sh-function sh-public sh-elixir">image</span><span class="sh-punctuation sh-definition sh-parameters sh-elixir">(</span>media_map<span class="sh-punctuation sh-separator sh-object sh-elixir">,</span> <span class="sh-constant sh-other sh-keywords sh-elixir">alt<span class="sh-punctuation sh-definition sh-constant sh-elixir">:</span></span> alt<span class="sh-punctuation sh-separator sh-object sh-elixir">,</span> <span class="sh-constant sh-other sh-keywords sh-elixir">sizes<span class="sh-punctuation sh-definition sh-constant sh-elixir">:</span></span> sizes<span class="sh-punctuation sh-section sh-function sh-elixir">)</span> <span class="sh-keyword sh-control sh-module sh-elixir">do</span></span>
  <span class="sh-meta sh-sequence sh-tuple sh-elixir"><span class="sh-punctuation sh-section sh-sequence sh-begin sh-elixir">{</span>fallback<span class="sh-punctuation sh-separator sh-sequence sh-elixir">,</span> media_map<span class="sh-punctuation sh-section sh-sequence sh-end sh-elixir">}</span></span> <span class="sh-keyword sh-operator sh-assignment sh-elixir">=</span> pop_fallback<span class="sh-punctuation sh-section sh-function sh-elixir">(</span>media_map<span class="sh-punctuation sh-section sh-function sh-elixir">)</span>
  <span class="sh-meta sh-sequence sh-tuple sh-elixir"><span class="sh-punctuation sh-section sh-sequence sh-begin sh-elixir">{</span>src<span class="sh-punctuation sh-separator sh-sequence sh-elixir">,</span> srcset<span class="sh-punctuation sh-section sh-sequence sh-end sh-elixir">}</span></span> <span class="sh-keyword sh-operator sh-assignment sh-elixir">=</span> to_fallback_src<span class="sh-punctuation sh-section sh-function sh-elixir">(</span>fallback<span class="sh-punctuation sh-section sh-function sh-elixir">)</span>

  picture <span class="sh-keyword sh-control sh-elixir">do</span>
    <span class="sh-keyword sh-control sh-elixir">for</span> <span class="sh-meta sh-sequence sh-tuple sh-elixir"><span class="sh-punctuation sh-section sh-sequence sh-begin sh-elixir">{</span>type<span class="sh-punctuation sh-separator sh-sequence sh-elixir">,</span> media_list<span class="sh-punctuation sh-section sh-sequence sh-end sh-elixir">}</span></span> <span class="sh-keyword sh-operator sh-arrow sh-elixir">&lt;-</span> sort_by_prio<span class="sh-punctuation sh-section sh-function sh-elixir">(</span>media_map<span class="sh-punctuation sh-section sh-function sh-elixir">)</span> <span class="sh-keyword sh-control sh-elixir">do</span>
      source<span class="sh-punctuation sh-section sh-function sh-elixir">(</span><span class="sh-constant sh-other sh-keywords sh-elixir">type<span class="sh-punctuation sh-definition sh-constant sh-elixir">:</span></span> type<span class="sh-punctuation sh-separator sh-object sh-elixir">,</span> <span class="sh-constant sh-other sh-keywords sh-elixir">srcset<span class="sh-punctuation sh-definition sh-constant sh-elixir">:</span></span> to_srcset<span class="sh-punctuation sh-section sh-function sh-elixir">(</span>media_list<span class="sh-punctuation sh-section sh-function sh-elixir">)</span><span class="sh-punctuation sh-separator sh-object sh-elixir">,</span> <span class="sh-constant sh-other sh-keywords sh-elixir">sizes<span class="sh-punctuation sh-definition sh-constant sh-elixir">:</span></span> sizes<span class="sh-punctuation sh-section sh-function sh-elixir">)</span>
    <span class="sh-keyword sh-control sh-elixir">end</span>

    img<span class="sh-punctuation sh-section sh-function sh-elixir">(</span><span class="sh-constant sh-other sh-keywords sh-elixir">alt<span class="sh-punctuation sh-definition sh-constant sh-elixir">:</span></span> alt<span class="sh-punctuation sh-separator sh-object sh-elixir">,</span> <span class="sh-constant sh-other sh-keywords sh-elixir">src<span class="sh-punctuation sh-definition sh-constant sh-elixir">:</span></span> to_absolute_url<span class="sh-punctuation sh-section sh-function sh-elixir">(</span>src<span class="sh-punctuation sh-section sh-function sh-elixir">)</span><span class="sh-punctuation sh-separator sh-object sh-elixir">,</span> <span class="sh-constant sh-other sh-keywords sh-elixir">srcset<span class="sh-punctuation sh-definition sh-constant sh-elixir">:</span></span> srcset<span class="sh-punctuation sh-separator sh-object sh-elixir">,</span> <span class="sh-constant sh-other sh-keywords sh-elixir">sizes<span class="sh-punctuation sh-definition sh-constant sh-elixir">:</span></span> sizes<span class="sh-punctuation sh-section sh-function sh-elixir">)</span>
  <span class="sh-keyword sh-control sh-elixir">end</span>
<span class="sh-keyword sh-control sh-elixir">end</span>
</span></code></pre>
<p>A media map is structured as follows:</p>
<pre class="syntax-highlighting"><code class="language-elixir"><span class="sh-source sh-elixir">%<span class="sh-meta sh-sequence sh-tuple sh-elixir"><span class="sh-punctuation sh-section sh-sequence sh-begin sh-elixir">{</span>
  <span class="sh-constant sh-other sh-symbol sh-double-quoted sh-elixir"><span class="sh-punctuation sh-definition sh-constant sh-elixir">:&quot;</span>image/png<span class="sh-punctuation sh-definition sh-constant sh-elixir">&quot;</span></span>: <span class="sh-punctuation sh-section sh-array sh-elixir">[</span>
    %<span class="sh-entity sh-name sh-class sh-elixir">Media</span><span class="sh-meta sh-sequence sh-tuple sh-elixir"><span class="sh-punctuation sh-section sh-sequence sh-begin sh-elixir">{</span><span class="sh-constant sh-other sh-keywords sh-elixir">width<span class="sh-punctuation sh-definition sh-constant sh-elixir">:</span></span> …<span class="sh-punctuation sh-separator sh-sequence sh-elixir">,</span> <span class="sh-constant sh-other sh-keywords sh-elixir">height<span class="sh-punctuation sh-definition sh-constant sh-elixir">:</span></span> …<span class="sh-punctuation sh-separator sh-sequence sh-elixir">,</span> <span class="sh-constant sh-other sh-keywords sh-elixir">abs_url<span class="sh-punctuation sh-definition sh-constant sh-elixir">:</span></span> …<span class="sh-punctuation sh-separator sh-sequence sh-elixir">,</span> …<span class="sh-punctuation sh-section sh-sequence sh-end sh-elixir">}</span></span><span class="sh-punctuation sh-separator sh-sequence sh-elixir">,</span>
    …
  <span class="sh-punctuation sh-section sh-array sh-elixir">]</span><span class="sh-punctuation sh-separator sh-sequence sh-elixir">,</span>
  <span class="sh-constant sh-other sh-symbol sh-double-quoted sh-elixir"><span class="sh-punctuation sh-definition sh-constant sh-elixir">:&quot;</span>image/avif<span class="sh-punctuation sh-definition sh-constant sh-elixir">&quot;</span></span>: <span class="sh-punctuation sh-section sh-array sh-elixir">[</span>…<span class="sh-punctuation sh-section sh-array sh-elixir">]</span>
<span class="sh-punctuation sh-section sh-sequence sh-end sh-elixir">}</span></span>
</span></code></pre>
<p>First the component removes the fallback type that should be able to be displayed in all browsers from the media map and then uses Taggart to create a <code>picture</code> element.
This contains a <code>source</code> element for the remaining types (sorted by the priority in which they should be used) as well as a regular <code>img</code> element that’s used for the fallback type.</p>
<p>But where does the media map come from?</p>
<h3 id="media-state-and-transformer">Media State and Transformer<a href="#media-state-and-transformer" aria-label="Link to heading 'Media State and Transformer'" data-heading-content="Media State and Transformer" class="anchor"></a></h3>
<p>Let’s start with the <em>Media State</em> because that’s the part a page interact with directly.</p>
<p>In order to get the media map that should be passed to a component you simply ask the State to get it for you:</p>
<pre class="syntax-highlighting"><code class="language-elixir"><span class="sh-source sh-elixir">%<span class="sh-entity sh-name sh-class sh-elixir">MediaWrap</span><span class="sh-meta sh-sequence sh-tuple sh-elixir"><span class="sh-punctuation sh-section sh-sequence sh-begin sh-elixir">{</span><span class="sh-constant sh-other sh-keywords sh-elixir">category<span class="sh-punctuation sh-definition sh-constant sh-elixir">:</span></span> category<span class="sh-punctuation sh-separator sh-sequence sh-elixir">,</span> <span class="sh-constant sh-other sh-keywords sh-elixir">type<span class="sh-punctuation sh-definition sh-constant sh-elixir">:</span></span> type<span class="sh-punctuation sh-separator sh-sequence sh-elixir">,</span> <span class="sh-constant sh-other sh-keywords sh-elixir">value<span class="sh-punctuation sh-definition sh-constant sh-elixir">:</span></span> media<span class="sh-punctuation sh-section sh-sequence sh-end sh-elixir">}</span></span> <span class="sh-keyword sh-operator sh-assignment sh-elixir">=</span>
  <span class="sh-entity sh-name sh-class sh-elixir">MediaState</span><span class="sh-punctuation sh-separator sh-method sh-elixir">.</span>get_or_compute<span class="sh-punctuation sh-section sh-function sh-elixir">(</span>file<span class="sh-punctuation sh-separator sh-object sh-elixir">,</span> opts<span class="sh-punctuation sh-section sh-function sh-elixir">)</span>
</span></code></pre>
<p>As you can see you pass the path to the media file, as well as a list of options (for example <code>rendering: &quot;pixelated&quot;</code> to use nearest-neighbor scaling).
It returns a <code>MediaWrap</code> struct that contains the detected category (image or video), the type of the data (a single “unresponsive” file or a media map) and the value itself.
Since the function is named <code>get_or_compute</code> it computes the result the first time and then caches it for all subsequent calls.
The media state itself isn’t that interesting: It registers callers as observers, starts a process in which the <em>Transformer</em> does all the actual work, and then tells everyone that the result is ready.</p>
<p><em>Transformer</em> is a <a href="https://hexdocs.pm/elixir/1.18.1/typespecs.html#behaviours">behaviour</a> that can be implemented to provide transformations for a specific file type.
It also provides a generic <code>transform(file, opts)</code> function that tries all known transformers until it finds one that works.
From the arguments you can see that this is pretty much exactly what also gets passed to the <em>Media State</em>.</p>
<p>Because it is a <em>behaviour</em>, it specifies the following functions that each transformer should implement:</p>
<pre class="syntax-highlighting"><code class="language-elixir"><span class="sh-source sh-elixir">extensions<span class="sh-punctuation sh-section sh-function sh-elixir">(</span><span class="sh-punctuation sh-section sh-function sh-elixir">)</span>
get_category<span class="sh-punctuation sh-section sh-function sh-elixir">(</span>path<span class="sh-punctuation sh-section sh-function sh-elixir">)</span>
get_metadata<span class="sh-punctuation sh-section sh-function sh-elixir">(</span>path<span class="sh-punctuation sh-section sh-function sh-elixir">)</span>
create_intermediates<span class="sh-punctuation sh-section sh-function sh-elixir">(</span>input<span class="sh-punctuation sh-section sh-function sh-elixir">)</span>
transform_new<span class="sh-punctuation sh-section sh-function sh-elixir">(</span>input<span class="sh-punctuation sh-separator sh-object sh-elixir">,</span> intermediates<span class="sh-punctuation sh-section sh-function sh-elixir">)</span>
</span></code></pre>
<p><code>extensions/0</code> returns the list of file extensions that this transformer supports.
The generic transform function has a list of all transformers and calls this function in order to decide which transformer to use.</p>
<p><code>get_category/1</code> returns the category that a given file has.
This is the same category used by the <em>Media State</em> earlier, and can currently be either <code>image</code> or <code>video</code> (and requires the file path as an argument since one transformer could support both images and videos).</p>
<p><code>get_metadata/1</code> returns metadata about a file such as its width and height.</p>
<p>Finally there’s the two functions involved in the actual transformation.</p>
<p><code>create_intermediates/1</code> is the main function that gets called every time to create a list of “intermediates” out of some input data (the file name and associated options like <code>rendering: &quot;pixelated&quot;</code>).
Each intermediate corresponds to one output file that will later be written when doing the actual transformation.
There are two important things that are happening here.</p>
<ol>
<li>It will set the actual transformation options based on the input options (for example turn <code>rendering: &quot;pixeldated&quot;</code> into the proper name of the <a href="https://www.libvips.org/API/current/libvips-resample.html#VipsKernel">resampling kernel</a> to use).
This happens on a per output basis because it may be desired to interpret the input options differently for specific image sizes or formats.</li>
<li>Generate the output file name based on the input file and all the options.
This has the general form <code>&lt;input-hash&gt;/&lt;output-hash&gt;.&lt;ext&gt;</code> and assures that the same input will always generate the same output.</li>
</ol>
<p>Afterwards the transformer can split the list of intermediates into ones for which files have already been generated (by checking if the output path exists) and ones that have yet to be generated (by calling <code>transform_new/2</code> on the intermediates).
This is especially useful when two sets of inputs overlap in the types of files that should be generated.
Imagine one that wants images in the scales <code>[0.25, 0.5, 0.75]</code> and one that wants them in the scales <code>[0.5, 1.0]</code> – the 0.5 scale image only needs to be generated once and the output path will be identical for both.</p>
<p><code>transform_new/2</code> mostly calls a program or library with the necessary options for the transformation.
In case of libraries like <a href="https://www.libvips.org/">vips</a> that allow you to create a kind of pipeline that first transforms the input image to the desired output sizes and then saves each in all the desired image formats.
This way not every intermediate has to go through the whole transformation process and the shared steps are only performed once.
Since I decided pretty early on to first implement a transformer around <em>vips</em> and wanted to support this feature it is also the reason that this function accepts a list of intermediates instead of performing the transformation only for a single output at a time.</p>
<p>At the end the transformer concats the lists of existing and newly generated media and wraps them in <code>MediaWrap</code>.</p>
<h2 id="conclusion">Conclusion?<a href="#conclusion" aria-label="Link to heading 'Conclusion?'" data-heading-content="Conclusion?" class="anchor"></a></h2>
<p>I hope this helped to show some insights into how I decided to implement my sitegen.
I tried to minimize the amount of code shown to only complement the text, but maybe that made things more difficult to understand.
I actually sat on the last section a couple weeks because I wasn’t sure how detailed my description of the transformer itself should be.
Overall I had a lot of fun working on the sitegen and learned some new things about Elixir that I didn’t get to properly use before.
As mentioned in the beginning it pretty much does what I need it to do now.
I can think of a couple things that could be improved, but since it is just a hobby project I’ll get to it when I get to it and focus on other stuff in the mean time.</p>
<p>Between starting this blog post and finishing it I actually implemented two new features that I thought about for a while!
The first one is setting an image “placeholder” to avoid content shift while the images are still loading (all without JavaScript).
The second one is a new component that automatically downloads fonts from an external stylesheet and a new transformer that uses the features described earlier to transform the stylesheet into a local one if it hasn’t been already.
And going over everything again for this post gave me a couple more ideas.</p>
<p>Who knows if I’ll write a third part.
For now I’m happy that I managed to collect my thoughts on both the issues I had with existing sitegens and how I decided to solve them (for my particular use case).</p>
<p>If you’re interested in more than just my attempt to summarize everything you can check out the code in my <a href="https://codeberg.org/qtea/ocarrd">repository</a> or visit the <a href="https://qtea.codeberg.page/ocarrd/">example site</a> where I try out the features before implementing them in my own site!</p>
<section class="footnotes" data-footnotes>
<ol>
<li id="fn-safe-html">
<p>As long as it returns <code>{:safe, your_string_like_thing}</code>. <br />
Hey this is is pretty much the same footnote I wrote in the previous post. <br />
I guess I just think it’d be too much noise to mention this in the main body and instead decide to put it in a footnote that most people are gonna click on anyway. <a href="#fnref-safe-html" class="footnote-backref" data-footnote-backref data-footnote-backref-idx="1" aria-label="Back to reference 1">↩</a></p>
</li>
</ol>
</section>
]]></description><guid>https://qtea.me/posts/i-thought-you-wanted-to-write-a-sitegen/</guid><pubDate>Wed, 29 Jan 2025 00:00:00 +0000</pubDate></item><item><title>Finding the occasional joy in programming again</title><link>https://qtea.me/posts/occasional-joy-in-programming/</link><description><![CDATA[<p>A couple months ago I ended up writing something in C++ for the very first time and even did a proper tagged release because I thought other people might find it useful too.</p>
<p>Ever since then I occasionally thought about writing about it, but never actually got around to it.
In the meantime I ended up doing other stuff, so this is more of a collection of some things I worked on in the past ~4 months instead of a focused post.</p>
<h2 id="being-fed-up-with-gnome">Being fed up with GNOME<a href="#being-fed-up-with-gnome" aria-label="Link to heading 'Being fed up with GNOME'" data-heading-content="Being fed up with GNOME" class="anchor"></a></h2>
<p>Every since I fully switched to Linux in August of 2023 I’ve been using GNOME.
In the past I’ve mainly used Xfce (and for a bit i3) on various laptops I used for uni.
At work I had a virtual machine that’s running openSUSE<sup class="footnote-ref"><a href="#fn-nixos" id="fnref-nixos" data-footnote-ref>1</a></sup> with Xfce.
The one thing all of these machines had in common is that they either had not-that-great performance or not-that-great battery life (or both), so using something lightweight like Xfce felt like the right choice.</p>
<p>So when I decided to switch to Linux on my main desktop PC I didn’t have to think about any of these restrictions for the first time.
On top of that I also wanted to try out Wayland – which was enough of a reason for me to give GNOME a shot.</p>
<p>The things I like about GNOME are</p>
<ol>
<li>That it’s a complete package, I don’t have to manage and configure different components myself.</li>
<li>That it looks good enough out of the box.
(I could never warm up to how KDE looks and themes don’t make it any better.)</li>
<li>It can be really easily configured to look <em>even better</em> with plugins like <a href="https://github.com/micheleg/dash-to-dock">Dash to Dock</a> and <a href="https://github.com/aunetx/blur-my-shell">Blur my Shell</a>.</li>
</ol>
<p>If there’s one thing you should take away from this is that I really like the look of a semi-transparent panel with a blur effect.
Even on Windows I installed similar things to change the appearance of the taskbar.</p>
<p>So I was more or less happily using GNOME for 1.5 years.
It had its occasional issues, but the way everything looked was always enough of a reason for me to <em>look</em> past them.</p>
<p>Then it ended up happening more and more frequently that GNOME would just crash.
Either directly on login or very closely after when I opened a game for example.
The system journal always pointed to an issue in some extension but it was hard to pinpoint what the exactly was the cause.</p>
<p>And exactly that is my primary problem with GNOME: The extensions.
The API is unstable which means with every new version you first have to wait for the extensions to be compatible again in order to enjoy all the things you like about customizing GNOME (the blur!!).
And on top of that it’s all a pile of JavaScript which doesn’t make it very pleasant to write an extension.</p>
<p>I know because I even wrote my own<sup class="footnote-ref"><a href="#fn-showtopbar" id="fnref-showtopbar" data-footnote-ref>2</a></sup> GNOME extension in those 1.5 years and specifically chose to use the <a href="https://gjs.guide/extensions/development/typescript.html">TypeScript type definitions</a> to make the whole experience less painful, and while it did make it better it was not great (and at least back then the types weren’t fully up to date with the latest GNOME version).</p>
<h2 id="putting-fire-in-my-way-its-a-wayfire-pun">Putting Fire in my Way (it’s a Wayfire pun)<a href="#putting-fire-in-my-way-its-a-wayfire-pun" aria-label="Link to heading 'Putting Fire in my Way (it’s a Wayfire pun)'" data-heading-content="Putting Fire in my Way (it’s a Wayfire pun)" class="anchor"></a></h2>
<p>So in March I started trying out other floating window managers with Wayland support.
I already ruled out KDE so that didn’t leave that many options.</p>
<p>At first I tried <a href="https://labwc.github.io/">labwc</a> because it felt closer to the things I like about Xfce, but it didn’t offer that many customization options and most importantly didn’t support any blur effects.</p>
<p>So after giving up on the idea for a short bit and going back to GNOME I gave <a href="https://wayfire.org/">Wayfire</a> a try.
I had already tried it in the past but didn’t feel like putting all the effort into setting up all the extra services I’d need (for having a nice panel and notifications and …).
But I decided to give it another try because… it has blur effects.</p>
<p>Wayfire is funny because when you look at videos of it it feels like it’s <em>too much</em>. <em>Too playful</em>.
There’s the cube plugin, there’s wobbly windows, there’s fire effects.
My impression up until then was “this is the compositor for if you want complete animation overload in your desktop”.
But I wanted to give it a try (blur effects!!) and thus configured the minimal things I’d want to have in order to try it out for a few weeks:</p>
<ol>
<li>A <a href="https://github.com/Alexays/Waybar">Waybar</a> configuration that very closely mimics the GNOME panel (with blur effects!)</li>
<li>A program launcher – finally getting to use Rofi, or rather its <a href="https://github.com/lbonn/rofi">Wayland fork</a>, again (I really missed this from Xfce)</li>
<li>The necessary keybinds for things I commonly in order to feel right at home</li>
</ol>
<p>And it was good enough!
I could do almost everything the way I was used, it looked good, and I didn’t have any random crashes anymore.</p>
<p>But there was one thing I didn’t like about Wayfire and that was the lack of a proper window switcher.
Or rather, one that looked good.</p>
<p>I tried some of the integrated options and plugins other people wrote, but I didn’t like any of them.
So I ended up doing two separate things that will eventually (I feel like this blog post is getting too long already) lead me to my most recent project:</p>
<ol>
<li>Write a Wayfire plugin</li>
<li>Write a Rofi script</li>
</ol>
<h1 id="creating-a-pretty-plugin-this-is-a-c-pun">Creating a Pretty Plugin (this is a C++ pun)<a href="#creating-a-pretty-plugin-this-is-a-c-pun" aria-label="Link to heading 'Creating a Pretty Plugin (this is a C++ pun)'" data-heading-content="Creating a Pretty Plugin (this is a C++ pun)" class="anchor"></a></h1>
<p>Another thing I really missed from GNOME was the Activity Overview.
I might like it even more than the blur effects and I dearly miss it when I use Windows for work.
To me it is the perfect way to switch between windows when there’s more than a couple open: You press the Super key, all windows get arranged so they are visible at the same time and <em>roughly</em> in the spot they were before, you click on a window to focus it and the Activity Overview closes.
It’s such a pleasant user experience.</p>
<p>So I wondered: How hard could it be to write my own plugin for Wayfire that does exactly that?</p>
<p>I knew it must be possible because Wayfire ships with a <a href="https://github.com/WayfireWM/wayfire/wiki/Configuration#switcher">Switcher plugin</a> which already uses the concepts I would need for my own plugin:</p>
<ol>
<li>It moves and scales windows from their current position to a different one (although it only displays up to 3).</li>
<li>It allows switching between the windows and changing the focus to the newly selected one.</li>
<li>It can be opened and closed with a single hotkey.</li>
</ol>
<p>The whole plugin is around 900 lines of C++ code which seemed manageable enough for someone who’s never touched C++ before in their life, but does have a fair amount of experience in other C style languages.
I started playing around a bit with the plugin, changing small things here and there just to get a feeling for how Wayfire plugins work.</p>
<p>And the rest of the story isn’t even that exciting.
I studied the logic of the Activity Overview in GNOME, I referenced the Switcher plugin, other Wayfire plugins and even looked into the core Wayfire source code to get a better idea of how things work.</p>
<p>And after less than a month I ended up with what I titled <a href="https://codeberg.org/qtea/qwf-overview">QWF Overview</a>!
I had so, so much fun working on this and learning more about Wayfire and C++.
After not even a week of working on it (around April 1) the minimal version – which only displayed windows in a single row – worked well enough that I was using it in my main Wayfire session.</p>
<p>On April 17 I removed the GNOME session from my NixOS config because everything felt so much nicer now.</p>
<p>On April 21 I decided to release the 1.0 version of QWF Overview because it worked so well.</p>
<p>And you know what?
Now, over two months later it still works really well and I didn’t have a single issue with it.</p>
<p>This might honestly be the best thing I’ve ever programmed (ignoring that it isn’t an original idea) because I use it every single day and it makes my experience so much nicer.</p>
<h1 id="getting-rusty">Getting Rusty<a href="#getting-rusty" aria-label="Link to heading 'Getting Rusty'" data-heading-content="Getting Rusty" class="anchor"></a></h1>
<p>Lets return to before I even decided to work on QWF Overview.</p>
<p>Another thing I didn’t like about GNOME was that it doesn’t remember window positions.
There is an extension that enables this, but I only really cared about a few windows that should have fixed positions while some should <em>never</em> remember their position, and the extension only allowed you to configure a blacklist but not a whitelist.</p>
<p>The nice thing about Wayfire is that it enables you to configure window rules.
For example I always want to have Firefox open on the right side of my screen with a specific size, so I put the following config in my <code>wayfire.ini</code>:</p>
<pre class="syntax-highlighting"><code class="language-ini"><span class="sh-source sh-ini"><span class="sh-meta sh-declaration sh-ini"><span class="sh-meta sh-property sh-ini"><span class="sh-keyword sh-name sh-ini">firefox_1</span> <span class="sh-punctuation sh-definition sh-equals sh-ini">=</span></span> <span class="sh-meta sh-value sh-ini"><span class="sh-string sh-name sh-value sh-ini">on created if (app_id contains &quot;firefox&quot; &amp; !(title contains &quot;Picture-in-Picture&quot;)) then set geometry 2240 30 1200 1410</span></span>
</span><span class="sh-meta sh-declaration sh-ini"><span class="sh-meta sh-property sh-ini"><span class="sh-keyword sh-name sh-ini">popout_player_1</span> <span class="sh-punctuation sh-definition sh-equals sh-ini">=</span></span> <span class="sh-meta sh-value sh-ini"><span class="sh-string sh-name sh-value sh-ini">on created if (app_id contains &quot;firefox&quot; &amp; title contains &quot;Picture-in-Picture&quot;) then set always_on_top</span></span>
</span><span class="sh-meta sh-declaration sh-ini"><span class="sh-meta sh-property sh-ini"><span class="sh-keyword sh-name sh-ini">popout_player_2</span> <span class="sh-punctuation sh-definition sh-equals sh-ini">=</span></span> <span class="sh-meta sh-value sh-ini"><span class="sh-string sh-name sh-value sh-ini">on created if (app_id contains &quot;firefox&quot; &amp; title contains &quot;Picture-in-Picture&quot;) then move 0 30</span></span>
</span></span></code></pre>
<p>This also configures another rule so the pop out player opens in the top left corner and is always on top.
The issue with the special language for the windows rules though is that it doesn’t give you full control over the windows.
It only has commands for a subset of the features that Wayfire supports and even has issues like not supporting an <code>app_id</code> that contains a <code>.</code> (the lexer for the language tries to parse everything with a <code>.</code> as a float value, even if it is inside quotes).</p>
<p>I actually ended up looking into the Wayfire source code for the very first time because I wanted to fix the <code>.</code> issue (and did for myself), but also found out this way of configuring window rules wasn’t actively worked on anymore and the maintainer preferred if one used the IPC (inter process communication) API provided by Wayfire for this <a href="https://github.com/WayfireWM/wayfire/pull/1821">instead</a>.</p>
<p>Which finally leads us to the second thing I mentioned two sections ago: the Rofi script!</p>
<p>I still wanted a regular window switcher that would work with Alt+Tab and stumbled upon the idea of using Rofi for that.
The Wayfire IPC would allow me to query the list of all open windows and change the focus of a window.
It seemed like a pretty simple thing to do and since Rofi already looked good (because of the theme I had made for it) it should at least be a (visual) improvement over the other window switchers.</p>
<p>The <a href="https://github.com/WayfireWM/pywayfire">official bindings</a> for the Wayfire IPC are written in Python, and while I never enjoyed writing Python it looked like the fastest way to get something working.</p>
<p>I would link the Python code I initially wrote for this, but looks like I never actually committed it because it had one issue: Python is slow.</p>
<p>If you only want to position windows via the IPC it doesn’t really matter since things taking a second more or less will not be as noticeable.
But if you want to open a window switcher with Alt+Tab it should be <em>instant</em>.</p>
<p>So I came to the only logical conclusion: rewrite it in Rust.</p>
<p>I had some rough experience with Rust from trying to write a small game in it two years ago and had been looking for a reason to get back to it again, so this came at just the right time.
Luckily someone already wrote IPC bindings <a href="https://github.com/killown/wayfire-rs">for Rust</a> so I didn’t have to figure out everything by myself and could focus solely on porting the few lines of Python code.</p>
<p>I’m gonna embed the whole script at <a href="#rofi-switcher">the end of the post</a> in case anyone finds it interesting.</p>
<p>Having moved one Wayfire thing to Rust I thought “why not another one?” and ended up rewriting the window rules in Rust too.
The added control allowed me to do nicer things like only moving the first opened Firefox window to a specific spot while subsequent windows would open at the default position (in the middle of the screen).</p>
<p>And then I ended up writing another thing in Rust: <a href="https://codeberg.org/qtea/wlr-screen-fade">A small program</a> that slowly fades the screen to black so you can chain it before a command that turns your screen off after a specific amount of time in order to get a “nicer” transition to a fully black screen.
I initially wrote it using GTK4 Layer Shell (which you can still find under the 0.1.0 tag) before deciding GTK is way too heavy of a dependency for such a small thing that doesn’t even have UI and rewrote the whole thing using <a href="https://github.com/Smithay/client-toolkit">Smithay’s Client Toolkit</a> while directly rendering the increasingly black frames with <a href="https://wgpu.rs/">WGPU</a>.
There’s some minor things I haven’t bothered to fix yet, but I have been happily using it for over two months now and even decided to publish it to <a href="https://crates.io/crates/wlr-screen-fade">crates.io</a>.</p>
<h2 id="finding-joy-in-programming">Finding joy in programming?<a href="#finding-joy-in-programming" aria-label="Link to heading 'Finding joy in programming?'" data-heading-content="Finding joy in programming?" class="anchor"></a></h2>
<p>After switching to Wayfire, having lots of fun writing my own Wayfire plugin and smaller tools that make using my computer more enjoyable, I thought I might have found some joy in programming in my free time again – before completely losing all motivation shortly after.
Maybe that’s just the trade-off for mostly writing things that I need myself, which doesn’t happen that often.</p>
<p>But then a month ago I started writing something new in Rust that was useful, felt bigger, and helped me learn lots of new concepts.
And maybe I’ll even write about it in the next blog post.</p>
<p>Until then!</p>
<p><br><br><br></p>
<hr id="rofi-switcher">
<p>As promised, here is the bit of Rust I wrote to switch windows with Rofi using the Wayfire IPC.
I tried to keep it as performant as possible, but if you notice any improvements please let me know!</p>
<p>Rofi gets started by having Alt+Tab execute the following command:</p>
<pre class="syntax-highlighting"><code class="language-sh"><span class="sh-source sh-shell sh-bash"><span class="sh-meta sh-function-call sh-shell"><span class="sh-variable sh-function sh-shell">rofi</span></span><span class="sh-meta sh-function-call sh-arguments sh-shell"><span class="sh-variable sh-parameter sh-option sh-shell"><span class="sh-punctuation sh-definition sh-parameter sh-shell"> -</span>show</span> wf-switcher <span class="sh-punctuation sh-separator sh-continuation sh-line sh-shell">\
</span><span class="sh-variable sh-parameter sh-option sh-shell"><span class="sh-punctuation sh-definition sh-parameter sh-shell">  -</span>modes</span> wf-switcher:/path/to/bin/rofi-wf-switcher <span class="sh-punctuation sh-separator sh-continuation sh-line sh-shell">\
</span><span class="sh-variable sh-parameter sh-option sh-shell"><span class="sh-punctuation sh-definition sh-parameter sh-shell">  -</span>selected-row</span> 1 <span class="sh-punctuation sh-separator sh-continuation sh-line sh-shell">\
</span><span class="sh-variable sh-parameter sh-option sh-shell"><span class="sh-punctuation sh-definition sh-parameter sh-shell">  -</span>kb-accept-entry</span> <span class="sh-string sh-quoted sh-single sh-shell"><span class="sh-punctuation sh-definition sh-string sh-begin sh-shell">&#39;</span>Return,!Alt+Tab,!Alt+Alt_L,!Alt_L<span class="sh-punctuation sh-definition sh-string sh-end sh-shell">&#39;</span></span> <span class="sh-punctuation sh-separator sh-continuation sh-line sh-shell">\
</span><span class="sh-variable sh-parameter sh-option sh-shell"><span class="sh-punctuation sh-definition sh-parameter sh-shell">  -</span>kb-row-up</span> <span class="sh-string sh-quoted sh-single sh-shell"><span class="sh-punctuation sh-definition sh-string sh-begin sh-shell">&#39;</span>Alt+ISO_Left_Tab<span class="sh-punctuation sh-definition sh-string sh-end sh-shell">&#39;</span></span> <span class="sh-punctuation sh-separator sh-continuation sh-line sh-shell">\
</span><span class="sh-variable sh-parameter sh-option sh-shell"><span class="sh-punctuation sh-definition sh-parameter sh-shell">  -</span>kb-row-down</span> <span class="sh-string sh-quoted sh-single sh-shell"><span class="sh-punctuation sh-definition sh-string sh-begin sh-shell">&#39;</span>Alt+Tab<span class="sh-punctuation sh-definition sh-string sh-end sh-shell">&#39;</span></span> <span class="sh-punctuation sh-separator sh-continuation sh-line sh-shell">\
</span><span class="sh-variable sh-parameter sh-option sh-shell"><span class="sh-punctuation sh-definition sh-parameter sh-shell">  -</span>theme-str</span> <span class="sh-string sh-quoted sh-single sh-shell"><span class="sh-punctuation sh-definition sh-string sh-begin sh-shell">&#39;</span>mainbox { children: [ message, listview ]; }<span class="sh-punctuation sh-definition sh-string sh-end sh-shell">&#39;</span></span></span>
</span></code></pre>
<p>And <code>rofi-wf-switcher</code> gets compiled from the following bit of code:</p>
<pre class="syntax-highlighting"><code class="language-rs"><span class="sh-source sh-rust"><span class="sh-keyword sh-other sh-rust">use</span> <span class="sh-meta sh-path sh-rust">std<span class="sh-punctuation sh-accessor sh-rust">::</span></span><span class="sh-meta sh-path sh-rust">cmp<span class="sh-punctuation sh-accessor sh-rust">::</span></span>Reverse<span class="sh-punctuation sh-terminator sh-rust">;</span>
<span class="sh-keyword sh-other sh-rust">use</span> <span class="sh-meta sh-path sh-rust">std<span class="sh-punctuation sh-accessor sh-rust">::</span></span>env<span class="sh-punctuation sh-terminator sh-rust">;</span>
<span class="sh-keyword sh-other sh-rust">use</span> <span class="sh-meta sh-path sh-rust">std<span class="sh-punctuation sh-accessor sh-rust">::</span></span><span class="sh-meta sh-path sh-rust">io<span class="sh-punctuation sh-accessor sh-rust">::</span></span><span class="sh-meta sh-block sh-rust"><span class="sh-punctuation sh-section sh-block sh-begin sh-rust">{</span>BufWriter<span class="sh-punctuation sh-separator sh-rust">,</span> Write<span class="sh-punctuation sh-separator sh-rust">,</span> stdout</span><span class="sh-meta sh-block sh-rust"><span class="sh-punctuation sh-section sh-block sh-end sh-rust">}</span></span><span class="sh-punctuation sh-terminator sh-rust">;</span>

<span class="sh-keyword sh-other sh-rust">use</span> <span class="sh-meta sh-path sh-rust">wayfire_rs<span class="sh-punctuation sh-accessor sh-rust">::</span></span><span class="sh-meta sh-path sh-rust">ipc<span class="sh-punctuation sh-accessor sh-rust">::</span></span>WayfireSocket<span class="sh-punctuation sh-terminator sh-rust">;</span>

<span class="sh-meta sh-annotation sh-rust"><span class="sh-punctuation sh-definition sh-annotation sh-rust">#</span><span class="sh-punctuation sh-section sh-group sh-begin sh-rust">[</span><span class="sh-variable sh-annotation sh-rust">pollster</span>::<span class="sh-variable sh-annotation sh-rust">main</span><span class="sh-punctuation sh-section sh-group sh-end sh-rust">]</span></span>
async <span class="sh-meta sh-function sh-rust"><span class="sh-meta sh-function sh-rust"><span class="sh-storage sh-type sh-function sh-rust">fn</span> </span><span class="sh-entity sh-name sh-function sh-rust">main</span></span><span class="sh-meta sh-function sh-rust"><span class="sh-meta sh-function sh-parameters sh-rust"><span class="sh-punctuation sh-section sh-parameters sh-begin sh-rust">(</span></span><span class="sh-meta sh-function sh-rust"><span class="sh-meta sh-function sh-parameters sh-rust"><span class="sh-punctuation sh-section sh-parameters sh-end sh-rust">)</span></span></span></span><span class="sh-meta sh-function sh-rust"> </span><span class="sh-meta sh-function sh-rust"><span class="sh-meta sh-block sh-rust"><span class="sh-punctuation sh-section sh-block sh-begin sh-rust">{</span>
    <span class="sh-storage sh-type sh-rust">let</span> <span class="sh-storage sh-modifier sh-rust">mut</span> sock <span class="sh-keyword sh-operator sh-assignment sh-rust">=</span> <span class="sh-meta sh-path sh-rust">WayfireSocket<span class="sh-punctuation sh-accessor sh-rust">::</span></span>connect<span class="sh-meta sh-group sh-rust"><span class="sh-punctuation sh-section sh-group sh-begin sh-rust">(</span></span><span class="sh-meta sh-group sh-rust"><span class="sh-punctuation sh-section sh-group sh-end sh-rust">)</span></span><span class="sh-punctuation sh-accessor sh-dot sh-rust">.</span>await<span class="sh-punctuation sh-accessor sh-dot sh-rust">.</span><span class="sh-support sh-function sh-rust">unwrap</span><span class="sh-meta sh-group sh-rust"><span class="sh-punctuation sh-section sh-group sh-begin sh-rust">(</span></span><span class="sh-meta sh-group sh-rust"><span class="sh-punctuation sh-section sh-group sh-end sh-rust">)</span></span><span class="sh-punctuation sh-terminator sh-rust">;</span>

    <span class="sh-storage sh-type sh-rust">let</span> args<span class="sh-punctuation sh-separator sh-rust">:</span> <span class="sh-meta sh-generic sh-rust"><span class="sh-support sh-type sh-rust">Vec</span><span class="sh-punctuation sh-definition sh-generic sh-begin sh-rust">&lt;</span><span class="sh-support sh-type sh-rust">String</span><span class="sh-punctuation sh-definition sh-generic sh-end sh-rust">&gt;</span></span> <span class="sh-keyword sh-operator sh-assignment sh-rust">=</span> <span class="sh-meta sh-path sh-rust">env<span class="sh-punctuation sh-accessor sh-rust">::</span></span>args<span class="sh-meta sh-group sh-rust"><span class="sh-punctuation sh-section sh-group sh-begin sh-rust">(</span></span><span class="sh-meta sh-group sh-rust"><span class="sh-punctuation sh-section sh-group sh-end sh-rust">)</span></span><span class="sh-punctuation sh-accessor sh-dot sh-rust">.</span><span class="sh-support sh-function sh-rust">collect</span><span class="sh-meta sh-group sh-rust"><span class="sh-punctuation sh-section sh-group sh-begin sh-rust">(</span></span><span class="sh-meta sh-group sh-rust"><span class="sh-punctuation sh-section sh-group sh-end sh-rust">)</span></span><span class="sh-punctuation sh-terminator sh-rust">;</span>

    <span class="sh-keyword sh-control sh-rust">if</span> args<span class="sh-punctuation sh-accessor sh-dot sh-rust">.</span><span class="sh-support sh-function sh-rust">len</span><span class="sh-meta sh-group sh-rust"><span class="sh-punctuation sh-section sh-group sh-begin sh-rust">(</span></span><span class="sh-meta sh-group sh-rust"><span class="sh-punctuation sh-section sh-group sh-end sh-rust">)</span></span> <span class="sh-keyword sh-operator sh-comparison sh-rust">==</span> <span class="sh-constant sh-numeric sh-integer sh-decimal sh-rust">2</span> <span class="sh-meta sh-block sh-rust"><span class="sh-punctuation sh-section sh-block sh-begin sh-rust">{</span>
        <span class="sh-storage sh-type sh-rust">let</span> id <span class="sh-keyword sh-operator sh-assignment sh-rust">=</span> args<span class="sh-meta sh-group sh-rust"><span class="sh-punctuation sh-section sh-group sh-begin sh-rust">[</span><span class="sh-constant sh-numeric sh-integer sh-decimal sh-rust">1</span><span class="sh-punctuation sh-section sh-group sh-end sh-rust">]</span></span><span class="sh-punctuation sh-accessor sh-dot sh-rust">.</span><span class="sh-meta sh-path sh-rust">parse<span class="sh-punctuation sh-accessor sh-rust">::</span></span><span class="sh-meta sh-generic sh-rust"><span class="sh-punctuation sh-definition sh-generic sh-begin sh-rust">&lt;</span><span class="sh-storage sh-type sh-rust">i64</span><span class="sh-punctuation sh-definition sh-generic sh-end sh-rust">&gt;</span></span><span class="sh-meta sh-group sh-rust"><span class="sh-punctuation sh-section sh-group sh-begin sh-rust">(</span></span><span class="sh-meta sh-group sh-rust"><span class="sh-punctuation sh-section sh-group sh-end sh-rust">)</span></span><span class="sh-punctuation sh-accessor sh-dot sh-rust">.</span><span class="sh-support sh-function sh-rust">expect</span><span class="sh-meta sh-group sh-rust"><span class="sh-punctuation sh-section sh-group sh-begin sh-rust">(</span><span class="sh-string sh-quoted sh-double sh-rust"><span class="sh-punctuation sh-definition sh-string sh-begin sh-rust">&quot;</span>did not get view id as int<span class="sh-punctuation sh-definition sh-string sh-end sh-rust">&quot;</span></span></span><span class="sh-meta sh-group sh-rust"><span class="sh-punctuation sh-section sh-group sh-end sh-rust">)</span></span><span class="sh-punctuation sh-terminator sh-rust">;</span>
        <span class="sh-comment sh-line sh-double-slash sh-rust"><span class="sh-punctuation sh-definition sh-comment sh-rust">//</span> ignore errors
</span>        <span class="sh-storage sh-type sh-rust">let</span> <span class="sh-keyword sh-operator sh-rust">_</span> <span class="sh-keyword sh-operator sh-assignment sh-rust">=</span> sock<span class="sh-punctuation sh-accessor sh-dot sh-rust">.</span><span class="sh-support sh-function sh-rust">set_focus</span><span class="sh-meta sh-group sh-rust"><span class="sh-punctuation sh-section sh-group sh-begin sh-rust">(</span>id</span><span class="sh-meta sh-group sh-rust"><span class="sh-punctuation sh-section sh-group sh-end sh-rust">)</span></span><span class="sh-punctuation sh-accessor sh-dot sh-rust">.</span>await<span class="sh-punctuation sh-terminator sh-rust">;</span>
        <span class="sh-keyword sh-control sh-rust">return</span><span class="sh-punctuation sh-terminator sh-rust">;</span>
    </span><span class="sh-meta sh-block sh-rust"><span class="sh-punctuation sh-section sh-block sh-end sh-rust">}</span></span>

    <span class="sh-storage sh-type sh-rust">let</span> <span class="sh-storage sh-modifier sh-rust">mut</span> toplevels <span class="sh-keyword sh-operator sh-assignment sh-rust">=</span> <span class="sh-keyword sh-control sh-rust">match</span> sock<span class="sh-punctuation sh-accessor sh-dot sh-rust">.</span><span class="sh-support sh-function sh-rust">list_views</span><span class="sh-meta sh-group sh-rust"><span class="sh-punctuation sh-section sh-group sh-begin sh-rust">(</span></span><span class="sh-meta sh-group sh-rust"><span class="sh-punctuation sh-section sh-group sh-end sh-rust">)</span></span><span class="sh-punctuation sh-accessor sh-dot sh-rust">.</span>await <span class="sh-meta sh-block sh-rust"><span class="sh-punctuation sh-section sh-block sh-begin sh-rust">{</span>
        <span class="sh-support sh-type sh-rust">Ok</span><span class="sh-meta sh-group sh-rust"><span class="sh-punctuation sh-section sh-group sh-begin sh-rust">(</span>view</span><span class="sh-meta sh-group sh-rust"><span class="sh-punctuation sh-section sh-group sh-end sh-rust">)</span></span> <span class="sh-keyword sh-operator sh-rust">=&gt;</span> view<span class="sh-punctuation sh-separator sh-rust">,</span>
        <span class="sh-support sh-type sh-rust">Err</span><span class="sh-meta sh-group sh-rust"><span class="sh-punctuation sh-section sh-group sh-begin sh-rust">(</span>e</span><span class="sh-meta sh-group sh-rust"><span class="sh-punctuation sh-section sh-group sh-end sh-rust">)</span></span> <span class="sh-keyword sh-operator sh-rust">=&gt;</span> <span class="sh-meta sh-block sh-rust"><span class="sh-punctuation sh-section sh-block sh-begin sh-rust">{</span>
            <span class="sh-support sh-macro sh-rust">eprintln!</span><span class="sh-meta sh-group sh-rust"><span class="sh-punctuation sh-section sh-group sh-begin sh-rust">(</span></span><span class="sh-meta sh-group sh-rust"><span class="sh-string sh-quoted sh-double sh-rust"><span class="sh-punctuation sh-definition sh-string sh-begin sh-rust">&quot;</span>Failed to get views: <span class="sh-constant sh-other sh-placeholder sh-rust">{}</span><span class="sh-punctuation sh-definition sh-string sh-end sh-rust">&quot;</span></span></span><span class="sh-meta sh-group sh-rust"><span class="sh-punctuation sh-separator sh-rust">,</span> e<span class="sh-punctuation sh-section sh-group sh-end sh-rust">)</span></span><span class="sh-punctuation sh-terminator sh-rust">;</span>
            <span class="sh-keyword sh-control sh-rust">return</span><span class="sh-punctuation sh-terminator sh-rust">;</span>
        </span><span class="sh-meta sh-block sh-rust"><span class="sh-punctuation sh-section sh-block sh-end sh-rust">}</span></span>
    </span><span class="sh-meta sh-block sh-rust"><span class="sh-punctuation sh-section sh-block sh-end sh-rust">}</span></span><span class="sh-punctuation sh-terminator sh-rust">;</span>

    toplevels<span class="sh-punctuation sh-accessor sh-dot sh-rust">.</span><span class="sh-support sh-function sh-rust">retain</span><span class="sh-meta sh-group sh-rust"><span class="sh-punctuation sh-section sh-group sh-begin sh-rust">(</span>is_mapped_toplevel</span><span class="sh-meta sh-group sh-rust"><span class="sh-punctuation sh-section sh-group sh-end sh-rust">)</span></span><span class="sh-punctuation sh-terminator sh-rust">;</span>
    toplevels<span class="sh-punctuation sh-accessor sh-dot sh-rust">.</span><span class="sh-support sh-function sh-rust">sort_unstable_by_key</span><span class="sh-meta sh-group sh-rust"><span class="sh-punctuation sh-section sh-group sh-begin sh-rust">(</span><span class="sh-meta sh-function sh-closure sh-rust"><span class="sh-meta sh-function sh-parameters sh-rust"><span class="sh-punctuation sh-section sh-parameters sh-begin sh-rust">|</span></span></span><span class="sh-meta sh-function sh-closure sh-rust"><span class="sh-meta sh-function sh-parameters sh-rust"><span class="sh-variable sh-parameter sh-rust">v</span><span class="sh-punctuation sh-section sh-parameters sh-end sh-rust">|</span></span> </span><span class="sh-meta sh-function sh-closure sh-rust">Reverse<span class="sh-meta sh-group sh-rust"><span class="sh-punctuation sh-section sh-group sh-begin sh-rust">(</span>v<span class="sh-punctuation sh-accessor sh-dot sh-rust">.</span>last_focus_timestamp</span><span class="sh-meta sh-group sh-rust"><span class="sh-punctuation sh-section sh-group sh-end sh-rust">)</span></span></span></span><span class="sh-meta sh-group sh-rust"><span class="sh-punctuation sh-section sh-group sh-end sh-rust">)</span></span><span class="sh-punctuation sh-terminator sh-rust">;</span>

    <span class="sh-storage sh-type sh-rust">let</span> lock <span class="sh-keyword sh-operator sh-assignment sh-rust">=</span> <span class="sh-support sh-function sh-rust">stdout</span><span class="sh-meta sh-group sh-rust"><span class="sh-punctuation sh-section sh-group sh-begin sh-rust">(</span></span><span class="sh-meta sh-group sh-rust"><span class="sh-punctuation sh-section sh-group sh-end sh-rust">)</span></span><span class="sh-punctuation sh-accessor sh-dot sh-rust">.</span><span class="sh-support sh-function sh-rust">lock</span><span class="sh-meta sh-group sh-rust"><span class="sh-punctuation sh-section sh-group sh-begin sh-rust">(</span></span><span class="sh-meta sh-group sh-rust"><span class="sh-punctuation sh-section sh-group sh-end sh-rust">)</span></span><span class="sh-punctuation sh-terminator sh-rust">;</span>
    <span class="sh-storage sh-type sh-rust">let</span> <span class="sh-storage sh-modifier sh-rust">mut</span> writer <span class="sh-keyword sh-operator sh-assignment sh-rust">=</span> <span class="sh-meta sh-path sh-rust">BufWriter<span class="sh-punctuation sh-accessor sh-rust">::</span></span>new<span class="sh-meta sh-group sh-rust"><span class="sh-punctuation sh-section sh-group sh-begin sh-rust">(</span>lock</span><span class="sh-meta sh-group sh-rust"><span class="sh-punctuation sh-section sh-group sh-end sh-rust">)</span></span><span class="sh-punctuation sh-terminator sh-rust">;</span>
    <span class="sh-keyword sh-control sh-rust">for</span> v <span class="sh-keyword sh-operator sh-rust">in</span> toplevels <span class="sh-meta sh-block sh-rust"><span class="sh-punctuation sh-section sh-block sh-begin sh-rust">{</span>
        <span class="sh-support sh-macro sh-rust">writeln!</span><span class="sh-meta sh-group sh-rust"><span class="sh-punctuation sh-section sh-group sh-begin sh-rust">(</span></span><span class="sh-meta sh-group sh-rust">writer,</span><span class="sh-meta sh-group sh-rust"> <span class="sh-string sh-quoted sh-double sh-rust"><span class="sh-punctuation sh-definition sh-string sh-begin sh-rust">&quot;</span><span class="sh-constant sh-other sh-placeholder sh-rust">{}</span><span class="sh-constant sh-character sh-escape sh-rust">\0</span>display<span class="sh-constant sh-character sh-escape sh-rust">\x1f</span><span class="sh-constant sh-other sh-placeholder sh-rust">{}</span> (<span class="sh-constant sh-other sh-placeholder sh-rust">{}</span>)<span class="sh-punctuation sh-definition sh-string sh-end sh-rust">&quot;</span></span></span><span class="sh-meta sh-group sh-rust"><span class="sh-punctuation sh-separator sh-rust">,</span> v<span class="sh-punctuation sh-accessor sh-dot sh-rust">.</span>id<span class="sh-punctuation sh-separator sh-rust">,</span> v<span class="sh-punctuation sh-accessor sh-dot sh-rust">.</span>app_id<span class="sh-punctuation sh-separator sh-rust">,</span> v<span class="sh-punctuation sh-accessor sh-dot sh-rust">.</span>title<span class="sh-punctuation sh-section sh-group sh-end sh-rust">)</span></span><span class="sh-punctuation sh-accessor sh-dot sh-rust">.</span><span class="sh-support sh-function sh-rust">unwrap</span><span class="sh-meta sh-group sh-rust"><span class="sh-punctuation sh-section sh-group sh-begin sh-rust">(</span></span><span class="sh-meta sh-group sh-rust"><span class="sh-punctuation sh-section sh-group sh-end sh-rust">)</span></span><span class="sh-punctuation sh-terminator sh-rust">;</span>
    </span><span class="sh-meta sh-block sh-rust"><span class="sh-punctuation sh-section sh-block sh-end sh-rust">}</span></span>
    writer<span class="sh-punctuation sh-accessor sh-dot sh-rust">.</span><span class="sh-support sh-function sh-rust">flush</span><span class="sh-meta sh-group sh-rust"><span class="sh-punctuation sh-section sh-group sh-begin sh-rust">(</span></span><span class="sh-meta sh-group sh-rust"><span class="sh-punctuation sh-section sh-group sh-end sh-rust">)</span></span><span class="sh-punctuation sh-accessor sh-dot sh-rust">.</span><span class="sh-support sh-function sh-rust">unwrap</span><span class="sh-meta sh-group sh-rust"><span class="sh-punctuation sh-section sh-group sh-begin sh-rust">(</span></span><span class="sh-meta sh-group sh-rust"><span class="sh-punctuation sh-section sh-group sh-end sh-rust">)</span></span><span class="sh-punctuation sh-terminator sh-rust">;</span>
</span><span class="sh-meta sh-block sh-rust"><span class="sh-punctuation sh-section sh-block sh-end sh-rust">}</span></span></span>
</span></code></pre>
<section class="footnotes" data-footnotes>
<ol>
<li id="fn-nixos">
<p>Before I ended up switching every single machine to NixOS <a href="#fnref-nixos" class="footnote-backref" data-footnote-backref data-footnote-backref-idx="1" aria-label="Back to reference 1">↩</a></p>
</li>
<li id="fn-showtopbar">
<p>It’s called <a href="https://codeberg.org/qtea/showtopbar">Show Top Bar</a> and a fork of <a href="https://gitlab.gnome.org/tuxor1337/hidetopbar">Hide Top Bar</a> which pretty much reverses its behavior because I wanted the panel to always be visible <em>except</em> for when a fullscreen window is open. <a href="#fnref-showtopbar" class="footnote-backref" data-footnote-backref data-footnote-backref-idx="2" aria-label="Back to reference 2">↩</a></p>
</li>
</ol>
</section>
]]></description><guid>https://qtea.me/posts/occasional-joy-in-programming/</guid><pubDate>Tue, 1 Jul 2025 00:00:00 +0000</pubDate></item><item><title>Adding Cool Stuff to my website</title><link>https://qtea.me/posts/adding-cool-stuff-to-my-website/</link><description><![CDATA[<p>I updated my website about a month ago!</p>
<p>Did anyone notice?</p>
<h2 id="the-idea">The Idea<a href="#the-idea" aria-label="Link to heading 'The Idea'" data-heading-content="The Idea" class="anchor"></a></h2>
<p>Surely you’ve seen some websites around that have a “now playing widget” or something similar.</p>
<p>At the start of December I thought it would be nice to add something like that to my website, but in a completely static way.
The easy way definitely would’ve been to just slam some JavaScript or a premade widget in there that fetched the data anew every time someone visited the site.</p>
<p>Done. <br />
Don’t worry about it. <br />
Someone else already figured it out.</p>
<p>But I didn’t want that.</p>
<p>You may not have noticed, but my website currently doesn’t rely on any JavaScript at all – and I’m trying to keep it that way.<sup class="footnote-ref"><a href="#fn-analytics" id="fnref-analytics" data-footnote-ref>1</a></sup></p>
<p>Doing it statically (automatically rebuilding the website for example once a week so it can get new info about what I recently listened to) would have been a bit difficult though - since the way I previously built my website was a bit of a mess.</p>
<h2 id="a-bit-of-a-mess">A Bit of a Mess<a href="#a-bit-of-a-mess" aria-label="Link to heading 'A Bit of a Mess'" data-heading-content="A Bit of a Mess" class="anchor"></a></h2>
<p>My website pretty much evolved in two stages.</p>
<h3 id="1-a-page-to-call-home">1. A Page to Call Home<a href="#1-a-page-to-call-home" aria-label="Link to heading '1. A Page to Call Home'" data-heading-content="1. A Page to Call Home" class="anchor"></a></h3>
<p>I added the home page in September of 2013 to have a personal site with some info about myself.</p>
<p>In March of 2024 I decided to make it look a bit nicer after watching <a href="https://anilist.co/anime/101316/Irozuku-Sekai-no-Ashita-kara/">IRODUKU: The World in Colors</a> (good anime, can recommend).</p>
<p>At this point it was a single HTML file that contained everything and I didn’t have much of a desire to add more to it.</p>
<h3 id="2-guess-im-writing-blog-posts-now">2. Guess I’m Writing Blog Posts Now<a href="#2-guess-im-writing-blog-posts-now" aria-label="Link to heading '2. Guess I’m Writing Blog Posts Now'" data-heading-content="2. Guess I’m Writing Blog Posts Now" class="anchor"></a></h3>
<p>Then in October of 2024 I felt like writing a post about how I <a href="../deciding-to-write-a-static-sitegen/">decided to write a static site generator</a> and suddenly needed somewhere to publish it.</p>
<p>So I went with the obvious and quick solution of copying the layout of my home page and turning it into a template that I could use with <a href="https://pandoc.org/">Pandoc</a>.
Pandoc would convert the Markdown posts to HTML and I could focus on the writing – instead of making sure my website was easy to maintain and extend in case I suddenly felt like adding more stuff to it.
Surely that would never happen.</p>
<p>After I saw <a href="https://pixelde.su/">Andy</a> post about the advantages of RSS feeds I quickly threw <a href="https://github.com/chambln/pandoc-rss">pandoc-rss</a> in there so I had one (and made some <a href="https://github.com/teatwig/pandoc-rss">minor adjustments</a>) and tied all of that together with a shell script.</p>
<p>Every time I added a new blog post I had to add the link to the <a href="/posts/">overview page</a> because I didn’t feel like adding another Pandoc template – and then manually built (ran the shell script) and deployed everything to <a href="https://codeberg.page/">Codeberg Pages</a>.</p>
<p>That’s good enough for writing some blog posts.</p>
<p>If for whatever reason you are interested in how exactly all of that looked like feel free to the check out the <a href="https://codeberg.org/qtea/me/src/tag/pandoc-for-blogpost">pandoc-for-blogpost tag</a> in my repository.</p>
<p>Okay, so I if I wanted to add some music stats I’d need to write new code to fetch them on each build.
Which I could’ve done with more shell scripts and more Pandoc, but I didn’t really like the idea and I also wasn’t too happy that a lot of HTML was currently duplicated between the home page, the posts overview page, and the Pandoc template for individual posts.</p>
<p>Of course, this left me with the only sane™ solution.</p>
<h2 id="rewrite-it-in-rust">Rewrite It In Rust<a href="#rewrite-it-in-rust" aria-label="Link to heading 'Rewrite It In Rust'" data-heading-content="Rewrite It In Rust" class="anchor"></a></h2>
<p>Over the past year I’ve written a lot of Rust for mostly personal stuff and overall I enjoy using the language.</p>
<p>Now you might ask “don’t you have your really cool static site generator written in Elixir that you even <a href="../deciding-to-write-a-static-sitegen/">wrote</a> <a href="../i-thought-you-wanted-to-write-a-sitegen/">two</a> blog posts about??” – and you would be completely right!</p>
<p>At first I thought about porting my site to <a href="https://codeberg.org/qtea/ocarrd">Ocarrd</a> and then add some features for the music stats and whatever else I could think of, but the main thing that stopped me was the library ecosystem.
There didn’t seem to be a nice Elixir library for generating RSS feeds, and the ones I could find were either interfacing with libraries written in other languages (kinda defeating the point) or simply hadn’t been updated in ages.</p>
<p>Rust on the other hand has a really nice <a href="https://github.com/rust-syndication/rss">library for generating RSS feeds</a> which I had previously played around with.
And if I felt like adding an Atom feed down the line it would only require a couple lines of code.</p>
<p><del>And I just enjoy writing Rust more at the moment.</del></p>
<p>So with that decision out of the way I stumbled upon the next one which took me a lot longer.</p>
<h3 id="do-all-web-template-engines-suck">Do All Web Template Engines Suck?<a href="#do-all-web-template-engines-suck" aria-label="Link to heading 'Do All Web Template Engines Suck?'" data-heading-content="Do All Web Template Engines Suck?" class="anchor"></a></h3>
<p>If you read any of the previous posts this might seem a bit familiar.</p>
<p>Since my website is mostly HTML with some few dynamic bits thrown in there I wanted to keep the focus on the HTML and decided to use a template engine instead of a code first approach like I did last time.</p>
<p>The basic idea is the same as what I had already done with Pandoc: Have an HTML file with some <code>$fancy-placeholder$</code> in there that could be replaced with the title of the page or the content of a blog post when building the site.</p>
<p>I eventually ended up working myself through the Rust template engines linked on <a href="https://github.com/askama-rs/template-benchmark">this</a> repository because it was a decently complete overview of everything available.</p>
<p>This might be me not figuring out how to do it, but I wasn’t able to use pretty much any of them because they didn’t support a very basic use case: Having optional parameters to give to a parent template.</p>
<p>My home page applies a specific CSS class to the <code>&lt;body&gt;</code> element so I can properly position stuff to make the background work.
So the home page needs to say “hey I import the base template, and I want to set this specific class on it”, whereas all the other pages simply import the base template.</p>
<p>Or if an engine did support this it was in an extremely verbose way.</p>
<p>Or it was constrained by the fact that Rust is just not a good language for doing dynamic things and I’d need to precisely specify every parameter that each different template needs.</p>
<p>Or I simply hated its syntax.</p>
<p>Rambling aside: I’m really glad that <a href="https://handlebarsjs.com/">Handlebars</a> exists.
It supports everything I want and has a decently pleasant syntax.</p>
<p>Here’s a really short example of how it looks like:</p>
<pre class="syntax-highlighting"><code class="language-html"><span class="sh-text sh-html sh-basic">{{#&gt; base body_class=&quot;home&quot; }}
{{#*inline &quot;base_content&quot;}}
<span class="sh-meta sh-tag sh-other sh-html"><span class="sh-punctuation sh-definition sh-tag sh-begin sh-html">&lt;</span></span><span class="sh-meta sh-tag sh-other sh-html"><span class="sh-entity sh-name sh-tag sh-other sh-html">main</span><span class="sh-punctuation sh-definition sh-tag sh-end sh-html">&gt;</span></span>
  {{&gt; layout_content}}
<span class="sh-meta sh-tag sh-other sh-html"><span class="sh-punctuation sh-definition sh-tag sh-begin sh-html">&lt;/</span></span><span class="sh-meta sh-tag sh-other sh-html"><span class="sh-entity sh-name sh-tag sh-other sh-html">main</span><span class="sh-punctuation sh-definition sh-tag sh-end sh-html">&gt;</span></span>
{{/inline}}
{{/base}}
</span></code></pre>
<ol>
<li>I extend from the <code>base</code> template and specify an optional <code>body_class</code>.</li>
<li>I define a <code>base_content</code> block that will replace the corresponding <code>{{&gt; base_content}}</code> in the <code>base</code> template.</li>
<li>I write some HTML specific to this template.</li>
<li>And then I create an insertion point named <code>layout_content</code> that other templates can use to add their own content.</li>
</ol>
<p>Feel free to check out all the templates I wrote in my <a href="https://codeberg.org/qtea/me/src/branch/main/data/templates">repository</a>.</p>
<p>This feels more flexible and nicer than for example <a href="https://jinja.palletsprojects.com/">Jinja</a> (at least to me) and motivated me to actually finish rewriting my website.</p>
<p>What came out of it after three days of intense getting-things-done was a new Rust application which I called <em>mersy</em><sup class="footnote-ref"><a href="#fn-mersy-name" id="fnref-mersy-name" data-footnote-ref>2</a></sup> and a separate directory containing all the templates, Markdown posts, and other static files (all living in the same <a href="https://codeberg.org/qtea/me">repository</a>).</p>
<p>The whole thing went live on the qtea dot me website on December 7 – and everyone was in awe at the improved build process which changed absolutely nothing about what the site looked like.<sup class="footnote-ref"><a href="#fn-comrak" id="fnref-comrak" data-footnote-ref>3</a></sup></p>
<p>Which is nice.
I spent all this time working on something to make it “nicer” – but it didn’t actually change anything.</p>
<p><em>But</em> now that I had a an application that was actually easy to extend and a pleasant templating engine I could finally <em>add</em> stuff.</p>
<p>So I wrote some code to get my most listened artists of the past week from the <a href="https://listenbrainz.readthedocs.io/en/latest/users/api/index.html">ListenBrainz API</a>, extended the template for my home page, spent way too long writing the CSS that made the background gradient of said artist move more quickly the more I had listened to them, and I was done!</p>
<p>The resulting website is completely static and without any JavaScript or backend logic for fetching the stats.
I simply set up a trigger in CI to rebuild it once a day so the statistics are always up to date.</p>
<p>It shows even more than just music stats already and I have some ideas for more stuff I could add, but I think here is a good place to stop for now.</p>
<p>I had some fun writing yet another static site generator for a very specific use case <del>after days of figuring out what template engine to use</del> and my website feels a bit nicer in return.</p>
<p>Feel free to hit me up on any of the socials if you have questions and I hope you have a good day &lt;3</p>
<section class="footnotes" data-footnotes>
<ol>
<li id="fn-analytics">
<p>Except a tiny snippet to allow minimal tracking using <a href="https://github.com/HermanMartinus/bearlytics">Bearlytics</a>.
I like that it doesn’t do much more than send a request saying “hey someone visited this page” so I can smile a bit when I see that people actually check out my website. <a href="#fnref-analytics" class="footnote-backref" data-footnote-backref data-footnote-backref-idx="1" aria-label="Back to reference 1">↩</a></p>
</li>
<li id="fn-mersy-name">
<p>A combination of “me”, “rs” for “Rust” and “sy” for <a href="https://github.com/sycamore-rs/sycamore">Sycamore</a>, which was one of the first templating engines I tried out but didn’t end up using. <a href="#fnref-mersy-name" class="footnote-backref" data-footnote-backref data-footnote-backref-idx="2" aria-label="Back to reference 2">↩</a></p>
</li>
<li id="fn-comrak">
<p>Okay, not “nothing”.
Because I decided on <a href="https://comrak.ee/">Comrak</a> for my Markdown to HTML converter I got much better code syntax highlighting than what Pandoc had offered. <br />
<br />
While we’re in the footnotes and no one’s listening: <br />
Doing all of this also allowed me to automatically generate the posts overview page.
No more doing anything manual when I have to publish a new post like this one. <br />
It’s pretty much just:
Put the post in the posts directory.
Commit it.
Push it.
Spin it.
Bop it.
The build pipeline runs and the site should be live shortly afterwards. <a href="#fnref-comrak" class="footnote-backref" data-footnote-backref data-footnote-backref-idx="3" aria-label="Back to reference 3">↩</a></p>
</li>
</ol>
</section>
]]></description><guid>https://qtea.me/posts/adding-cool-stuff-to-my-website/</guid><pubDate>Fri, 9 Jan 2026 00:00:00 +0000</pubDate></item><item><title>Feeling sad about Pokémon games (and thoughts on Legends: Z-A)</title><link>https://qtea.me/posts/my-issues-with-pokemon-za/</link><description><![CDATA[<p>I’ve played Pokémon for as long as I’ve been playing video games.</p>
<p>When I first got a GameBoy Advance I played <em>Emerald</em> and <em>LeafGreen</em>.
I played a copy of <em>Yellow</em> I borrowed from a friend in primary school.
I played <em>Crystal</em> on an emulator on my cellphone in middle school (and refused to evolve Cyndaquil because it was so cute).
I played every single mainline Pokémon game since and always had fun.
I played a lot of the spin-offs (<em>Mystery Dungeon</em> and <em>Ranger</em>) and always had fun (alright I didn’t play <em>Gates to Infinity</em>, and while <em>Super Mystery Dungeon</em> was alright it didn’t manage to live up to what <em>Mystery Dungeon</em> used to be on the DS).</p>
<p>I had a phase where I wanted to own every Pokémon game from the GBA onwards and even imported the Japanese soundtracks after finding out they were not that expensive and readily available.
So I own all editions of every mainline game from <em>Ruby &amp; Sapphire</em> until <em>Sun &amp; Moon</em>, full in box, and the physical soundtrack.</p>
<p>I had fun playing through <em>Shield</em> – and while it did have issues I still enjoyed going through the world and interacting with the characters (I may also be a bit biased, since I have a lot of merch depicting Leon in my room).
The DLCs didn’t grab me that much, but I still played through and got a fair share of enjoyment out of them.
It was still Pokémon.
Surely the next game would be great, now that they managed the jump from a 240p handheld to a full HD home console.</p>
<p>I got <em>Scarlet</em> – and I think this was the first time I didn’t enjoy Pokémon.
The world, the characters, the new Pokémon are all pretty interesting.
But overall the game is just too much.
The open world gives you too much to do
It doesn’t stop you from accidentally walking into an area that requires a way higher level
It makes the task of “gotta catch ’em all” (focusing only on the regional dex) more daunting than ever before.</p>
<p>Maybe the issue was with how I learned to play Pokémon:
Get to a new area, explore all of it, try to catch every new Pokémon you encounter along the way.</p>
<p>And <em>Scarlet</em> makes it possible to spend hours exploring an area while getting lost in parts of the map that aren’t even relevant to the story.
You constantly see sparkles for random item pickups that draw your attention away from where you actually wanted to go.</p>
<p>I did most of the Gyms, Starfall Street and the Titan Pokémon, and then stopped playing somewhere in the northern part of the map because I got burned out.
Which is a bit sad since I heard that Area Zero (where you get to after beating the Elite Four?) is pretty cool.
I’ve also started watching the current anime this year and I’m really enjoying seeing more of the world and the characters and the different Pokémon – just without any of the issues the game has.</p>
<p>So afterwards I thought:
“Maybe that’s it for me and Pokémon games.
I’ll just focus on playing other games and get my share of Pokémon from watching the anime.”
(I’ve watched every episode of the anime since the <em>Sun &amp; Moon</em> series and am genuinely surprised how good the quality and story telling for a “kids’ show” is.
With that said: Do give <em>Pokémon Horizons</em> a try if you enjoy anything Pokémon.
I’ve been tearing up on multiple episodes and the characters are all so good and it’s just a really comfy watch.)</p>
<h2 id="deciding-to-give-pokémon-another-try">Deciding to give Pokémon another try<a href="#deciding-to-give-pokémon-another-try" aria-label="Link to heading 'Deciding to give Pokémon another try'" data-heading-content="Deciding to give Pokémon another try" class="anchor"></a></h2>
<blockquote>
<p><img src="/its-been-3000-years.jpg" alt="Screenshot of AZ from Pokémon X &amp; Y who’s holding his hands out in front of him. A subtitle reads “It’s been 3,000 years…”." /></p>
</blockquote>
<p class="quote-aside">(actually it's only been like 2.5 years)</p>
<p>So 2025 comes along and I watch the reveal trailer for <em>Pokémon Legends: Z-A</em>.
I wasn’t sure if I wanted to give Pokémon another try, but I had good memories of playing <em>X &amp; Y</em> on my 3DS, the customization options (which were very lacking in <em>Scarlet &amp; Violet</em>) and the story conclusion regarding AZ and his Floette.
Even if it wasn’t amazing, the setting at least drew me in more than other things like <em>Legends: Arceus</em>.</p>
<p>I hadn’t played the previous <em>Legends</em> game.
I don’t remember the exact reason but it was probably a mix of not being that excited about Pokémon anymore after <em>Sword &amp; Shield</em>, it only being a spin-off, and <em>Final Fantasy XIV</em> taking up most of my free time around that time.
But I had heard pretty good things about it from friends who played it, and on social media in general.
The new regional forms in <em>Legends: Arceus</em> seemed fun, I liked the character designs and all the fanart I’d seen.</p>
<p>So if the mainline games couldn’t give me what I wanted out of Pokémon anymore, the spin-offs might be able to instead?
With them not being tied to a strict schedule that had to align with the anime and the merch and the card game and whatnot there might be a chance to make something smaller, more polished?</p>
<p>When the game released I followed what other people were posting and the general consensus seemed to be that it was pretty good?
Sure there were performance issues and complaints about the graphics and the lack of voice acting and whatnot.
But I cared more about the story and the gameplay, and seeing everyone post cute screenshots of their characters sitting in a café together with their Pokémon made me think “maybe I should give it a try as well.”
I had just finished playing <em>Trails in the Sky</em> (<strong>good</strong> game, everyone who was always really “annoying” about how good the <em>Trails</em> series is was absolutely right, but back to <em>Z-A</em>), so this was the perfect time to give something shorter a try before sinking back into my backlog that I’ll definitely work through next year.
For sure.
Yes.</p>
<p>During Black Friday I got the chance to buy it for only 45 €.
I remember being able to get Pokémon games at release for 35 € back in the day, to be fair that was on the 3DS where games weren’t that expensive in the first place and I got lucky that stores had discounts or “3 for 2” offers.
So getting a new Switch game shortly after release for 25% off seemed like a no-brainer, even if it ends up being another <em>Scarlet</em> situation where I may not finish but at least get some enjoyment out of it.</p>
<h2 id="starting-into-z-a">Starting into Z-A<a href="#starting-into-z-a" aria-label="Link to heading 'Starting into Z-A'" data-heading-content="Starting into Z-A" class="anchor"></a></h2>
<h3 id="day-13">Day 1–3<a href="#day-13" aria-label="Link to heading 'Day 1–3'" data-heading-content="Day 1–3" class="anchor"></a></h3>
<p>It’s November 23, about 1.5 months after the game came out, and my copy of <em>Pokémon Legends: Z-A</em> arrives at my door.</p>
<p>It’s pretty late so I decide to only play until I get my starter so I’ll be ready to get right into the game next time.</p>
<p>I put the game into my Switch and turn it on.
I select what my character should look like from one of the given presets.
I’m greeted by the intro sequence with no voice acting.
It does feel super weird to not have any voice acting here, but this won’t be a deal breaker for me (<a href="https://www.youtube.com/watch?v=8fGSmhWg-EA">this</a> review does a good job of showing how much of an issue this actually is).
My character arrives in <em>Lumiose City</em> and I step out of the train station.
I’m full of anticipation for what’s going to happen next.</p>
<p>And unfortunately this is where the game very quickly starts to fall apart for me.</p>
<p>You’re greeted by <em>Urbain</em> (if you decided to play as the girl protagonist) who wants to rope you into a photoshoot – which ends up in you getting your starter Pokémon a little while later.
There’s some dialogue about you being a tourist and since he works for a local hotel he offers you a place to stay.
Afterwards you learn more about catching Pokémon and all the usual stuff before he asks you to join his group for Pokémon battling.</p>
<p>And I just keep wondering why all of this is happening.
What is the agency of the player character to agree to all of this?
If you’re a tourist that means that either it’s a short term stay that wouldn’t leave time to engage in all of this over multiple weeks, or you did plan a longer stay – but wouldn’t that mean that you already have the place to stay at sorted out?
You learn absolutely nothing about the player character.
Why did they come to Lumiose City?
Don’t they have to get back to school or their family eventually?</p>
<p>In regular Pokémon games it’s always clear that you’re some kid who sets out on an adventure together with their partner Pokémon because that’s just what kids do at that age.
Everything else makes sense based on that simple premise.
Things slowly unfold while you’re on that adventure, there’s time to introduce new characters bit by bit and build up a story that goes beyond just beating all the Gyms.
While the player character is mostly a blank slate, their interactions with other characters like their mom and rival who already know them still make you feel like they’re a part of this world.</p>
<p>“Tourist that nobody knows and doesn’t have any plans” is a very weird premise and the game doesn’t try to flesh it at all.
(At least it didn’t in ~15 hours I played.
Maybe there is some huge plot twist about your character’s origin later, but I doubt it.)</p>
<p>Why not have the player character go to the hotel they had already booked?
Make them explore the city by themself for a bit?
Go to some cafés?
Let us choose the starter in advance (“Oh hey what’s that Pokémon you have with you?” <em>choose your start dialogue pops up</em>), so that there is a trusted companion that connects them to the game world.</p>
<p>Then a bit later you can have them run into Urbain who is motivated to teach you all about how battling works.
Let him slowly rope you into whatever is going on while staying at your own hotel.
And after 7 days or so have a short sequence that your planned stay is getting to a close.
Luckily Urbain offers to let you stay at his hotel for free if you keep helping him.
By now there’s some trust built up so it doesn’t feel as weird to have a stranger pretty much “kidnap” you off the street.
Show a scene of the player calling their mom to make sure they’re allowed to stay in Lumiose for a bit longer (giving the opportunity to establish a bit more backstory).</p>
<p>But it’s not like that.</p>
<p>There’s no immersion at all.</p>
<p>I try not to think about it too much and instead focus on the gameplay which still feels interesting and new.</p>
<p>The “real time” fights are a nice twist and having moves with different recharge times (<del>kinda like your actions in FFXIV</del>) makes you think more about when to use them and how you interact with battles in general.</p>
<p>The <em>Wild Zones</em> seem inviting with only having around 8 unique Pokémon per zone that you’re able to catch.
More manageable than the giant open world areas in <em>Scarlet</em>.
I like this.
I try to catch every Pokémon in the first few zones before realizing some are probably locked behind certain conditions like the weather and move on to other things.</p>
<p>The <em>Battle Zones</em> seem engaging at first.
Your current objective is to grind points in the Battle Zones every night in order to get enough points to challenge someone for a “promotion match.”
You start at rank <em>Z</em> and are supposed to work yourself all the way up to rank <em>A</em> (for profit™, and because it will help with whatever <del>Urbain’s</del> your group is doing).
There’s some fun mechanics where you can sneak up on opponents and try to knock them out with specific types of attacks to earn extra points.
Your opponent for the promotion match has a silly name that starts with the same letter as your current rank.</p>
<p>So far so good.</p>
<h3 id="day-5">Day 5<a href="#day-5" aria-label="Link to heading 'Day 5'" data-heading-content="Day 5" class="anchor"></a></h3>
<p>I kinda hope the gameplay loop isn’t actually “spend 25 nights battling and doing promotion matches” because that sounds very boring and repetitive.</p>
<p>They always feel like a chore that takes away from the actual story.</p>
<p>“Here you’re done talking to the NPCs with unique character designs about story related stuff for the day.
Now go grind battles against copypasted NPCs for the night (or multiple nights if you didn’t manage to get enough points) so we’ll allow you to do more story.”</p>
<p>The promotion matches do get some connection to the story after a while, but the battling itself still feels like a chore and you oneshot most of your opponent’s Pokémon anyway.</p>
<p>But so far the game has been fun enough and hopefully it’ll get better as the story develops further.
(Except for it being impossible to find a plain skirt?? There’s so many different clothes you can buy and a lot of the NPCs actually wear really cool skirts – that are not available in shops.
I ended up buying a skort but the geometry of the model looks pretty bad when your character is in motion.)</p>
<h3 id="day-7">Day 7<a href="#day-7" aria-label="Link to heading 'Day 7'" data-heading-content="Day 7" class="anchor"></a></h3>
<blockquote>
<p>“Quick, you have to chase someone!”</p>
</blockquote>
<p class="quote-author">some character during the main story</p>
<p>Naturally, the game disables the run button during the chase sequence.
This is fine.</p>
<h3 id="after-2-weeks">After 2+ Weeks<a href="#after-2-weeks" aria-label="Link to heading 'After 2+ Weeks'" data-heading-content="After 2+ Weeks" class="anchor"></a></h3>
<p>Maybe I should just ignore the sidequests since almost all of them are completely pointless …but the completionist in me wants to do them.
At least they give me something to do until next nighttime where I can continue grinding points to see 5 more minutes of the story.
(I know I can skip to nighttime at benches, but I still want to do the sidequests.)</p>
<p>Some of the sidequests are not that bad.
There was one where you had to find 12 <em>Spewpa</em> hidden in a museum which felt very silly.</p>
<p>But most of them feel “wrong.”
Especially the ones that end up giving you a Pokémon.
NPC: “Hey thanks for helping! Oh? It looks like the Pokémon you just met wants to go along with you. How nice.”
Player character: “:)”</p>
<p>IT’S ALWAYS “:)”</p>
<p>My issue isn’t that you’re gifted a Pokémon.
That’s a normal part of any Pokémon game (although the mainline games didn’t have that many sidequests).
It’s that your character is always happy.
They never question anything.
Maybe the issue is that your character is no longer a blob of pixels and now constantly in view due to all the dialogue with fixed camera angles.
I just wish they’d question anything at all instead of simply going along with whatever happens.
Always smiling.</p>
<p>:)</p>
<h3 id="rogue-mega-evolution-and-the-battle-system">Rogue Mega Evolution (and the battle system)<a href="#rogue-mega-evolution-and-the-battle-system" aria-label="Link to heading 'Rogue Mega Evolution (and the battle system)'" data-heading-content="Rogue Mega Evolution (and the battle system)" class="anchor"></a></h3>
<p>We’re still two weeks in, but I realize I haven’t mentioned <em>Mega Evolution</em> at all.</p>
<p>Probably because it’s just not that interesting?</p>
<p>It wasn’t even that interesting back in <em>X &amp; Y</em>, but it <em>felt</em> more interesting.
Your special trump card that you could use only once per battle.</p>
<p>Now it’s on a timer, you have to charge it up first, and you might even be able to use it multiple times per battle.
During trainer battles there’s a long cutscene whenever Mega Evolution gets activated.
Every. Single. Time.
The cool thing is definitely that they added a lot of new Mega Evolutions with (in my opinion) pretty creative designs.
I enjoyed seeing these in the anime.</p>
<p>What the game also added is “boss fights” in the form of <em>Rogue</em> Mega Evolved Pokémon.
The name is pretty self-explanatory and they remind me a bit of the <em>Max Raid Battles</em> from <em>Sword &amp; Shield</em>:
One giant Pokémon with a massive HP bar that you have to take down.</p>
<p>Except this time the game gives you an obstacle that’s even more massive than your opponent’s HP bar:
The new battle system.</p>
<p>I didn’t have that many issues with the battle system up until now.
Everything happening in real time naturally makes it more involved.
No longer can you take your time to think about strategy, look up what moves are effective against your opponent.
You pick your move whenever it is ready while trying to dodge stage hazards and attacks (which can affect both your Pokémon and <em>you</em>).
Wild Pokémon can attack the player character now and if you get hit too many times you black out.
So now you not only have to pay attention to the Pokémon but also where your character is positioned.
I definitely enjoy the turn based gameplay more, but the real time battles are fine and didn’t bother me as much as everything else I’ve mentioned so far (they’re actually pretty fun when it comes to wild Pokémon).</p>
<p>They didn’t bother me – until I got to the rogue <em>Mega Barbaracle</em> fight.</p>
<p>This was the 9. Rogue Mega I fought.
Generally the fights drag on a bit since you have to collect some energy in order to have your own Pokémon mega evolve or use some special moves that deal more damage to the Rogue Mega.
The previous ones gave me some slight issues, mostly because my own Pokémon got KO’d.
But that’s okay.
Time to level up a bit or find a Pokémon that’s more effective (or just try again and hope for a better outcome).</p>
<p>Rogue Mega Barbaracle added a completely new problem:
A bit into the fight it does a thing where it suddenly teleports to the player character, does a thousand punches, and then you inevitably black out because you took too much damage.
Time to restart the fight.
Time to rewatch the 20 seconds unskippable cutscene where it mega evolves.
Every single time.
At least your own Pokémon don’t have a cutscene when they mega evolve during rogue battles.
I tried dodging, I tried running away, I tried simply having my Pokémon attack more while it happened.
But nothing helped.</p>
<p>If you get far enough into the fight the games offers you to retry the fight from the midway point.
Since the game is clearly aware that these fights can be difficult enough that you need a checkpoint, how did nobody notice how annoying it is to rewatch the cutscenes every single time?
But even the checkpoint doesn’t help much since it drops you right into the part of the fight where you’re only a couple of seconds away from getting punched out again.</p>
<p>(Side note:
There was one promotion match that I had to retry a couple times and there was so much unskippable talking beforehand.
Why do rogue battles give you the option to restart the fight (almost) immediately, but regular battles don’t?)</p>
<p>This is the moment when I first felt like dropping the game.
This wasn’t fun.
This felt unfair.</p>
<p>But I kept trying again the next day.
Surely I’ll figure out something or get better at dodging the attacks.</p>
<p>But I didn’t.</p>
<p>Call it “skill issue” if you want.</p>
<p>And since I already had issues with the overall presentation of the game and didn’t see myself giving it another try again (unlike <em>Scarlet</em> which I might still finish one day despite not having touched it for 2.5 years) I ended up making a decision.</p>
<h2 id="im-sad">I’m sad<a href="#im-sad" aria-label="Link to heading 'I’m sad'" data-heading-content="I’m sad" class="anchor"></a></h2>
<p>I put the game up for sale on December 17, 24 days after I started playing, and brought it to the post office the very next day.</p>
<p>This is the first time in ages that I actually sold a game.
I don’t even remember if I ever did.
At least not in the past 10 years.</p>
<p>And this makes me kind of sad?</p>
<p>Pokémon is a series that I’ve always loved.
Where I’ve eagerly awaited the next entry for years.
It always had its up and downs, but I still managed to have fun.</p>
<p>All of this makes me feel like I’m done with the video games.
There’s no reason to try again.
Unless they go back to a more streamlined, expressive and story focused experience.</p>
<p>At least I still have the anime.
And I hope whatever lies beyond the <em>Horizon</em> is just as good.</p>
]]></description><guid>https://qtea.me/posts/my-issues-with-pokemon-za/</guid><pubDate>Thu, 26 Feb 2026 00:00:00 +0000</pubDate></item><item><title>How do you compare something when your point of comparison is based on nostalgia?</title><link>https://qtea.me/posts/comparison-with-nostalgia/</link><description><![CDATA[<p>I “finished” <em>Kirby and the Forgotten Land</em> in July, having started it shortly after it released back in 2022.</p>
<p>I remember looking forward to it back then.</p>
<p>The last <em>Kirby</em> game I had played before this was <em>Kirby: Planet Robobot</em> (also around the time it released, in 2016), which most people would agree was a pretty good game.
I wouldn’t call myself a massive <em>Kirby</em> fan, despite owning a bunch of plushies and other merch, playing all the games during the DS and 3DS era, preferring to play as Kirby in <em>Super Smash Bros</em>, and my email address I created in primary school being inspired by Kirby because I used to pretend I was Kirby when playing with a kindergarten friend (the weird part about this is that I’m pretty sure I’ve never actually played a <em>Kirby</em> game back then, so no idea how this happened).</p>
<p>Asides aside: I do like Kirby and in a similar vein to my <a href="../my-issues-with-pokemon-za/">previous blog post</a> I’m not quite sure how I feel about where the series is headed.
With <em>Pokémon</em> I at least had experience with more recent games and was following other things like the anime.</p>
<p>I hadn’t played the previous game, <em>Kirby Star Allies</em>, because I had already heard that it wasn’t that good.</p>
<p>I don’t have fresh memories of how good the other games were when I played them 10 to 20 years ago.
I only <em>feel</em> that it was fun.
Being on vacation, spending way too much time in <em>Kirby: Mouse Attack</em> and <em>Kirby Super Star Ultra</em>.
I remember struggling with the last boss in <em>Kirby: Triple Deluxe</em> but eventually getting it and then spending some time to replay levels to work on my in-game keychain collection.
It definitely helped that this was during the height of the 3DS and the Streetpass integration motivated me to turn the game on every now and then.</p>
<p>But were those games better?
Do I just enjoy 2D games more?</p>
<p>The whole combat in <em>Forgotten Land</em> just feels worse to me.
The 3D environments make it harder to aim and avoid things.
The gameplay feels slow because there needs to be more space between everything.
This is very much still a mostly linear Kirby game, with the same kinds of alternate routes and hidden secrets.
But it makes me feel like I could miss something at every single corner.</p>
<p>There’s even a collecting aspect in the form of gashapon machines, but spending hours hoping to randomly get the collectible you were still missing doesn’t feel that fun anymore.
And I can’t work on it through Streetpass.</p>
<p>The visuals are really good, but I don’t think it gained anything from transitioning to a 3D environment.
Much like how Pokémon didn’t gain anything from going from 240p to 1080p.</p>
<hr />
<p>I could just blame this on me getting old, not wanting to get used to new things, being too tired from work to properly enjoy video games.
But I have enough recent examples of me really enjoying video games, even if they frustrate me at times.</p>
<p>Over the last year I played the first two <em>Trails in the Sky</em> games.
These are the kind of games where you know enough people that keep telling you “omg this series is so good you should just play it” that it makes you less interested in actually playing them.
Surely they can’t be that good.
Well, turns out those games really <em>are</em> that good.
Because of the world.
And the characters.
The decently good battle system (even if the game could do a better job of explaining it to you).</p>
<p>One thought I had was that this is where visuals peaked.
Early 2000’s low-poly 3D environments paired with expressive sprites and character portraits.
This might not be the best point to bring up in a post that’s supposed to be about Kirby, who is in my opinion one of the most expressive Nintendo characters.
Seeing Kirby in the cutscenes in <em>Forgotten Land</em> did bring me a bunch of joy.</p>
<hr />
<p>Maybe what I want from games these days is story.</p>
<p>Kirby never really had much “story”.
But the story is one of the parts that I kinda enjoyed about <em>Forgotten Land</em>.
When I got to the final stage and found out how the pieces fit together.
When there was a climactic chase sequence leading up the final fight.
These things were good.
Seeing Kirby interact with those around him was good.</p>
<p>But what about the regular gameplay in all the levels leading up to this?
It’s been too long since I last played a Kirby game.
Maybe the gameplay was always like this, despite my feelings telling me it was better in the 2D games.</p>
<p>A lot of the video essayists I watch would say something like “I replayed the entire series for this video”, but that’s just not me.
I prefer to experience new things.
I don’t want to spend days, weeks, replaying something when I already find it hard to find any motivation to play video games these days.</p>
<p>But how can I say that this game is worse, when all I have is my nostalgia to lean on?</p>
<hr />
<p>At this moment I have around 10 games “ready to play” which I mean to finish some time in the near future.
And a lot more that once were in this state, but then too much time passed and I never ended up playing them.
But despite wanting to experience new things it is difficult to open up to something new.
After finishing the first <em>Trails in the Sky</em> I wanted to take a break before playing the second game, to take some time to play something smaller.
But that left me with a list of installed games, games I was interested in or had been recommended, unsure where to start, unsure if something was the right choice.</p>
<p>There’s been a couple of cases recently where I tried to play a game I that I had heard good things about, but then when I actually got around to playing it it wasn’t my cup of tea.
And then I need to decide:
Do I want to keep playing despite of it?
Will it get better?</p>
<p>I played <em>Owlboy</em> and stopped halfway through because the gameplay just wasn’t fun and encounters started to feel unfair.
Despite how good the visuals and soundtrack were.</p>
<p>I tried playing <em>Tunic</em> because I thought I’d be up for a Zelda-like game, but it felt too much like a mobile game, as well as having elements that made me immediately go “nope” when I encountered them.
This was very early into the game even, so I got a refund on Steam.</p>
<p>Lastly, I played <em>Silksong</em>.
And while I enjoyed the exploration and gameplay in general, death felt too punishing to make me want to backtrack over and over again.</p>
<hr />
<p>Coming back to story, I think <em>Pokémon</em> has the issue that the gameplay itself hasn’t changed that much, but the game itself has in a way that makes it difficult to enjoy the story.
<em>Scarlet &amp; Violet</em> puts too much padding in the form of a big empty open world between me and the story moments.
Going through the world felt like a chore.
<em>Legends: Z-A</em> improves one the size of the world, but in turn fills it with lifeless NPCs.
It makes me wonder what’s the point of trying to get to the “good” parts when most of the things surrounding them just aren’t on the same level.</p>
<p>Early 2025 I played through <em>Final Fantasy XVI</em> – which you could say also has big open world with not much in it.
But the game didn’t make me feel like I was missing out on anything by not exploring every single inch of it.
There weren’t shiny spots on the ground to constantly catch my attention.
Traversal was quick.
And most of all:
The world itself felt good.
The side characters felt alive and kept coming up throughout the story.</p>
<p>This is one of the things I enjoyed about <em>Trails in the Sky</em> so much.
You run into some random character early on, thinking they’re just an NPC for a sidequest, but then they come up again and again and keep growing on you.
Yes, there was the occasional fight that gave me a bunch of frustration, but I knew that once I got past this I get to experience more of this world.</p>
<hr />
<p>I don’t think <em>Kirby</em> needs a stronger story focus.</p>
<p>But recent experiences make me wonder where to go with Nintendo games from now on.
They’ve been a big part of my childhood ever since I played on my parents’ NES, my friend’s N64, and on my own GBA.</p>
<p>I don’t see much of a reason to get a Switch 2 at this point, when there’s only a couple franchises I’m interested in, and a with bunch of them having left me unfulfilled with their most recent games.
I don’t need the portability anymore and am much more comfortable playing on my PC these days.</p>
<p>Maybe the next Zelda game will fix me. <br />
Maybe Nintendo should start making games for the 3DS again.</p>
]]></description><guid>https://qtea.me/posts/comparison-with-nostalgia/</guid><pubDate>Fri, 14 Aug 2026 00:00:00 +0000</pubDate></item><item><title>Souping up my blog</title><link>https://qtea.me/posts/souping-up-my-blog/</link><description><![CDATA[<p>For a long time I thought it’d be nice if there was a simple way for people to interact with my posts.
When you write something it’s nice to know that someone took the time to read what you wrote and maybe even got some enjoyment out of it.
I’m glad for those who let me know on Bluesky or Fedi &lt;3</p>
<p><a href="https://bearblog.dev/">Bear Blog</a> has an unintrusive upvote button at the end of each post.
But I’m not using Bear Blog – my blog is statically generated and I’d like to keep it that way.</p>
<p>So last weekend I got the idea of writing a simple web service that you can give the URL for a post, and it’ll either return the number of upvotes or let you add an additional one.
To get started I looked at the source code for Bear Blog to figure out how to prevent repeated upvotes and protect against potential abuse.
In the end the only thing I adapted was storing an upvote as the hash of a visitor’s IP address together with the current year, which has one minor issue (if you post something at the end of a year it can be upvoted again within a short time), but overall works well enough.</p>
<p>I added an allow list so only upvotes for certain sites are accepted and then did a quick check whether the upvoted post actually exists.</p>
<p>Since the web service is completely separate from my blog I just had to write a little bit of JavaScript to fetch the upvotes when a post is loaded, and then add a button to allow people to add an upvote.</p>
<p>When I initially started the project I decided to name it “upvaas” (upvotes as a service), because that’s what it is.
But turns out “upvaas” is a <a href="https://en.wiktionary.org/wiki/%E0%A4%89%E0%A4%AA%E0%A4%B5%E0%A4%BE%E0%A4%B8">Hindi word</a> (meaning “fasting”), which by itself wouldn’t be enough of a reason to change the name (it’s not a bad word, and in a way upvoting is kinda the opposite of fasting?), but it did make me wonder if I could come up with something more unique and less big tech sounding.</p>
<p>Supvaas? (silly upvotes as as service)</p>
<p>Soup?? (silly/service of upvotes)</p>
<p>You’re telling me a soup upvoted this post???</p>
<p>The silliness of “soup” stuck with me, so I promptly renamed the project to “<a href="https://codeberg.org/qtea/soupvotes">soupvotes</a>” (I want to avoid being confused in the future when I stumble upon a folder that’s just named “soup”) and here we are.</p>
<p>I think “soup” is also fitting because I wanted to use a steaming tea cup as an indicator for upvoted posts – and soup is also pretty steamy.</p>
<p>So from now on you can stir (upvote) my writing by clicking the tea cup under each post.
Tea you around!</p>
<hr />
<p><em>Update 2026-09-12:</em>
I’ve changed the logic to allow a new upvote every three months (counting from the last upvote, instead of for example the current quarter).
This feels a bit fairer to those with a static IP, and especially those who might get an IP assigned that has already upvoted (although in that case they might still need to wait up to 3 months, by which point they probably won’t be reading the post anymore).
I assume most visitors will be able to upvote more often (my own IPv6 seems to rotate every day (or so)), but this feels like the best compromise without adding an account system or storing data on the client’s side.</p>
]]></description><guid>https://qtea.me/posts/souping-up-my-blog/</guid><pubDate>Sat, 22 Aug 2026 00:00:00 +0000</pubDate></item><item><title>Switching from Neovim to Vim</title><link>https://qtea.me/posts/switching-from-neovim-to-vim/</link><description><![CDATA[<p>Wait, shouldn’t this be the other way around?</p>
<div class="markdown-alert markdown-alert-note">
<p class="markdown-alert-title">Note</p>
<p>Because it confused me a bit while writing I’ll be using “vim” to refer to the general concept which includes both Vim and Neovim (and a lot of the time also regular <code>vi</code>) and “Vim” to refer to the specific program.</p>
</div>
<p>I first started using Vim some time in 2014 when a coworker taught me how to deploy new versions of our application onto our servers.
Just the basics to get me started, and I left it at that for a couple years.
I was comfortable enough to use it for editing config files, but never looked into more than the basic motions.</p>
<p>In 2019 I started customizing Vim by adding the <code>gruvbox</code> colorscheme and <code>vim-airline</code> to have the cool™ statusline with the chevrons as separators that I saw everyone use online.
I don’t remember where I first saw gruvbox but the colors are just really pleasant to me and I still use it as the color scheme for my terminal and code editors to this day.</p>
<p>In mid 2023 I switched to Neovim.
I think one of my coworkers who was more up to date with Linux stuff (and using Arch<sup class="footnote-ref"><a href="#fn-arch" id="fnref-arch" data-footnote-ref>1</a></sup>) was talking about it.
At that time I pretty much only used it as a drop-in replacement for my existing <code>.vimrc</code> that had been mostly unchanged since 2019.
I was definitely using vim a lot more by this point, from doing small source code edits (because it took too long for IntelliJ to open a project) to even writing the occasional macro.</p>
<p>Then in late 2023 I saw a video that showcased code completion using LSP in Neovim and pointed to <a href="https://github.com/nvim-lua/kickstart.nvim"><code>kickstart.nvim</code></a> as a good way to get started with it.
So that’s exactly what I did.
I started off with <code>kickstart.nvim</code> as a base, got a feel for how to navigate around projects, and slowly made it my own.</p>
<p>Up to this I had primarily used VSCode to edit code (outside of work, where I was still primarily using IntelliJ), but I wouldn’t say I ever <em>enjoyed</em> using it.
<del>Insert VSCode rant here.</del></p>
<p>Since I was fresh into my Elixir phase I decided to work on all my projects exclusively in Neovim, which included my attempt at that year’s <em>Advent of Code</em> and the <a href="https://codeberg.org/qtea/ocarrd">static site generator</a> that I <a href="../deciding-to-write-a-static-sitegen/">blogged about</a> <a href="../i-thought-you-wanted-to-write-a-sitegen/">in the past</a>.
I enjoyed working with Neovim.
It was fun.
Navigating between code felt quick.
It was just a single editor window without any tool- or sidebars.
(Okay really, why does VSCode and all the new versions of Microsoft Office have this giant sidebar on the left side with only three buttons? Yes, of course I need a dedicated sidebar button in Outlook that opens OneDrive.)</p>
<p>I tried using “vim motions” in other editors before making Neovim my main editor, but it always felt incomplete.
Sure, you can quickly navigate within the same file, but if you want to do more than that you always need to reach for your editor’s shortcuts (which likely even conflict with some of the vim ones).
You can’t control everything while being in vim mode.</p>
<p>Even at work I started to use Neovim for more and more things, only reaching for IntelliJ when I had to do some deep debugging.</p>
<hr />
<p>Okay enough being sentimental, I can start to get to my point now.</p>
<p>I generally think it’s a good idea to learn how to use something <code>vi</code> shaped.
It’s on every single system, it’s easy to use (once you get past the “can’t quit” jokes) and every additional bit that you learn can be really helpful.
And somehow Neovim prevented me from learning more of those additional bits.</p>
<p>Last week there was some drama on Neovim’s issue tracker (which I’m not gonna go into), but <a href="https://michci.ooo/">Michcia</a> mentioned switching from Neovim back to Vim – which I initially reacted to with something along the lines of “that would be too much work for me since it is my primary editor and I’m used to all these plugins”.
Well, despite that I kept thinking about what it would take to switch to Vim and made my first attempts that very same day.</p>
<p>Then last weekend I spent way too much time configuring Vim while trying out different plugins while trying to pinpoint what I like about my Neovim setup and how I could replicate it with Vim.
Since then (and while having the opportunity to try it out at work) I came up with the following list of things that I would like to have in Vim, roughly ordered by priority:</p>
<ol>
<li>LSP and code navigation</li>
<li>Java debugging</li>
<li>Diff editing</li>
<li>Syntax highlighting</li>
</ol>
<h2 id="lsp-and-code-navigation">LSP and code navigation<a href="#lsp-and-code-navigation" aria-label="Link to heading 'LSP and code navigation'" data-heading-content="LSP and code navigation" class="anchor"></a></h2>
<p>In Neovim I was using the builtin LSP together with <a href="https://github.com/nvim-telescope/telescope.nvim">telescope.nvim</a> to quickly navigate between files in a project.
I heavily use shortcuts like <code>gd</code> (go to definition of a variable), <code>gr</code> (got to references of a variable), <code>&lt;leader&gt;sf</code> (search files by name), <code>&lt;leader&gt;sg</code> (grep in files) and <code>&lt;leader&gt;sw</code> (search for the current word in all files).</p>
<p>After searching for LSP support in Vim I found out that there’s 5-ish plugins that are commonly used, of which I tried out the following ones:</p>
<ol>
<li><a href="https://github.com/yegappan/lsp"><code>yegappan/lsp</code></a> (“Vim9 LSP”) – A newer plugin written in Vim9 script (which should make it faster than alternatives written in vanilla Vim script that I did not consider).</li>
<li><a href="https://ycm-core.github.io/YouCompleteMe/"><code>YouCompleteMe</code></a> – A plugin written in Python that comes out of the box with support for a couple languages.</li>
<li><a href="https://cocnvim.com/"><code>coc.nvim</code></a> – A plugin written in TypeScript that tries to be easy to use by offering extensions for most languages instead of making you configure the LSP directly.</li>
</ol>
<p>I started with the Vim9 LSP plugin and didn’t have that many issues.
It felt similar to how I was used to configuring LSP in Neovim.
But what annoyed me was that for some reason initializing <code>rust-analyzer</code> blocks the editor, meaning I have to wait a couple seconds before I can do anything.<sup class="footnote-ref"><a href="#fn-vim9-lsp-block" id="fnref-vim9-lsp-block" data-footnote-ref>2</a></sup></p>
<p>So that’s when I tried out <code>YouCompleteMe</code>, mostly because it has “easy” integration with a debugger (more on that in the next section).
But idk, the configuration felt bad, it wasn’t super clear what to do.
On top of that some advanced configuration could only be done in Python.
And <em>sure</em> the whole thing is written in Python, but when you’re a Vim plugin please let me do all the configuration in Vim script (or some JSON file if you really have to).
There was definitely more that annoyed me about it which made me try the next option.</p>
<p>I knew about <code>coc.nvim</code> because it came up a lot when I set up LSP for Neovim.
But I never paid it much attention since Neovim had its own builtin LSP at that point and using a separate TypeScript thing that talked with lots of additional extensions seemed a bit unnecessary.
Well, I was pleasantly surprised when I tried it out in Vim.
Extensions are easy to install, you barely have to configure anything, and if you do there’s really good auto completion for the config file that feels a lot like editing <code>settings.json</code> in VSCode.</p>
<p>In the end I switched back to the Vim9 LSP – not because I had any major issues with <code>coc.nvim</code>, but because of the second part of this section: code navigation.</p>
<p>I am really used to <code>telescope.nvim</code>.
The popups are nice, there’s fuzzy finding, it feels well integrated into Neovim and is one of the reasons I enjoyed using it so much.</p>
<p>In the terminal I’m already used to <code>fzf</code> so I tried out <a href="https://github.com/junegunn/fzf.vim">fzf.vim</a> which more or less displays the output of <code>fzf</code> in a nice looking popup inside of Vim.
And that’s already the main issue I have with it:
Since it is <code>fzf</code> all the shortcuts you already know for filtering etc. will just apply.
But since it is not a pure vim plugin it doesn’t support things like syntax highlighting.
If you have <a href="https://github.com/sharkdp/bat"><code>bat</code></a> installed it will use that for syntax highlighting, but this will also mean the highlighting is completely different from what you normally see inside of Vim.<sup class="footnote-ref"><a href="#fn-bat-thoughts" id="fnref-bat-thoughts" data-footnote-ref>3</a></sup></p>
<p>I kept with it for a couple days because <code>coc.nvim</code> has an <a href="https://github.com/antoinemadec/coc-fzf">extension</a> that shows popups using <code>fzf.nvim</code>, but in the end I got too annoyed<sup class="footnote-ref"><a href="#fn-coc-rant" id="fnref-coc-rant" data-footnote-ref>4</a></sup> and decided to look for alternatives.
That’s when I found out about <a href="https://github.com/vim-fuzzbox/fuzzbox.vim"><code>fuzzbox.vim</code></a> which has a <a href="https://github.com/vim-fuzzbox/fuzzbox-lsp.vim">plugin</a> that makes it integrate with the Vim9 LSP.</p>
<p>So I threw away everything I had set up using <code>coc.nvim</code> and <code>fzf.nvim</code> and decided to give Vim9 LSP (in combination with <code>fuzzbox.vim</code>) another try.
And yeah, it does look and feel much nicer over all (despite having to wait 5 seconds every time I open a Rust project).
It gives me back that feeling of using <code>telescope.nvim</code> and in turn makes using Vim a lot more fun.</p>
<p>Yay, one problem solved!
On to the next one.</p>
<h2 id="java-debugging">Java debugging<a href="#java-debugging" aria-label="Link to heading 'Java debugging'" data-heading-content="Java debugging" class="anchor"></a></h2>
<p>This is probably the most annoying section and it even was (and still is) in Neovim.</p>
<p>When working with Java I often have to debug things, be it test executions or running applications.
In 2024 I was using Neovim to write most of my code, but when it came to debugging I always started IntelliJ.
But gradually I looked more into how to debug things with Neovim and ended up with the following setup:</p>
<ul>
<li><a href="https://codeberg.org/mfussenegger/nvim-dap"><code>nvim-dap</code></a> – Provides support for the Debug Adapter Protocol that is also used by VSCode.</li>
<li><a href="https://github.com/rcarriga/nvim-dap-ui"><code>nvim-dap-ui</code></a> – A graphical debugger for Neovim that allows you to see the values of variables and evaluate commands at the current location (it also has buttons to skip over lines etc. which I always instead of setting keybinds for them).</li>
<li><a href="https://codeberg.org/mfussenegger/nvim-jdtls"><code>nvim-jdtls</code></a> – Provides better integration with the Java LSP and allows easy test execution (for a full class or the closest method).</li>
</ul>
<p>Overall this worked well enough, but felt very prone to breakage.
It required registering both the <code>vscode-java-test</code> and <code>vscode-java-debug</code> extensions with the LSP, of which <code>vscode-java-test</code> very often had conflicts in its dependencies that required manual workarounds.
Some time last month test execution stopped working completely for me, and while I tried to roll back to previous versions nothing really helped.</p>
<p>Knowing this I imagined that getting debugging working in Vim might be the biggest hurdle.</p>
<p>There’s a popular graphical debugger for Vim called <a href="https://github.com/puremourning/vimspector"><code>vimspector</code></a>, which from the screenshots looked like what I wanted and has builtin support for the Debug Adapter Protocol.
But how could I integrate it with Java?
The <a href="https://github.com/puremourning/vimspector#usage-with-youcompleteme">readme</a> mentions integration with <code>YouCompleteMe</code> (which is the main reason I tried it out as an LSP plugin), but apart from being too frustrated with it I now realize that there’s no real “integration” and instead the readme just documents how to manually start the debug server provided by <code>vscode-java-debug</code>.</p>
<p>In the issues of <code>vimspector</code> someone also mentioned that there’s a <a href="https://github.com/dansomething/coc-java-debug"><code>coc.nvim</code> extension</a>, so I tried it out for a bit and while debugging works fine I realized that the main thing I was missing was the support for test execution provided by <code>nvim-jdtls</code>.
But since I know how to manually start a debugger for a single test (<code>mvn test -Dmaven.surefire.debug -Dtest=TestClass#testMethod</code>) I thought why not try to write some Vim script that takes care of getting the debugger running and tells <code>coc-java-debug</code> to connect to it afterwards.
So I did that and, while the usability felt a bit worse than <code>nvim-jdtls</code>, it worked!</p>
<p>When I switched back to the Vim9 LSP I had to find another solution (there weren’t any extensions available) and not yet having realized that the <code>vimspector</code> readme actually told me how to do it with any LSP I stumbled upon <a href="https://urfoex.blogspot.com/2020/08/debugging-java-with-jdb-or-vim.html">this blog post</a> that went into more detail on manually starting the debug server and then connecting <code>vimspector</code> to it (using <a href="https://github.com/prabirshrestha/vim-lsp"><code>vim-lsp</code></a>, one of the LSP plugins I didn’t try out).</p>
<p>Unfortunately my config for this is still very much work-in-progress, but hopefully I’ll remember to link it here once I’m done with it.</p>
<p>In short I created two commands (<code>TestMethod</code> and <code>TestClass</code>) that figure out the name of the current class (<code>expand('%:t:r')</code>) and method (currently I’m hacky and search backwards for <code>@Test</code> and then the first word after “void”) and then use <code>term_start()</code> to start debugging the test with Maven.
This has a callback attached that looks for the “Listening for transport dt_socket at address: 5005” message.
Afterwards it uses the <code>rpc()</code> command provided by the Vim9 LSP plugin to tell <code>jdtls</code> to start the debug server provided by <code>vscode-java-debug</code>.
This returns the port, which in turn gets passed to <code>vimspector</code>’s <code>vimspector#LaunchWithSettings({DAPPort: port})</code> and automatically opens the graphical debugger.</p>
<p>This was definitely the biggest hurdle and the only part where I had to write more than a few line of Vim script, but it works fine and feels more resilient because it only depends on <code>vscode-java-debug</code> (which doesn’t have any dependencies and thus has less chance of having conflicts) and not <code>vscode-java-test</code>.</p>
<h2 id="diff-editing">Diff editing<a href="#diff-editing" aria-label="Link to heading 'Diff editing'" data-heading-content="Diff editing" class="anchor"></a></h2>
<p>I switched to <a href="https://www.jj-vcs.dev/latest/">Jujutsu</a> as my primary way to interact with commits in my Git repos some time last year (except for work projects that require Git LFS, which unfortunately isn’t well supports by Jujutsu <a href="https://github.com/jj-vcs/jj/issues/80">yet</a>).</p>
<p>As part of that I’ve gotten used to “interactive committing/squashing” to create a new commit from a selection of my changes or squash them into an existing one.
Jujutsu has a builtin tool for this which feels a bit clunky to use, so I had previously switched to <a href="https://github.com/julienvincent/hunk.nvim"><code>hunk.nvim</code></a>.</p>
<p>Things I like about <code>hunk.nvim</code>:</p>
<ul>
<li>It has a list of changed files on the left side that allows me to select individual files or whole folders to include in my commit.</li>
<li>Showing the diff for a file is a single button press (right arrow key).</li>
<li>I can switch the diff splits and select individual lines to include with regular vim motion.</li>
</ul>
<p>Things I don’t like about <code>hunk.nvim</code>:</p>
<ul>
<li>You have to select both the deleted lines (in the left split) and the changed lines (in the right split), otherwise it’ll add the new lines next to the deleted ones instead of replacing them (there might be a shortcut for this but I never looked into it).</li>
<li>It obviously doesn’t work with Vim.</li>
</ul>
<p>I took a look through the Jujutsu <a href="https://github.com/jj-vcs/jj/wiki/Vim,-Neovim">wiki</a> (which is how I originally found out about <code>hunk.nvim</code>) and tried out <a href="https://github.com/will133/vim-dirdiff"><code>vim-dirdiff</code></a>.
This did give me a file list (at the bottom) together with a split diff view, but some of its behavior felt weird, it wasn’t actively maintained and I was too focused on getting something closer to <code>hunk.nvim</code> that I looked for another option.</p>
<p>On the same page (for some reason only under the Neovim section) it is mentioned how to use vim as a diff editor for existing Git tooling.
This requires setting up a script that will create a temporary repository which has all your changes uncommitted.</p>
<p>Because of this I spent more time learning how diff editing works in vim, and how to do it using <a href="https://github.com/tpope/vim-fugitive"><code>vim-fugitive</code></a> (which was installed because it was included with <code>kickstart.nvim</code>, but I had pretty much only used it for the occasional <code>:G blame</code>).</p>
<p>So I made some changes in a repo, set up the script for Jujutsu, executed a <code>jj split</code>, and was placed inside of an empty Vim window.
Now I could do <code>:G</code> to show the list of changes, stage them with <code>s</code> and quit Vim, which automatically opened the window where I could type my commit message.
One thing that annoyed me was that deleted files were automatically staged, so I made some changes to the script (replacing <code>git add --intent-to-add -A</code> with <code>git add --intent-to-add --ignore-removal .</code>) and changed the Vim invocation to immediately drop me into <code>vim-fugitive</code>’s summary window (<code>vim -c 'Git | bdelete 1</code>).</p>
<p>At first I tried working with the diff editor (opening a changed file and doing <code>:Gvdiffsplit</code> or pressing <code>dv</code> on a file name) which involved learning about <code>:diffput</code> (<code>dp</code>) and <code>:diffget</code> (<code>do</code>) to send changes to or fetch changes from the other split window.
It’s funny, I’ve been using vim for diffing stuff for years and only now learned that there’s shortcuts to make it easier than manually copying and deleting lines.
This works well and is quite powerful (you can even stage individual word changes which wasn’t possible with <code>hunk.nvim</code>) but overall involves too many keypresses for a simple “I quickly want to squash theses lines into the previous commit”.</p>
<p><code>vim-fugitive</code> also has an option to show an inline diff for a file right in the summary window using either <code>=</code> to toggle or <code>&gt;</code>/<code>&lt;</code> to open and close it.
All of these keys are a bit hard to reach or require an additional modifier so I decided to remap them to the arrows keys like I was used to from <code>hunk.nvim</code> (on my Moonlander keyboard the left/right arrow can be quickly reached by my thumb, which I don’t really need for staging changes):</p>
<pre class="syntax-highlighting"><code class="language-vim"><span class="sh-source sh-viml"><span class="sh-support sh-function sh-viml">autocmd</span> <span class="sh-support sh-variable sh-viml">FileType</span> fugitive <span class="sh-support sh-function sh-viml">nmap</span> <span class="sh-support sh-type sh-viml">&lt;buffer&gt;</span> <span class="sh-support sh-type sh-viml">&lt;Left&gt;</span> <span class="sh-support sh-type sh-viml">&lt;plug&gt;</span>fugitive:&lt;
<span class="sh-support sh-function sh-viml">autocmd</span> <span class="sh-support sh-variable sh-viml">FileType</span> fugitive <span class="sh-support sh-function sh-viml">nmap</span> <span class="sh-support sh-type sh-viml">&lt;buffer&gt;</span> <span class="sh-support sh-type sh-viml">&lt;Right&gt;</span> <span class="sh-support sh-type sh-viml">&lt;plug&gt;</span>fugitive:&gt;
</span></code></pre>
<p>This isn’t exactly the workflow I was used to, but after trying it out a bit it feels</p>
<ul>
<li>more efficient, because I stay in one buffer.
And since deleted and added lines are displayed right next to each other I can do a quick visual select and press <code>s</code> to stage them instead of having to switch between three splits.</li>
<li>more powerful, because I can always fall back to <code>:Gvdiffsplit</code> when I care about more than simple line changes.</li>
</ul>
<h2 id="syntax-highlighting">Syntax highlighting<a href="#syntax-highlighting" aria-label="Link to heading 'Syntax highlighting'" data-heading-content="Syntax highlighting" class="anchor"></a></h2>
<p>This is the least important point since it is only a very minor issue.</p>
<p>Of course Vim has syntax highlighting.
The Vim9 LSP even supports “semantic highlighting” (where you can get slightly better syntax highlighting via information from the LSP, although this won’t apply to the previews in <code>fuzzbox.vim</code>).
But I’ve also gotten really used to how code is highlighted with <a href="https://github.com/nvim-treesitter/nvim-treesitter">nvim-treesitter</a>.</p>
<p>So I’ll either get used to how it looks without it, or write my own highlighting rules if it annoys me too much, or one of the experiments for adding treesitter support to Vim will get stable enough.<sup class="footnote-ref"><a href="#fn-vim-clap" id="fnref-vim-clap" data-footnote-ref>5</a></sup></p>
<h2 id="conclusion">Conclusion<a href="#conclusion" aria-label="Link to heading 'Conclusion'" data-heading-content="Conclusion" class="anchor"></a></h2>
<p>There are definitely some annoyances left, but overall I’m happy with the switch.
The majority of things I’m used to from Neovim also work in Vim and in a lot of cases they even feel more responsive (this might just be placebo, but I can imagine that plugins like <code>fuzzbox.vim</code> that are written in Vim9 script are faster than the Lua alternatives for Neovim).
Switching to Vim actually made me learn more about my editor since now I’m using more default features (like diff editing), had to write my own scripts, and rely (slightly) less on plugins that completely change how things work.</p>
<hr />
<p>PS: I completely forgot about it until I was about to publish but I also really liked using <a href="https://github.com/stevearc/oil.nvim"><code>oil.nvim</code></a> to switch between and copy/move/delete files.
The only alternative for Vim I could find was <a href="https://github.com/nda-cunh/SupraWater"><code>SupraWater</code></a>, which has some weird issues sometimes but overall still does what I want.</p>
<hr />
<p><em>Update 2026-09-11:</em>
At work I realized that one problem with my solution for <a href="#diff-editing">diff editing</a> is that, since you are in a temporary directory, Jujutsu’s <code>--scope</code> (or Git’s <code>includeIf</code>) no longer applies and I got an error that my email was not set.
This was quickly solved by updating the script.</p>
<p>Currently I use the following:</p>
<pre class="syntax-highlighting"><code class="language-sh"><span class="sh-source sh-shell sh-bash"><span class="sh-meta sh-function-call sh-shell"><span class="sh-support sh-function sh-set sh-shell">set</span></span><span class="sh-meta sh-function-call sh-arguments sh-shell"> <span class="sh-variable sh-parameter sh-option sh-shell"><span class="sh-punctuation sh-definition sh-parameter sh-shell">-</span>eu</span></span>
<span class="sh-variable sh-other sh-readwrite sh-assignment sh-shell">left</span><span class="sh-keyword sh-operator sh-assignment sh-shell">=</span><span class="sh-string sh-unquoted sh-shell"><span class="sh-string sh-quoted sh-double sh-shell"><span class="sh-punctuation sh-definition sh-string sh-begin sh-shell">&quot;</span><span class="sh-meta sh-group sh-expansion sh-parameter sh-shell"><span class="sh-punctuation sh-definition sh-variable sh-shell">$</span><span class="sh-variable sh-other sh-readwrite sh-shell">1</span></span><span class="sh-punctuation sh-definition sh-string sh-end sh-shell">&quot;</span></span></span>
<span class="sh-variable sh-other sh-readwrite sh-assignment sh-shell">right</span><span class="sh-keyword sh-operator sh-assignment sh-shell">=</span><span class="sh-string sh-unquoted sh-shell"><span class="sh-string sh-quoted sh-double sh-shell"><span class="sh-punctuation sh-definition sh-string sh-begin sh-shell">&quot;</span><span class="sh-meta sh-group sh-expansion sh-parameter sh-shell"><span class="sh-punctuation sh-definition sh-variable sh-shell">$</span><span class="sh-variable sh-other sh-readwrite sh-shell">2</span></span><span class="sh-punctuation sh-definition sh-string sh-end sh-shell">&quot;</span></span></span>

<span class="sh-comment sh-line sh-number-sign sh-shell"><span class="sh-punctuation sh-definition sh-comment sh-begin sh-shell">#</span></span><span class="sh-comment sh-line sh-number-sign sh-shell"> since we&#39;re outside the repo the set --scope no longer applies</span><span class="sh-comment sh-line sh-number-sign sh-shell">
</span><span class="sh-variable sh-other sh-readwrite sh-assignment sh-shell">gitArgs</span><span class="sh-keyword sh-operator sh-assignment sh-shell">=</span><span class="sh-punctuation sh-section sh-parens sh-begin sh-shell">(</span>
  -c user.email=<span class="sh-string sh-quoted sh-double sh-shell"><span class="sh-punctuation sh-definition sh-string sh-begin sh-shell">&quot;</span><span class="sh-meta sh-group sh-expansion sh-command sh-parens sh-shell"><span class="sh-punctuation sh-definition sh-variable sh-shell">$</span><span class="sh-punctuation sh-section sh-parens sh-begin sh-shell">(</span><span class="sh-meta sh-function-call sh-shell"><span class="sh-variable sh-function sh-shell">jj</span></span><span class="sh-meta sh-function-call sh-arguments sh-shell"> config get user.email</span><span class="sh-punctuation sh-section sh-parens sh-end sh-shell">)</span></span><span class="sh-punctuation sh-definition sh-string sh-end sh-shell">&quot;</span></span>
  -c user.name=<span class="sh-string sh-quoted sh-double sh-shell"><span class="sh-punctuation sh-definition sh-string sh-begin sh-shell">&quot;</span><span class="sh-meta sh-group sh-expansion sh-command sh-parens sh-shell"><span class="sh-punctuation sh-definition sh-variable sh-shell">$</span><span class="sh-punctuation sh-section sh-parens sh-begin sh-shell">(</span><span class="sh-meta sh-function-call sh-shell"><span class="sh-variable sh-function sh-shell">jj</span></span><span class="sh-meta sh-function-call sh-arguments sh-shell"> config get user.name</span><span class="sh-punctuation sh-section sh-parens sh-end sh-shell">)</span></span><span class="sh-punctuation sh-definition sh-string sh-end sh-shell">&quot;</span></span>
<span class="sh-punctuation sh-section sh-parens sh-end sh-shell">)</span>

<span class="sh-meta sh-function-call sh-shell"><span class="sh-variable sh-function sh-shell">rm</span></span><span class="sh-meta sh-function-call sh-arguments sh-shell"><span class="sh-variable sh-parameter sh-option sh-shell"><span class="sh-punctuation sh-definition sh-parameter sh-shell"> -</span>f</span> <span class="sh-string sh-quoted sh-double sh-shell"><span class="sh-punctuation sh-definition sh-string sh-begin sh-shell">&quot;</span><span class="sh-meta sh-group sh-expansion sh-parameter sh-shell"><span class="sh-punctuation sh-definition sh-variable sh-shell">$</span><span class="sh-variable sh-other sh-readwrite sh-shell">right</span></span>/JJ-INSTRUCTIONS<span class="sh-punctuation sh-definition sh-string sh-end sh-shell">&quot;</span></span></span>
<span class="sh-meta sh-function-call sh-shell"><span class="sh-variable sh-function sh-shell">git</span></span><span class="sh-meta sh-function-call sh-arguments sh-shell"><span class="sh-variable sh-parameter sh-option sh-shell"><span class="sh-punctuation sh-definition sh-parameter sh-shell"> -</span>C</span> <span class="sh-string sh-quoted sh-double sh-shell"><span class="sh-punctuation sh-definition sh-string sh-begin sh-shell">&quot;</span><span class="sh-meta sh-group sh-expansion sh-parameter sh-shell"><span class="sh-punctuation sh-definition sh-variable sh-shell">$</span><span class="sh-variable sh-other sh-readwrite sh-shell">left</span></span><span class="sh-punctuation sh-definition sh-string sh-end sh-shell">&quot;</span></span> init<span class="sh-variable sh-parameter sh-option sh-shell"><span class="sh-punctuation sh-definition sh-parameter sh-shell"> -</span>q</span></span>
<span class="sh-meta sh-function-call sh-shell"><span class="sh-variable sh-function sh-shell">git</span></span><span class="sh-meta sh-function-call sh-arguments sh-shell"><span class="sh-variable sh-parameter sh-option sh-shell"><span class="sh-punctuation sh-definition sh-parameter sh-shell"> -</span>C</span> <span class="sh-string sh-quoted sh-double sh-shell"><span class="sh-punctuation sh-definition sh-string sh-begin sh-shell">&quot;</span><span class="sh-meta sh-group sh-expansion sh-parameter sh-shell"><span class="sh-punctuation sh-definition sh-variable sh-shell">$</span><span class="sh-variable sh-other sh-readwrite sh-shell">left</span></span><span class="sh-punctuation sh-definition sh-string sh-end sh-shell">&quot;</span></span> add<span class="sh-variable sh-parameter sh-option sh-shell"><span class="sh-punctuation sh-definition sh-parameter sh-shell"> -</span>A</span></span>
<span class="sh-meta sh-function-call sh-shell"><span class="sh-variable sh-function sh-shell">git</span></span><span class="sh-meta sh-function-call sh-arguments sh-shell"><span class="sh-variable sh-parameter sh-option sh-shell"><span class="sh-punctuation sh-definition sh-parameter sh-shell"> -</span>C</span> <span class="sh-string sh-quoted sh-double sh-shell"><span class="sh-punctuation sh-definition sh-string sh-begin sh-shell">&quot;</span><span class="sh-meta sh-group sh-expansion sh-parameter sh-shell"><span class="sh-punctuation sh-definition sh-variable sh-shell">$</span><span class="sh-variable sh-other sh-readwrite sh-shell">left</span></span><span class="sh-punctuation sh-definition sh-string sh-end sh-shell">&quot;</span></span> <span class="sh-string sh-quoted sh-double sh-shell"><span class="sh-punctuation sh-definition sh-string sh-begin sh-shell">&quot;</span><span class="sh-meta sh-group sh-expansion sh-parameter sh-shell"><span class="sh-punctuation sh-definition sh-variable sh-shell">$</span><span class="sh-punctuation sh-section sh-expansion sh-parameter sh-begin sh-shell">{</span></span><span class="sh-meta sh-group sh-expansion sh-parameter sh-shell"><span class="sh-variable sh-other sh-readwrite sh-shell">gitArgs<span class="sh-punctuation sh-section sh-braces sh-begin sh-shell">[</span><span class="sh-variable sh-language sh-array sh-shell">@</span><span class="sh-punctuation sh-section sh-braces sh-end sh-shell">]</span></span></span><span class="sh-meta sh-group sh-expansion sh-parameter sh-shell"><span class="sh-punctuation sh-section sh-expansion sh-parameter sh-end sh-shell">}</span></span><span class="sh-punctuation sh-definition sh-string sh-end sh-shell">&quot;</span></span> commit<span class="sh-variable sh-parameter sh-option sh-shell"><span class="sh-punctuation sh-definition sh-parameter sh-shell"> -</span>q</span><span class="sh-variable sh-parameter sh-option sh-shell"><span class="sh-punctuation sh-definition sh-parameter sh-shell"> -</span>m</span> baseline<span class="sh-variable sh-parameter sh-option sh-shell"><span class="sh-punctuation sh-definition sh-parameter sh-shell"> --</span>allow-empty <span class="sh-comment sh-line sh-number-sign sh-shell"><span class="sh-punctuation sh-definition sh-comment sh-begin sh-shell">#</span></span><span class="sh-comment sh-line sh-number-sign sh-shell"> create parent commit</span><span class="sh-comment sh-line sh-number-sign sh-shell">
</span></span></span><span class="sh-meta sh-function-call sh-shell"><span class="sh-variable sh-function sh-shell">mv</span></span><span class="sh-meta sh-function-call sh-arguments sh-shell"> <span class="sh-string sh-quoted sh-double sh-shell"><span class="sh-punctuation sh-definition sh-string sh-begin sh-shell">&quot;</span><span class="sh-meta sh-group sh-expansion sh-parameter sh-shell"><span class="sh-punctuation sh-definition sh-variable sh-shell">$</span><span class="sh-variable sh-other sh-readwrite sh-shell">left</span></span>/.git<span class="sh-punctuation sh-definition sh-string sh-end sh-shell">&quot;</span></span> <span class="sh-string sh-quoted sh-double sh-shell"><span class="sh-punctuation sh-definition sh-string sh-begin sh-shell">&quot;</span><span class="sh-meta sh-group sh-expansion sh-parameter sh-shell"><span class="sh-punctuation sh-definition sh-variable sh-shell">$</span><span class="sh-variable sh-other sh-readwrite sh-shell">right</span></span><span class="sh-punctuation sh-definition sh-string sh-end sh-shell">&quot;</span></span></span>
<span class="sh-comment sh-line sh-number-sign sh-shell"><span class="sh-punctuation sh-definition sh-comment sh-begin sh-shell">#</span></span><span class="sh-comment sh-line sh-number-sign sh-shell"> create current working copy by marking all files as unstaged (even deletions)</span><span class="sh-comment sh-line sh-number-sign sh-shell">
</span><span class="sh-meta sh-function-call sh-shell"><span class="sh-variable sh-function sh-shell">git</span></span><span class="sh-meta sh-function-call sh-arguments sh-shell"><span class="sh-variable sh-parameter sh-option sh-shell"><span class="sh-punctuation sh-definition sh-parameter sh-shell"> -</span>C</span> <span class="sh-string sh-quoted sh-double sh-shell"><span class="sh-punctuation sh-definition sh-string sh-begin sh-shell">&quot;</span><span class="sh-meta sh-group sh-expansion sh-parameter sh-shell"><span class="sh-punctuation sh-definition sh-variable sh-shell">$</span><span class="sh-variable sh-other sh-readwrite sh-shell">right</span></span><span class="sh-punctuation sh-definition sh-string sh-end sh-shell">&quot;</span></span> add<span class="sh-variable sh-parameter sh-option sh-shell"><span class="sh-punctuation sh-definition sh-parameter sh-shell"> --</span>intent-to-add</span><span class="sh-variable sh-parameter sh-option sh-shell"><span class="sh-punctuation sh-definition sh-parameter sh-shell"> --</span>ignore-removal</span> .</span>

<span class="sh-comment sh-line sh-number-sign sh-shell"><span class="sh-punctuation sh-definition sh-comment sh-begin sh-shell">#</span></span><span class="sh-comment sh-line sh-number-sign sh-shell"> open vim with fugitive&#39;s status, close the empty buffer</span><span class="sh-comment sh-line sh-number-sign sh-shell">
</span><span class="sh-punctuation sh-definition sh-compound sh-begin sh-shell">(</span><span class="sh-meta sh-function-call sh-shell"><span class="sh-support sh-function sh-cd sh-shell">cd</span></span><span class="sh-meta sh-function-call sh-arguments sh-shell"> <span class="sh-string sh-quoted sh-double sh-shell"><span class="sh-punctuation sh-definition sh-string sh-begin sh-shell">&quot;</span><span class="sh-meta sh-group sh-expansion sh-parameter sh-shell"><span class="sh-punctuation sh-definition sh-variable sh-shell">$</span><span class="sh-variable sh-other sh-readwrite sh-shell">right</span></span><span class="sh-punctuation sh-definition sh-string sh-end sh-shell">&quot;</span></span></span><span class="sh-keyword sh-operator sh-logical sh-continue sh-shell">;</span> <span class="sh-meta sh-function-call sh-shell"><span class="sh-variable sh-function sh-shell">vim</span></span><span class="sh-meta sh-function-call sh-arguments sh-shell"><span class="sh-variable sh-parameter sh-option sh-shell"><span class="sh-punctuation sh-definition sh-parameter sh-shell"> -</span>c</span> <span class="sh-string sh-quoted sh-single sh-shell"><span class="sh-punctuation sh-definition sh-string sh-begin sh-shell">&#39;</span>Git | bdelete 1<span class="sh-punctuation sh-definition sh-string sh-end sh-shell">&#39;</span></span></span><span class="sh-punctuation sh-definition sh-compound sh-end sh-shell">)</span>

<span class="sh-meta sh-function-call sh-shell"><span class="sh-variable sh-function sh-shell">git</span></span><span class="sh-meta sh-function-call sh-arguments sh-shell"><span class="sh-variable sh-parameter sh-option sh-shell"><span class="sh-punctuation sh-definition sh-parameter sh-shell"> -</span>C</span> <span class="sh-string sh-quoted sh-double sh-shell"><span class="sh-punctuation sh-definition sh-string sh-begin sh-shell">&quot;</span><span class="sh-meta sh-group sh-expansion sh-parameter sh-shell"><span class="sh-punctuation sh-definition sh-variable sh-shell">$</span><span class="sh-variable sh-other sh-readwrite sh-shell">right</span></span><span class="sh-punctuation sh-definition sh-string sh-end sh-shell">&quot;</span></span> diff-index<span class="sh-variable sh-parameter sh-option sh-shell"><span class="sh-punctuation sh-definition sh-parameter sh-shell"> --</span>quiet</span><span class="sh-variable sh-parameter sh-option sh-shell"><span class="sh-punctuation sh-definition sh-parameter sh-shell"> --</span>cached</span> HEAD</span> <span class="sh-keyword sh-operator sh-logical sh-and sh-shell">&amp;&amp;</span> <span class="sh-punctuation sh-definition sh-compound sh-braces sh-begin sh-shell">{</span> <span class="sh-meta sh-function-call sh-shell"><span class="sh-support sh-function sh-echo sh-shell">echo</span></span><span class="sh-meta sh-function-call sh-arguments sh-shell"> <span class="sh-string sh-quoted sh-double sh-shell"><span class="sh-punctuation sh-definition sh-string sh-begin sh-shell">&quot;</span>No changes done, aborting split.<span class="sh-punctuation sh-definition sh-string sh-end sh-shell">&quot;</span></span></span><span class="sh-keyword sh-operator sh-logical sh-continue sh-shell">;</span> <span class="sh-meta sh-function-call sh-shell"><span class="sh-support sh-function sh-exit sh-shell">exit</span></span><span class="sh-meta sh-function-call sh-arguments sh-shell"> 1</span><span class="sh-keyword sh-operator sh-logical sh-continue sh-shell">;</span> <span class="sh-punctuation sh-definition sh-compound sh-braces sh-end sh-shell">}</span>
<span class="sh-meta sh-function-call sh-shell"><span class="sh-variable sh-function sh-shell">git</span></span><span class="sh-meta sh-function-call sh-arguments sh-shell"><span class="sh-variable sh-parameter sh-option sh-shell"><span class="sh-punctuation sh-definition sh-parameter sh-shell"> -</span>C</span> <span class="sh-string sh-quoted sh-double sh-shell"><span class="sh-punctuation sh-definition sh-string sh-begin sh-shell">&quot;</span><span class="sh-meta sh-group sh-expansion sh-parameter sh-shell"><span class="sh-punctuation sh-definition sh-variable sh-shell">$</span><span class="sh-variable sh-other sh-readwrite sh-shell">right</span></span><span class="sh-punctuation sh-definition sh-string sh-end sh-shell">&quot;</span></span> <span class="sh-string sh-quoted sh-double sh-shell"><span class="sh-punctuation sh-definition sh-string sh-begin sh-shell">&quot;</span><span class="sh-meta sh-group sh-expansion sh-parameter sh-shell"><span class="sh-punctuation sh-definition sh-variable sh-shell">$</span><span class="sh-punctuation sh-section sh-expansion sh-parameter sh-begin sh-shell">{</span></span><span class="sh-meta sh-group sh-expansion sh-parameter sh-shell"><span class="sh-variable sh-other sh-readwrite sh-shell">gitArgs<span class="sh-punctuation sh-section sh-braces sh-begin sh-shell">[</span><span class="sh-variable sh-language sh-array sh-shell">@</span><span class="sh-punctuation sh-section sh-braces sh-end sh-shell">]</span></span></span><span class="sh-meta sh-group sh-expansion sh-parameter sh-shell"><span class="sh-punctuation sh-section sh-expansion sh-parameter sh-end sh-shell">}</span></span><span class="sh-punctuation sh-definition sh-string sh-end sh-shell">&quot;</span></span> commit<span class="sh-variable sh-parameter sh-option sh-shell"><span class="sh-punctuation sh-definition sh-parameter sh-shell"> -</span>q</span><span class="sh-variable sh-parameter sh-option sh-shell"><span class="sh-punctuation sh-definition sh-parameter sh-shell"> -</span>m</span> split <span class="sh-comment sh-line sh-number-sign sh-shell"><span class="sh-punctuation sh-definition sh-comment sh-begin sh-shell">#</span></span><span class="sh-comment sh-line sh-number-sign sh-shell"> create commit on top of parent including changes</span><span class="sh-comment sh-line sh-number-sign sh-shell">
</span></span><span class="sh-meta sh-function-call sh-shell"><span class="sh-variable sh-function sh-shell">git</span></span><span class="sh-meta sh-function-call sh-arguments sh-shell"><span class="sh-variable sh-parameter sh-option sh-shell"><span class="sh-punctuation sh-definition sh-parameter sh-shell"> -</span>C</span> <span class="sh-string sh-quoted sh-double sh-shell"><span class="sh-punctuation sh-definition sh-string sh-begin sh-shell">&quot;</span><span class="sh-meta sh-group sh-expansion sh-parameter sh-shell"><span class="sh-punctuation sh-definition sh-variable sh-shell">$</span><span class="sh-variable sh-other sh-readwrite sh-shell">right</span></span><span class="sh-punctuation sh-definition sh-string sh-end sh-shell">&quot;</span></span> restore . <span class="sh-comment sh-line sh-number-sign sh-shell"><span class="sh-punctuation sh-definition sh-comment sh-begin sh-shell">#</span></span><span class="sh-comment sh-line sh-number-sign sh-shell"> undo changes in modified files</span><span class="sh-comment sh-line sh-number-sign sh-shell">
</span></span><span class="sh-meta sh-function-call sh-shell"><span class="sh-variable sh-function sh-shell">git</span></span><span class="sh-meta sh-function-call sh-arguments sh-shell"><span class="sh-variable sh-parameter sh-option sh-shell"><span class="sh-punctuation sh-definition sh-parameter sh-shell"> -</span>C</span> <span class="sh-string sh-quoted sh-double sh-shell"><span class="sh-punctuation sh-definition sh-string sh-begin sh-shell">&quot;</span><span class="sh-meta sh-group sh-expansion sh-parameter sh-shell"><span class="sh-punctuation sh-definition sh-variable sh-shell">$</span><span class="sh-variable sh-other sh-readwrite sh-shell">right</span></span><span class="sh-punctuation sh-definition sh-string sh-end sh-shell">&quot;</span></span> reset .   <span class="sh-comment sh-line sh-number-sign sh-shell"><span class="sh-punctuation sh-definition sh-comment sh-begin sh-shell">#</span></span><span class="sh-comment sh-line sh-number-sign sh-shell"> undo --intent-to-add</span><span class="sh-comment sh-line sh-number-sign sh-shell">
</span></span><span class="sh-meta sh-function-call sh-shell"><span class="sh-variable sh-function sh-shell">git</span></span><span class="sh-meta sh-function-call sh-arguments sh-shell"><span class="sh-variable sh-parameter sh-option sh-shell"><span class="sh-punctuation sh-definition sh-parameter sh-shell"> -</span>C</span> <span class="sh-string sh-quoted sh-double sh-shell"><span class="sh-punctuation sh-definition sh-string sh-begin sh-shell">&quot;</span><span class="sh-meta sh-group sh-expansion sh-parameter sh-shell"><span class="sh-punctuation sh-definition sh-variable sh-shell">$</span><span class="sh-variable sh-other sh-readwrite sh-shell">right</span></span><span class="sh-punctuation sh-definition sh-string sh-end sh-shell">&quot;</span></span> clean<span class="sh-variable sh-parameter sh-option sh-shell"><span class="sh-punctuation sh-definition sh-parameter sh-shell"> -</span>q</span><span class="sh-variable sh-parameter sh-option sh-shell"><span class="sh-punctuation sh-definition sh-parameter sh-shell"> -</span>df <span class="sh-comment sh-line sh-number-sign sh-shell"><span class="sh-punctuation sh-definition sh-comment sh-begin sh-shell">#</span></span><span class="sh-comment sh-line sh-number-sign sh-shell"> remove untracked files</span><span class="sh-comment sh-line sh-number-sign sh-shell">
</span></span></span></span></code></pre>
<section class="footnotes" data-footnotes>
<ol>
<li id="fn-arch">
<p>I had a brief phase in uni where I was running Arch on an old ThinkPad X200T, but apart from that I mostly stuck with openSUSE (since our servers at work back in the day were running SLES and I liked the mascot and it came in handy a couple of times to use something RPM based because we built RPM packages and all our customers were also on SLES or RHEL) before I ended up switching everything to NixOS. <a href="#fnref-arch" class="footnote-backref" data-footnote-backref data-footnote-backref-idx="1" aria-label="Back to reference 1">↩</a></p>
</li>
<li id="fn-vim9-lsp-block">
<p>The documentation says to configure <code>rust-analyzer</code> with <code>syncInit: true</code> and I tried setting it to false, but none of the other LSP plugins had this issue.
I should look into it some time… <a href="#fnref-vim9-lsp-block" class="footnote-backref" data-footnote-backref data-footnote-backref-idx="2" aria-label="Back to reference 2">↩</a></p>
</li>
<li id="fn-bat-thoughts">
<p>Whenever I click on one of those “must use Linux tools” videos I always see <code>bat</code> as one of the recommended programs, but I never got the point of it?
If I want to <code>cat</code> something it means I want to take a quick glance at the contents and don’t care about the syntax, because if I care about the syntax I will just open it in vim. <br />
Maybe integration with things like <code>fzf</code> is where <code>bat</code> shines more:
Not as a standalone tool but as something you can integrate if you want some basic syntax highlighting. <a href="#fnref-bat-thoughts" class="footnote-backref" data-footnote-backref data-footnote-backref-idx="3" aria-label="Back to reference 3">↩</a></p>
</li>
<li id="fn-coc-rant">
<p><code>coc.nvim</code> and its extensions are such a mishmash of languages that make me just wonder “why”.
LSP has a feature that allows you to show “document symbols” and “workspace symbols”.
Naturally <code>coc.nvim</code> has an API to access those, but for some reason there’s no way to show them in a (native Vim) popup like it does with “go to references”?
<code>coc-fzf</code> solves this for “document symbols”, but for “workspace symbols” it needs the Neovim Python client (which obviously doesn’t work in Vim).
Why does this require Python in the first place when <code>coc.nvim</code> already has the necessary data? <a href="#fnref-coc-rant" class="footnote-backref" data-footnote-backref data-footnote-backref-idx="4" aria-label="Back to reference 4">↩</a></p>
</li>
<li id="fn-vim-clap">
<p><a href="https://github.com/liuchengxu/vim-clap"><code>vim-clap</code></a> currently has “experimental” plugin support for things like treesitter among other things.
I’m not that interested in its main feature (the fuzzy finders don’t look as nice as <code>fuzzbox.vim</code>, although that makes them feel more “Vim native”), but maybe I’ll give it a try some time since one of the plugins provides LSP support as well. <a href="#fnref-vim-clap" class="footnote-backref" data-footnote-backref data-footnote-backref-idx="5" aria-label="Back to reference 5">↩</a></p>
</li>
</ol>
</section>
]]></description><guid>https://qtea.me/posts/switching-from-neovim-to-vim/</guid><pubDate>Sun, 6 Sep 2026 00:00:00 +0000</pubDate></item><item><title>Learning to not overengineer backups</title><link>https://qtea.me/posts/learning-to-not-overengineer-backups/</link><description><![CDATA[<p>For the longest time my backup strategy consisted of two parts:</p>
<ol>
<li>Personal files are automatically synced with OneDrive on my PC and laptop.</li>
<li>My NAS mirrors some of that data and occasionally exports it to an external HDD.
And then every few months I rotate that external HDD with a different one and store the other at my parents.</li>
</ol>
<p>So for most of my data I did actually have 3 copies on 2 different media types with 1 (or 2 even) stored off-site.</p>
<p>But when I upgraded my NAS to 4 TB drives I couldn’t backup all the data anymore since my external HDDs were only 3 TB.
So those backups fell out of use.
It’s been <em>many years</em> since I last did a proper backup and I still get the “data backup task failed” notification every Sunday at 3 am.<sup class="footnote-ref"><a href="#fn-optimal-world" id="fnref-optimal-world" data-footnote-ref>1</a></sup></p>
<p>But since my most important files (documents and photos) were still on OneDrive I wasn’t that worried about backups.
Sure I should probably try to fix this eventually, but if my phone or PC or laptop dies I at least won’t lose anything important – it’ll only be super annoying.</p>
<hr />
<p>When I switched to Linux in 2023 I couldn’t use OneDrive anymore because there was no equivalent integration like in Windows Explorer.
The closest thing I could find was NextCloud which integrated somewhat well with specific file managers, but I was already using OneDrive and didn’t want to pay for cloud storage somewhere else.<sup class="footnote-ref"><a href="#fn-onedrive-cost" id="fnref-onedrive-cost" data-footnote-ref>2</a></sup>
I tried using tools like <code>onedriver</code> for a while, mostly for my ebook library, but those felt unpredictable and quite slow.
And Calibre <em>really</em> doesn’t like having its database on something slow, which caused a bunch of frustration every time I imported new ebooks.</p>
<p>So for quite a while I didn’t have any automatic backups <em>at all</em> (excluding photo backups from my phone).
When I worked on something I did a manual drag-and-drop to the OneDrive website, because at least that way I could be certain that it was uploaded.</p>
<p>I was still annoyed though because I was using OneDrive – the only remaining Microsoft service I relied on.
(Well, that and OneNote, which I’m also trying to migrate away from. And I guess technically my Minecraft account counts too.)</p>
<hr />
<p>Earlier this year I looked into backup software for Linux end started comparing <a href="https://restic.net/">restic</a> and <a href="https://www.borgbackup.org/">Borg</a>.
I ended up looking a bit more into restic because the NixOS module seemed more configurable and decided “fuck it I’ll just get a 1 TB Hetzner Storage Box”<sup class="footnote-ref"><a href="#fn-storage-box" id="fnref-storage-box" data-footnote-ref>3</a></sup> so I could try it out a bit and see how I like it.</p>
<p>The Storage Box docs also explicitly mention that they support the restic backend via Rclone, which was probably one of the reasons why I went with it?
Although Hetzner has no docs on how to actually do this and after finding <a href="https://fluix.one/blog/hetzner-restic-append-only/">this</a> blog post, trying it out a bit and comparing upload speeds, I decided I’m fine just using the simpler SFTP option.</p>
<p>I started setting up some backup jobs for my servers (which weren’t backed up <em>at all</em>) and pretty quickly started thinking that I would like to organize these backups a bit more.</p>
<p>Hetzner allows you to create “sub accounts” for your Storage Box, which is a separate login and password that is unable to see the data of any of the other sub accounts.</p>
<p>So I decided to create one account per “big” data type (documents, music, photos) and then have a separate account for each machine to handle more specific backups (config files, database dumps).</p>
<p>But I’m running a lot of different services!
What if one day I decide that I no longer want to use Calibre for my ebooks but something else!
Then I’d have to delete all the old snapshots that include Calibre backups (imagining a case where I need to free up space on the Storage Box) because restic doesn’t allow you to delete individual files from old backups!</p>
<p>Luckily restic supports tagging backups.
Tagged backups are still deduplicated among all the other files in your backup repository, but in all other things they are pretty much separate.
You can tell it to only delete snapshots for a specific tag.
And if I’m doing it super granular doesn’t that mean I’m more flexible?
If one backup task fails (because it needs to stop an application first so it can safely backup the SQLite database – and the application just won’t stop) it doesn’t influence any of the other backups.
Brilliant idea.
I will just tag my backups with “books” or “kodi” or any other categories I can come up with.</p>
<p>The main issue I found with this approach is that it would cause a lot of duplication in my NixOS config.
Not only would I need separate backup configurations for each repository (Storage Box sub account), I’d also need one for each tag.
Here is what one backup configuration would look like:</p>
<pre class="syntax-highlighting"><code class="language-nix"><span class="sh-source sh-nix"><span class="sh-punctuation sh-definition sh-attrset-or-function sh-nix">{</span>
<span class="sh-entity sh-other sh-attribute-name sh-multipart sh-nix">services</span>.<span class="sh-entity sh-other sh-attribute-name sh-multipart sh-nix">restic</span>.<span class="sh-entity sh-other sh-attribute-name sh-multipart sh-nix">backups</span>.<span class="sh-entity sh-other sh-attribute-name sh-multipart sh-nix">myserver-books</span> <span class="sh-keyword sh-operator sh-bind sh-nix">=</span> <span class="sh-punctuation sh-definition sh-attrset-or-function sh-nix">{</span>
  <span class="sh-entity sh-other sh-attribute-name sh-multipart sh-nix">extraOptions</span> <span class="sh-keyword sh-operator sh-bind sh-nix">=</span> <span class="sh-punctuation sh-definition sh-list sh-nix">[</span><span class="sh-string sh-quoted sh-double sh-nix"><span class="sh-punctuation sh-definition sh-string sh-double sh-start sh-nix">&quot;</span>sftp.args=&#39;-i <span class="sh-markup sh-italic"><span class="sh-punctuation sh-section sh-embedded sh-begin sh-nix">${</span><span class="sh-variable sh-parameter sh-name sh-nix">privateKeyPath</span><span class="sh-punctuation sh-section sh-embedded sh-end sh-nix">}</span></span>&#39;<span class="sh-punctuation sh-definition sh-string sh-double sh-end sh-nix">&quot;</span></span><span class="sh-punctuation sh-definition sh-list sh-nix">]</span><span class="sh-punctuation sh-terminator sh-bind sh-nix">;</span>
  <span class="sh-entity sh-other sh-attribute-name sh-multipart sh-nix">environmentFile</span> <span class="sh-keyword sh-operator sh-bind sh-nix">=</span> <span class="sh-variable sh-parameter sh-name sh-nix">myserverResticEnvFile</span><span class="sh-punctuation sh-terminator sh-bind sh-nix">;</span>
  <span class="sh-entity sh-other sh-attribute-name sh-multipart sh-nix">timerConfig</span> <span class="sh-keyword sh-operator sh-bind sh-nix">=</span> <span class="sh-punctuation sh-definition sh-attrset-or-function sh-nix">{</span>
    <span class="sh-entity sh-other sh-attribute-name sh-multipart sh-nix">OnCalendar</span> <span class="sh-keyword sh-operator sh-bind sh-nix">=</span> <span class="sh-string sh-quoted sh-double sh-nix"><span class="sh-punctuation sh-definition sh-string sh-double sh-start sh-nix">&quot;</span>03:00<span class="sh-punctuation sh-definition sh-string sh-double sh-end sh-nix">&quot;</span></span><span class="sh-punctuation sh-terminator sh-bind sh-nix">;</span>
    <span class="sh-entity sh-other sh-attribute-name sh-multipart sh-nix">RandomizedDelaySec</span> <span class="sh-keyword sh-operator sh-bind sh-nix">=</span> <span class="sh-string sh-quoted sh-double sh-nix"><span class="sh-punctuation sh-definition sh-string sh-double sh-start sh-nix">&quot;</span>30m<span class="sh-punctuation sh-definition sh-string sh-double sh-end sh-nix">&quot;</span></span><span class="sh-punctuation sh-terminator sh-bind sh-nix">;</span>
    <span class="sh-entity sh-other sh-attribute-name sh-multipart sh-nix">Persistent</span> <span class="sh-keyword sh-operator sh-bind sh-nix">=</span> <span class="sh-constant sh-language sh-nix">true</span><span class="sh-punctuation sh-terminator sh-bind sh-nix">;</span>
  <span class="sh-punctuation sh-definition sh-attrset sh-nix">}</span><span class="sh-punctuation sh-terminator sh-bind sh-nix">;</span>
  <span class="sh-entity sh-other sh-attribute-name sh-multipart sh-nix">extraBackupArgs</span> <span class="sh-keyword sh-operator sh-bind sh-nix">=</span> <span class="sh-punctuation sh-definition sh-list sh-nix">[</span>
    <span class="sh-string sh-quoted sh-double sh-nix"><span class="sh-punctuation sh-definition sh-string sh-double sh-start sh-nix">&quot;</span>--retry-lock 5m<span class="sh-punctuation sh-definition sh-string sh-double sh-end sh-nix">&quot;</span></span>
    <span class="sh-string sh-quoted sh-double sh-nix"><span class="sh-punctuation sh-definition sh-string sh-double sh-start sh-nix">&quot;</span>--tag books<span class="sh-punctuation sh-definition sh-string sh-double sh-end sh-nix">&quot;</span></span>
  <span class="sh-punctuation sh-definition sh-list sh-nix">]</span><span class="sh-punctuation sh-terminator sh-bind sh-nix">;</span>
  <span class="sh-entity sh-other sh-attribute-name sh-multipart sh-nix">pruneOpts</span> <span class="sh-keyword sh-operator sh-bind sh-nix">=</span> <span class="sh-punctuation sh-definition sh-list sh-nix">[</span>
    <span class="sh-string sh-quoted sh-double sh-nix"><span class="sh-punctuation sh-definition sh-string sh-double sh-start sh-nix">&quot;</span>--keep-daily 7<span class="sh-punctuation sh-definition sh-string sh-double sh-end sh-nix">&quot;</span></span>
    <span class="sh-string sh-quoted sh-double sh-nix"><span class="sh-punctuation sh-definition sh-string sh-double sh-start sh-nix">&quot;</span>--keep-weekly 5<span class="sh-punctuation sh-definition sh-string sh-double sh-end sh-nix">&quot;</span></span>
    <span class="sh-string sh-quoted sh-double sh-nix"><span class="sh-punctuation sh-definition sh-string sh-double sh-start sh-nix">&quot;</span>--keep-monthly 12<span class="sh-punctuation sh-definition sh-string sh-double sh-end sh-nix">&quot;</span></span>
    <span class="sh-string sh-quoted sh-double sh-nix"><span class="sh-punctuation sh-definition sh-string sh-double sh-start sh-nix">&quot;</span>--tag books<span class="sh-punctuation sh-definition sh-string sh-double sh-end sh-nix">&quot;</span></span>
  <span class="sh-punctuation sh-definition sh-list sh-nix">]</span><span class="sh-punctuation sh-terminator sh-bind sh-nix">;</span>
  <span class="sh-entity sh-other sh-attribute-name sh-multipart sh-nix">paths</span> <span class="sh-keyword sh-operator sh-bind sh-nix">=</span> <span class="sh-punctuation sh-definition sh-list sh-nix">[</span>
    <span class="sh-variable sh-parameter sh-name sh-nix">calibreDatabase</span>
    <span class="sh-variable sh-parameter sh-name sh-nix">booksDataDir</span>
  <span class="sh-punctuation sh-definition sh-list sh-nix">]</span><span class="sh-punctuation sh-terminator sh-bind sh-nix">;</span>
  <span class="sh-entity sh-other sh-attribute-name sh-multipart sh-nix">backupPrepareCommand</span> <span class="sh-keyword sh-operator sh-bind sh-nix">=</span> <span class="sh-string sh-quoted sh-double sh-nix"><span class="sh-punctuation sh-definition sh-string sh-double sh-start sh-nix">&quot;</span>stop the thing<span class="sh-punctuation sh-definition sh-string sh-double sh-end sh-nix">&quot;</span></span><span class="sh-punctuation sh-terminator sh-bind sh-nix">;</span>
  <span class="sh-entity sh-other sh-attribute-name sh-multipart sh-nix">backupCleanupCommand</span> <span class="sh-keyword sh-operator sh-bind sh-nix">=</span> <span class="sh-string sh-quoted sh-double sh-nix"><span class="sh-punctuation sh-definition sh-string sh-double sh-start sh-nix">&quot;</span>start the thing<span class="sh-punctuation sh-definition sh-string sh-double sh-end sh-nix">&quot;</span></span><span class="sh-punctuation sh-terminator sh-bind sh-nix">;</span>
<span class="sh-punctuation sh-definition sh-attrset sh-nix">}</span><span class="sh-punctuation sh-terminator sh-bind sh-nix">;</span>
<span class="sh-punctuation sh-definition sh-attrset sh-nix">}</span>
</span></code></pre>
<p><code>myserverResticEnv</code> being the path to a file with the following content:</p>
<pre class="syntax-highlighting"><code class="language-sh"><span class="sh-source sh-shell sh-bash"><span class="sh-variable sh-other sh-readwrite sh-assignment sh-shell">RESTIC_REPOSITORY</span><span class="sh-keyword sh-operator sh-assignment sh-shell">=</span><span class="sh-string sh-unquoted sh-shell">sftp://uMYID-sub1@uMYID-sub1.your-storagebox.de:23/</span>
<span class="sh-variable sh-other sh-readwrite sh-assignment sh-shell">RESTIC_PASSWORD</span><span class="sh-keyword sh-operator sh-assignment sh-shell">=</span><span class="sh-string sh-unquoted sh-shell">thisblogpostisgettingwaytoolongagain</span>
</span></code></pre>
<p>Since backups for “books” and “kodi” go to the same repository the <code>extraOptions</code> and <code>environmentFile</code> lines would need to stay the same for each tag.
And I probably want to share some of the <code>pruneOpts</code> as well.</p>
<p>NixOS is nice enough to create a script for each backup job that allows you to easily perform operations on the restic repository.
But the scripts are named after the backup so I’d have <code>restic-myserver-books</code> and <code>restic-myserver-kodi</code> and even more that all operate on the same repository.</p>
<p>Anyway the point is I thought I could make this a lot nicer by writing a wrapper module around <code>services.restic.backups</code>.
In the process I learned a lot about how the NixOS module system works (while being extremely frustrated at times) and ended up with this:</p>
<pre class="syntax-highlighting"><code class="language-nix"><span class="sh-source sh-nix"><span class="sh-punctuation sh-definition sh-attrset-or-function sh-nix">{</span>
<span class="sh-entity sh-other sh-attribute-name sh-multipart sh-nix">backups</span>.<span class="sh-entity sh-other sh-attribute-name sh-multipart sh-nix">myserver</span> <span class="sh-keyword sh-operator sh-bind sh-nix">=</span> <span class="sh-punctuation sh-definition sh-attrset-or-function sh-nix">{</span>
  <span class="sh-entity sh-other sh-attribute-name sh-multipart sh-nix">privateKey</span> <span class="sh-keyword sh-operator sh-bind sh-nix">=</span> <span class="sh-variable sh-parameter sh-name sh-nix">privateKeyPath</span><span class="sh-punctuation sh-terminator sh-bind sh-nix">;</span>
  <span class="sh-entity sh-other sh-attribute-name sh-multipart sh-nix">setup</span> <span class="sh-keyword sh-operator sh-bind sh-nix">=</span> <span class="sh-punctuation sh-definition sh-attrset-or-function sh-nix">{</span>
    <span class="sh-entity sh-other sh-attribute-name sh-multipart sh-nix">environmentFile</span> <span class="sh-keyword sh-operator sh-bind sh-nix">=</span> <span class="sh-variable sh-parameter sh-name sh-nix">myserverResticEnvFile</span><span class="sh-punctuation sh-terminator sh-bind sh-nix">;</span>
    <span class="sh-entity sh-other sh-attribute-name sh-multipart sh-nix">timerConfig</span> <span class="sh-keyword sh-operator sh-bind sh-nix">=</span> <span class="sh-punctuation sh-definition sh-attrset-or-function sh-nix">{</span>
      <span class="sh-entity sh-other sh-attribute-name sh-multipart sh-nix">OnCalendar</span> <span class="sh-keyword sh-operator sh-bind sh-nix">=</span> <span class="sh-string sh-quoted sh-double sh-nix"><span class="sh-punctuation sh-definition sh-string sh-double sh-start sh-nix">&quot;</span>03:00<span class="sh-punctuation sh-definition sh-string sh-double sh-end sh-nix">&quot;</span></span><span class="sh-punctuation sh-terminator sh-bind sh-nix">;</span>
      <span class="sh-entity sh-other sh-attribute-name sh-multipart sh-nix">RandomizedDelaySec</span> <span class="sh-keyword sh-operator sh-bind sh-nix">=</span> <span class="sh-string sh-quoted sh-double sh-nix"><span class="sh-punctuation sh-definition sh-string sh-double sh-start sh-nix">&quot;</span>30m<span class="sh-punctuation sh-definition sh-string sh-double sh-end sh-nix">&quot;</span></span><span class="sh-punctuation sh-terminator sh-bind sh-nix">;</span>
      <span class="sh-entity sh-other sh-attribute-name sh-multipart sh-nix">Persistent</span> <span class="sh-keyword sh-operator sh-bind sh-nix">=</span> <span class="sh-constant sh-language sh-nix">true</span><span class="sh-punctuation sh-terminator sh-bind sh-nix">;</span>
    <span class="sh-punctuation sh-definition sh-attrset sh-nix">}</span><span class="sh-punctuation sh-terminator sh-bind sh-nix">;</span>
    <span class="sh-entity sh-other sh-attribute-name sh-multipart sh-nix">extraBackupArgs</span> <span class="sh-keyword sh-operator sh-bind sh-nix">=</span> <span class="sh-punctuation sh-definition sh-list sh-nix">[</span>
      <span class="sh-string sh-quoted sh-double sh-nix"><span class="sh-punctuation sh-definition sh-string sh-double sh-start sh-nix">&quot;</span>--retry-lock 5m<span class="sh-punctuation sh-definition sh-string sh-double sh-end sh-nix">&quot;</span></span>
    <span class="sh-punctuation sh-definition sh-list sh-nix">]</span><span class="sh-punctuation sh-terminator sh-bind sh-nix">;</span>
    <span class="sh-entity sh-other sh-attribute-name sh-multipart sh-nix">pruneOpts</span> <span class="sh-keyword sh-operator sh-bind sh-nix">=</span> <span class="sh-punctuation sh-definition sh-list sh-nix">[</span>
      <span class="sh-string sh-quoted sh-double sh-nix"><span class="sh-punctuation sh-definition sh-string sh-double sh-start sh-nix">&quot;</span>--keep-daily 7<span class="sh-punctuation sh-definition sh-string sh-double sh-end sh-nix">&quot;</span></span>
      <span class="sh-string sh-quoted sh-double sh-nix"><span class="sh-punctuation sh-definition sh-string sh-double sh-start sh-nix">&quot;</span>--keep-weekly 5<span class="sh-punctuation sh-definition sh-string sh-double sh-end sh-nix">&quot;</span></span>
      <span class="sh-string sh-quoted sh-double sh-nix"><span class="sh-punctuation sh-definition sh-string sh-double sh-start sh-nix">&quot;</span>--keep-monthly 12<span class="sh-punctuation sh-definition sh-string sh-double sh-end sh-nix">&quot;</span></span>
    <span class="sh-punctuation sh-definition sh-list sh-nix">]</span><span class="sh-punctuation sh-terminator sh-bind sh-nix">;</span>
  <span class="sh-punctuation sh-definition sh-attrset sh-nix">}</span><span class="sh-punctuation sh-terminator sh-bind sh-nix">;</span>
<span class="sh-punctuation sh-definition sh-attrset sh-nix">}</span><span class="sh-punctuation sh-terminator sh-bind sh-nix">;</span>

<span class="sh-entity sh-other sh-attribute-name sh-multipart sh-nix">backups</span>.<span class="sh-entity sh-other sh-attribute-name sh-multipart sh-nix">myserver</span>.<span class="sh-entity sh-other sh-attribute-name sh-multipart sh-nix">tags</span>.<span class="sh-entity sh-other sh-attribute-name sh-multipart sh-nix">books</span> <span class="sh-keyword sh-operator sh-bind sh-nix">=</span> <span class="sh-punctuation sh-definition sh-attrset-or-function sh-nix">{</span>
  <span class="sh-entity sh-other sh-attribute-name sh-multipart sh-nix">paths</span> <span class="sh-keyword sh-operator sh-bind sh-nix">=</span> <span class="sh-punctuation sh-definition sh-list sh-nix">[</span>
    <span class="sh-variable sh-parameter sh-name sh-nix">calibreDatabase</span>
    <span class="sh-variable sh-parameter sh-name sh-nix">booksDataDir</span>
  <span class="sh-punctuation sh-definition sh-list sh-nix">]</span><span class="sh-punctuation sh-terminator sh-bind sh-nix">;</span>
  <span class="sh-entity sh-other sh-attribute-name sh-multipart sh-nix">backupPrepareCommand</span> <span class="sh-keyword sh-operator sh-bind sh-nix">=</span> <span class="sh-string sh-quoted sh-double sh-nix"><span class="sh-punctuation sh-definition sh-string sh-double sh-start sh-nix">&quot;</span>stop the thing<span class="sh-punctuation sh-definition sh-string sh-double sh-end sh-nix">&quot;</span></span><span class="sh-punctuation sh-terminator sh-bind sh-nix">;</span>
  <span class="sh-entity sh-other sh-attribute-name sh-multipart sh-nix">backupCleanupCommand</span> <span class="sh-keyword sh-operator sh-bind sh-nix">=</span> <span class="sh-string sh-quoted sh-double sh-nix"><span class="sh-punctuation sh-definition sh-string sh-double sh-start sh-nix">&quot;</span>start the thing<span class="sh-punctuation sh-definition sh-string sh-double sh-end sh-nix">&quot;</span></span><span class="sh-punctuation sh-terminator sh-bind sh-nix">;</span>
<span class="sh-punctuation sh-definition sh-attrset sh-nix">}</span><span class="sh-punctuation sh-terminator sh-bind sh-nix">;</span>
<span class="sh-punctuation sh-definition sh-attrset sh-nix">}</span>
</span></code></pre>
<ul>
<li><code>backups.&lt;name&gt;.privateKey</code> automatically translates it into the necessary <code>extraOptions</code> for each backup.</li>
<li><code>backups.&lt;name&gt;.setup</code> are config for the regular restic module which will apply to every backup under this name.</li>
<li><code>backups.&lt;name&gt;.tags.&lt;tag&gt;</code> are also config for the regular restic module, but these take precedence over the shared ones.
Also the specified <code>&lt;tag&gt;</code> is automatically added to each backup.</li>
</ul>
<p>At least to me this felt a lot nicer.
I can put all the boilerplate for backup configuration in a central place and have the “what to actually backup” closer to the configuration that actually runs the respective service.
(And my module creates the <code>restic-myserver</code> script so I don’t have to decide the tag based ones.)</p>
<p>You can probably already see the main issue here:
All my backups use the same timer config (±30 mins) so they are very likely to collide.
And while I could’ve configured the timers per tag at completely different times of the day to reduce that risk, it definitely wouldn’t eliminate it.</p>
<p>All my computers were using this for the past 5 months and while I was aware that these conflicts are happening I assumed that it will be fine.
Eventually (after a couple days or so) one tag will get the earliest randomized delay so it can successfully perform a backup.</p>
<p>The whole thing was still nagging me though, so about a week ago I decided I’ll migrate everything to the regular restic module and not do tag based backups anymore.
I still have the different repositories for documents, pictures etc., but server-specific stuff is now backed up all at once without any tags.</p>
<p>In the end I asked myself:
Why am I preparing a case that might never happen?
Less reliable backups are definitely not worth it just to have an easier time cleaning them up “someday”.</p>
<hr />
<p>You can find my NixOS module <a href="https://codeberg.org/qtea/nix/src/commit/356707f41b2f1e1cd226d83cf9055d3dfe1d08b6/modules/backup.nix">here</a>.
There is also a Home Manager module in the same directory, but I think that had an additional issue.</p>
<p>PS: I will leave the backup config as is for a while, but I don’t think that everything I tried was a bad idea.
It could still make sense to have a helper module that automatically sets the private key or environment file for all backup tasks.
As long as I don’t try to overengineer it again.</p>
<section class="footnotes" data-footnotes>
<ol>
<li id="fn-optimal-world">
<p>In an optimal world I’d be buying bigger drives for my NAS (the 4 TB ones are almost full, causing another constant “drives are running out of space” notification), but we don’t live in a world where you can afford to buy computer things anymore. <a href="#fnref-optimal-world" class="footnote-backref" data-footnote-backref data-footnote-backref-idx="1" aria-label="Back to reference 1">↩</a></p>
</li>
<li id="fn-onedrive-cost">
<p>Since my parents need Microsoft <del>Office</del> 365 anyway this has always been quite the steal.
No one else gives you 1 TB for only 1 € a month.
And you even get Office on top!!
(I don’t care about Office.)
Unfortunately the price has gotten more expensive recently now that they’re also bundling Copilot into it.
And then this month they <a href="https://windowsforum.com/news/microsoft-365-family-and-premium-onedrive-storage-drops-from-6tb-to-2tb-shared-in-2027.447651/">announced</a> that they’re cutting OneDrive from 1 TB <em>per family member</em> to 2 TB <em>shared across all of them</em>.
This would still be fine because I think no one besides me is even close to using the full 1 TB, but yeah… <a href="#fnref-onedrive-cost" class="footnote-backref" data-footnote-backref data-footnote-backref-idx="2" aria-label="Back to reference 2">↩</a></p>
</li>
<li id="fn-storage-box">
<p>When I got it and at the time of writing it is 3.81 € per month (including VAT), which is quite a bit more expensive than the 1 € (practically free because my mom pays for it) for OneDrive.
But hey.
If that’s what it takes to get away from Microsoft and maybe get more reliable backups. <a href="#fnref-storage-box" class="footnote-backref" data-footnote-backref data-footnote-backref-idx="3" aria-label="Back to reference 3">↩</a></p>
</li>
</ol>
</section>
]]></description><guid>https://qtea.me/posts/learning-to-not-overengineer-backups/</guid><pubDate>Tue, 27 Oct 2026 00:00:00 +0000</pubDate></item></channel></rss>