Publishing a side project requires completing a lot of different tasks. The creator needs to wear many different hats. Apart from architecting and programming the application, they have to think about the user interface and the user experience, write the documentation, promote the project in the various public channels and more.

All the roles are bound to one person. Every role is important.

It’s not all doom and gloom though. The extra responsibilities bring extra opportunities to learn and to grow — new information to read, new material to study, more experimentation in unknown areas.

One of my favorite “side quests” in my free time programming is icon design. I am not particularly good — although I think I am getting better — but thinking about a concept, iterating over the different ideas in Inkscape and producing the final result is a process that I find quite enjoyable.

Last month, I released my first ever GUI application, Klisi. I wrote some thoughts about that initial release in a previous post.

Of course, Klisi came with its own application icon — one that I designed after I read the relevant section in the GNOME Human Interface Guidelines.

After many iterations changing the colors, the number of elements, the characters to print and the shapes, this is what I was able to come up with.

This seemed adequate for a while, but I was not completely satisfied. I wanted the icon to be a little more lively, a little more playful with the words. Klisi means “call” in Greek. I thought the name was fitting for a Callgrind profile viewer and generator.

The icon was not yet up to the same standard. The first attempt was good, but the output felt a little dry. It could lean a little more into the name. I wanted to find an item that would elegantly accompany the name. The obvious relation would be some kind of phone. Many “call-related” applications use a telephone handset. But this is quite common and not very playful. I instead opted for something a little more retro.

A rotary dial.

I wanted to keep the λ (lambda) and % characters from the original icon — to maintain the spirit of function call profiling. I thought it would be fun to use the lambda as the rotary phone finger stop. The % character would then be placed in the center. Additionally, the numbers inside the finger holes would provide an additional indication of the number crunching nature of the application.

Et voilà!

What do you think? I believe it can receive some more polishing to provide some more depth to all surfaces, but this is the extent of my skills for now and I am satisfied with the result.

This has not discouraged me from writing. My goal is to share projects that I am developing and to express some of my thoughts when I feel like it. I am glad if someone finds the content interesting and I am even happier to engage anyone who sends a comment my way. In any case, I think that the mere act of sitting down and writing your thoughts is beneficial by itself and it is worth doing, even if the audience is not there.

It is true, though, that it feels nice when people accept what you are offering. And two days ago, I finally got my first breakthrough. I shared my last post on Hacker News and it reached the front page.

I admit it was satisfying to see that a lot of people approved of the message and wanted to share their own opinions. I spent the next day or so participating in the discussion and digesting all the new information that was available. One of the main themes of the discussion was user interface accessibility. It is a part of software development that is of great interest and importance and I hope to more systematically approach it in my programming and my writing in the near future.

The whole experience was positive. I do not claim to be a great writer, nor that my post proclaimed some profound truth, but it was gratifying to see that an extended discussion was started because of something I wrote. As a result, I now am a little braver to share my thoughts with the world.

Last week I came across a post on Hacker News that encouraged application developers to stop making terminal user interfaces¹ (a.k.a. TUIs) and instead focus on graphical user interfaces (a.k.a. GUIs). The post reached the HN front page and sparked a lively debate in the comments section.

I think there is merit in both sides of the debate. On one hand, I understand the GUI-positive arguments of the post author. In theory, the capabilities of GUI application frameworks are a superset of the capabilities of their TUI counterparts, so they should be preferred. On the other hand, as a heavy terminal user, I also greatly appreciate all TUIs that allow me to “stay” in the terminal and fulfill all my needs.

But I want to oppose a recurring argument in favor of TUIs that in my opinion does not have a solid foundation². To paraphrase various commenters:

TUIs should be preferred because they are keyboard-driven.

While it’s true that if you randomly pick a GUI and a TUI application, the latter is more probable to be fully keyboard-driven, this does not tip the scale in favor of developing TUIs over GUIs³. What it does is highlight the inadequacies of keyboard navigation in many GUI applications.

There is nothing preventing a GUI from being fully keyboard-driven⁴ just like — or even better than — a TUI. In fact, many GUI framework application guidelines explicitly encourage GUI application developers to provide support for keyboard-driven navigation that covers the whole functionality of the application.

For example, the GNOME Human Interface Guidelines state that just as it should be possible to perform every action with a pointing device, every action should also be possible with the keyboard and that it should be possible to move around and interact with every part of your user interface using the keyboard.

This resonates with me as a user. Being able to intuitively — and predictably — navigate around a GUI application with only my keyboard gives me more incentive to choose it compared to its alternatives.

Knowing that, and when wearing my developer hat, I have to make sure that my applications are keyboard-friendly. For my first ever GUI application, Klisi, I invested some time to implement keyboard shortcuts targeting the whole range of available actions.

Keyboard navigation is not that hard to achieve in most cases and results in an overall better user experience. It is not a matter of feasibility, but a matter of will on the application developer’s part.

The takeaway is simple. Do not compromise on the user experience you provide with your application. Strive to make it as intuitive as possible. To that end, enabling full keyboard navigation should not be ignored.

So far, I was not explicitly using a font-family for this website and instead relied on the default sans-serif font provided by the browser. I thought it is time to change that and present a more unified experience for all readers.

What do you think?

From Ancient Greek κλῆσις (klêsis), related to καλέω (kaléō, “I call”).

After around 3 months of effort, I have finally released the first version of Klisi.

Klisi is the result of a desire to fill a small gap in the available application offering for the GNOME desktop environment and a recent interest in the Clojure programming language.

I wanted to develop a callgrind profile viewer that better integrates with GNOME and can be used as a simplified alternative to KCacheGrind.

Have you heard enough already? Install and try out the application. You can come back for the rest of the write-up and leave a comment with your thoughts.

It all started around one year ago.

After more than 7 years of using i3 as my window manager — through the end of my university years and the start of my professional career — I decided that it was time to embrace Wayland. The obvious choice would be to continue using another tiling window manager. sway would be the prime candidate. But I was also eyeing a more complete solution. Tiling window managers are great, but they require a lot more manual configuration to have a fully functioning system. I am grateful for what I learned in the process, but I was ready to off-load some of that work to someone else.

So, I switched to GNOME. I had always liked the aesthetics of its applications, so having them integrate natively with the whole environment appealed to me. I had also noticed that I could translate my i3 workflow directly to GNOME without any significant changes. I was already using most windows maximized and delegating to tmux for my terminal tiling needs. Scriptability is a little trickier in GNOME than in i3, but GNOME would handle most of my needs now anyway.

This was last November.

Some time after that — in April — I saw on Hacker News the announcement for the Clojure documentary. People seemed excited about it, so I decided to watch it. Going in, I had zero knowledge about Clojure. I did not know anything about Rich Hickey. I did not know anything about the philosophy of the language. I had only read about it in various post titles, but had never gotten down to study it and use it.

The documentary was engaging enough and it piqued my interest. I wanted to try to learn another functional programming language after previous Haskell adventures and this seemed like a nice opportunity. Clojure being a Lisp dialect made the whole premise even more appealing.

I started by reading all beginner-friendly documentation on the official website and then went over Clojure for the Brave and True trying to be as hands-on as possible.

I was ready for the next step. They say one of the best ways to learn and understand a programming language is to use it in a project. And this is exactly what I did. I set out to combine Clojure and GNOME application development.

On the 2nd of May, I made the first commit of Klisi. At the time, I had not yet settled on a name and I was only able to launch an empty GTK window. Today, the application can do a little more. After a long development list, consisting of required features and other ideas that came to my mind while developing, I believe it is good enough to serve other people.

This brings us to today and the first release.

It was time to share my application with the world. I hope that someone will find it useful and decide to make it a part of their development workflow.

In any case, I am very satisfied by the result so far. I have learned a lot and I will continue to do so, while I further explore Clojure, GTK and Flatpak development. There is a long way to go and I believe all the lessons I will learn in the process will be valuable one way or another.

This is it from me for now. Try out Klisi and let me know what you think. I will appreciate any well-meaning feedback.

I have been working on a side project that requires setting an application identifier. From the beginning I knew that I wanted to go with com.ckardaris.<Appname> and not share “naming custody” with GitHub. You don’t really need to own a domain to use it as part of an application identifier, but it makes verification with some platforms possible.

So, I bit the bullet and moved forward with my plans.

ckardaris.com is now live.

The whole process was quite quick. It took a couple hours reading the required documentation and setting everything up.

I registered the domain via porkbun.

I verified the new domain for GitHub Pages to avoid any future surprises and added any additional DNS records needed.

I created a second static website repository on GitHub and pushed the existing repository to it. As the first order of business (i.e. first commit) I made sure to fix any “stale” links pointing to the old ckardaris.github.io domain to now point to the new one.

Finally, I edited the old static site to redirect to the new one automatically and that was all¹.

  <script>
    window.location.href = "https://ckardaris.com" + window.location.pathname + window.location.search + window.location.hash;
  </script>
  <noscript>
    <meta http-equiv="refresh" content="0; url=https://ckardaris.com{{ page.url }}">
  </noscript>

UPDATE: It turns out I did not read the GitHub Pages documentation carefully enough. Creating the second repository and the manual redirects were not needed. By setting the custom domain in the original repository, GitHub handles the redirects from the default domain (i.e. ckardaris.github.io), while properly returning the 301 status code in the process.

This was my first ever domain purchase and I have to say everything went quite smoothly, so I am satisfied.

That’s all for now. Watch this space for my side project update.

See you soon.

One of the limitations of such a system is user authentication. Each user needs to send a password alongside each comment that serves to authenticate the user against their email. This is needed because email spoofing is a thing and identity theft is not a joke; even if the stakes are low in the context of blog comments.

In that previous post, I acknowledged that sending a password in plain text via email is not best practice and I encouraged the usage of encryption. For this purpose, I provided a public PGP key that can be used to encrypt any email and can only be decrypted by me, the owner of the secret key.

Problem

The problem with this suggestion is that, even though it’s technically sound and legitimate, it is not straightforward to set up. Many email clients do not even support PGP encryption and, dare I say, even most technical people do not have it set up by default. For non-technical users, configuring everything properly would certainly be a test of computer literacy.

This is not good enough, and certainly not welcoming or inclusive.

Solution

Shortly after I published the first version of the comment system I came up with a question.

I already have a public PGP key published and ready to be used. Is there a way to encrypt the comment payload on the browser, including the password and all other data?

I wouldn’t be writing this post if the answer was negative.

After a quick web search, I came across openPGP.js, a JavaScript library maintained by the Proton team. The goal of the library is to “bypass the PGP installation requirement in every machine”. Just perfect for my use case.

I quickly set everything up. I downloaded the JavaScript library files at the root of my website and created a couple of helper functions. The first to load the library on-demand to avoid unnecessary network transactions and the second to produce a PGP encrypted message from a plain text string input.

function loadScript(src) {
    return new Promise((resolve, reject) => {
        // Prevent loading the same script twice
        if (document.querySelector(`script[src="${src}"]`)) {
            resolve();
            return;
        }

        const script = document.createElement('script');
        script.src = src;
        script.async = true;
        script.onload = resolve;
        script.onerror = reject;
        document.head.appendChild(script);
    });
}

async function encrypt(message) {
    const publicKeyArmored = `{% include pgp-public-key.txt %}`.trim();

    await loadScript('/openpgp.min.js');

    return await window.openpgp.encrypt({
        message: await openpgp.createMessage({ text: message }),
        encryptionKeys: await window.openpgp.readKey({ armoredKey: publicKeyArmored })
    });
}

It’s simple. And it works.

Note: The comment encryption functionality is not available if JavaScript is disabled on the client.

For example, if you were to write a comment for this post using the comment form and provided the following data:

username: test_user
password: test_password
comment: Test comment.

the email to be sent would be pre-filled with the following body:

Your comment has been encrypted and is ready to be submitted.
...

-----BEGIN PGP MESSAGE-----

wV4Dyk92dA2JWC4SAQdAFgNHlb6Q7nAgovzVgUnB5CTOKBWSlXxSoIOzLUQl
Zm4wBdsLdUROxNS0xcTyja4iq9QUsSazv18DYbmRd2Lix3XoL4zDrQVOPVw6
ZGlkeDhi0qEByCityS59xWSuREVqgS4tpPlZg8Lz5Go6D2nSBu+1iTXw2dy6
L9eL5NZMoFhYUqocGukxBlEcHY6j1U+3Lstvc5dZPl+u7+Zh32uTzTo8CC05
doKNwH5AP9ybHk7nr2vVLdrede6vLCIAwGTK9fVYq2V1udXfSPNCESSeunh1
68qEaAA81mjCbSSfcB/RznpL8/nOLLWDXlXxfMPlYV8/+Q==
=k2VX
-----END PGP MESSAGE-----

Your comment data (username, password, message, etc.) is automatically encrypted without any need for manual intervention.

Conclusion

Based on the above proof of concept, I can say that, even without operating a “proper” backend server, it is still possible to guarantee a reasonable level of security. And you can do so without requiring any complicated setup on the user side.

To my eyes, this is a win for secure communication when email is used as the medium. Do you agree?

Despite the abundance of such spaces, where discussions can happen, I think it is convenient and fitting — especially for blog posts — when the actual post and the readers’ comments live together.

With that in mind, and feeling the urge to hack a little more on my website, during the past weekend I set out to add support for comments in this blog.

Doing so in a static blog poses a big challenge. There is no actual server running that can handle requests and process data. That means that you do not have the necessary infrastructure for user accounts. The readers cannot log in and send their comments and there is no straightforward way to take those comments and automatically post them online.

Another method is therefore needed to receive the comments and provide them as input to the static site generator, in my case jekyll.

One of the most frequently used solutions to this problem is giscus. giscus is utilizing GitHub discussions to store comments for the different blog posts and can be configured to automatically update your website when a new comment is created.

This approach is very appealing, but it has one disadvantage in my opinion. The person who wants to comment needs to have a GitHub account. This can be a blocker for non-technical people.

I wanted to use a different approach and I also wanted to make commenting accessible to as many people as possible. After some thinking I decided to use the most common technology I could think of.

Email.

Almost everyone using the internet has an email address. By basing my comment system on email, I can make it accessible to a wide range of people.

The fact that every email address is unique allows to implement a kind of primitive authentication setup. I am saying primitive, because email is not secure by default, and by extension neither is any system built on top of it.

It goes without saying that this system could never be used in production in security-sensitive environments. That said, crazier things have happened.

Technical overview

At this point, it would be useful to go in a little more detail. If you are not interested in the technical aspects of the comment system implementation you can skip this section and go straight to the end. You will miss all the fun, though.

So, how does it all work?

Requirements

Before implementing the comment system, I drafted some requirements:

1. All comments should be displayed with a visible name³ selected by the commenter and the date they were made.
2. A commenter should be able to change their visible name.
3. A malicious actor should not be able⁴ to assume the identity of a commenter.
4. Sending a comment should be as easy as possible and the comment system should be functional with JavaScript disabled.
5. Comment replies should be supported and presented in a nested tree structure, which should support collapse and expansion of comment sub-trees.

Data

The comment system is based on email, so it is logical that you send a comment by sending an email. Every comment email contains all necessary information, so that the comment can be presented correctly. I decided to send the information in the YAML format, since jekyll is YAML-friendly. Additionally, YAML compared to JSON can be more readable for multi-line data, like comments, so it made it more fitting for this use case.

Every comment email sends in its body the following information.

post:
name:
password:
repliesTo:
comment: |-

Sending passwords in plain text is almost always frowned upon. But I believe this situation deserves some leeway.

• The data transferred is not sensitive and proper care is taken to ensure confidentiality.
• This is an educational project with no hard security requirements.
• A password is good to be used as a measure against sender address spoofing.
• Email can always be hardened by using PGP encryption⁵:

Upon receiving a comment email, some additional information can be obtained: email_address and date.

Implementation

Let’s see how we can satisfy the system requirements with these data.

All comments should be displayed with a visible name selected by the commenter and the date they were made.

For this we use the name and date information from the actual comment email.

A commenter should be able to change their visible name.
A malicious actor should not be able to easily assume the identity of a commenter.

All information needed to generate this website is publicly stored in a GitHub repository. This means that any personal information needs to be properly stored.

For each received comment email a SHA256 message digest (hash) is computed using the email_address and a salt⁶.

To check name availability, all email hashes that are different from the current one are gathered and their linked name is compared to the requested one. If no matches are found the name can be used.

An additional message digest is computed for the authentication of the commenter using the email_address, the password and the salt.

This authentication hash is compared against the authentication hash of one of previous comment emails that share the same email hash⁷.

In the event of any error, the commenter is informed with a response email.

Sending a comment should be as easy as possible and the comment system should be functional with JavaScript disabled.

Commenters with JavaScript enabled can enjoy a streamlined user experience (UX). Clicking on add comment or reply presents them with an HTML form with three input fields: name, password and comment. After filling them and clicking the send button, their preferred email client is launched and the message is pre-filled for them and ready to be sent.

Commenters with JavaScript disabled still get a pre-filled email message, but they have to fill the necessary information, while making sure to not break the formatting of the data.

Writing a comment using the HTML form with JavaScript enabled has two benefits:

1. Browsers are able to save the name and password fields for the commenter and pre-fill them in the future.
2. The password can be hashed in the email body. This does not improve security, but protects against curious eyes.

Comment replies should be supported and presented in a nested tree structure, which should support collapse and expansion of comment sub-trees.

Using the repliesTo field of the comment email⁸, a tree hierarchy of messages is created. This hierarchy is used to sort the comments properly and to create the necessary logic to collapse and expand the respective sub-trees of comments.

Synchronization

We are close to the end, but I have so far failed to mention one basic characteristic of the comment system. And this concerns its responsiveness, or lack thereof.

After receiving a comment email, there is, as of now, no automation set up to process the email and post it on the blog. Posting each comment requires manual intervention. This makes the discussion asynchronous. I think that this is not a big issue and does not look out of place considering the static nature of the website.

Nevertheless, I leave the door open to automation. Interacting with email is scriptable with programs like msmtp and isync. In the unlikely but welcome scenario that the volume of the received comment emails is too large to handle manually, another weekend hacking project could automate the whole process.

Final thoughts

Creating a comment system based on email has been a worthwhile experience. I revisited some long-studied concepts and learned new ones. It was a good exercise in balancing trade-offs which I believe is one of the most important aspects of designing a system.

The final result leaves me satisfied, while also leaving room for improvements in the future.

And after all this work, I can finally say

Let me know what you think in the comments.

Hacking with technology and procrastination may seem unrelated, but I believe that in tandem they paint an accurate picture of how lots of people, myself included, interact with technology in their free time.

When I am referring to hacking, I intend to convey the original meaning. Wikipedia¹ phrases it quite nicely.

The act of engaging in activities (such as programming or other media) in a spirit of playfulness and exploration is termed hacking. However, the defining characteristic of a hacker is not the activities performed themselves (e.g. programming), but how it is done and whether it is exciting and meaningful.

The key words in the above segment are: playfulness, exploration, excitement, meaningfulness. I will come back to them shortly.

I guess most people are at least vaguely familiar with procrastination. Let’s not mention any definition containing the words laziness or carelessness. I prefer to keep it nice and neutral².

The act of procrastinating; putting off or delaying or deferring an action to a later time.

And if you are interested in the actual etymology, it can get a little more fun³.

From Latin prōcrāstinātiō, from prōcrāstinō (“procrastinate”), from prō + crāstinus (“of tomorrow”), from crās (“tomorrow”).

What is techrastination then? I will try to give a definition of my own.

The act of procrastinating by focusing on the technology associated with an activity rather than focusing on the activity itself.

You may have an idea where I am going with this. I am gonna give some examples anyway.

The first one is quite relevant.

It’s when you spend hours upon hours tinkering with your blog, fixing the theme, checking the fonts, trying to perfect the alignment of CSS elements and the margins of your titles and subtitles, yet you are not working towards creating actual blog posts⁴.

It is also when you constantly rework your configuration files and scripts to increase your productivity, when you are not actually working on something that you need to be productive in.

Or when you are more interested in the technologies you are using – programming language, stack, tools – and you like to engage in heated arguments with people about them, instead of just focusing on the actual target at hand, whatever that may be.

It would be safe to assume that we can think of many more similar examples.

I admit I have been guilty of all these to a lesser or greater degree.

But, is guilty the right word? Should there be a negative tone when we are describing such activity? Shouldn’t we always try to be as productive as possible?

Not really.

Let’s go back to the key words of the hacking definition above.

Playfulness. Play is not just for kids. Having some amount of play in our lives is beneficial to our well-being. This matches my experience while hacking. When friends or family ask me how I find satisfaction from my computer projects, I usually respond that it feels like playing.

Exploration. It is said that repetition is the mother of learning, but I believe that exploration is an equally important part of knowledge acquisition. We don’t have to constantly innovate. But we must test the limits of our knowledge to expand it and savor its benefits in the form of personal and professional growth.

Excitement. Who involved with programming and technology in general has not felt immense satisfaction after completing a task? Or even without completing it. Completing the task is not even a requirement. Being in the flow comes with its own set of satisfying emotions. The actual end product does not hold all value. It may not even be that useful, if we were to strictly evaluate it. But this excitement is very important. It encourages further exploration that leads to more play that leads to more excitement.

Meaningfulness. Now we are entering tricky territory. So far I have argued that engaging in techrastinating activities can be useful without the need to find an actual meaning. That statement does not have to be betrayed. The actual meaning does not derive from the usefulness of an activity. It comes from the effect it has on the acting individual. If an activity satisfies us, then it is meaningful.

All this sounds extremely positive. What about the dark side? I would argue that the dark side is not strictly related to technology activities. Any activity can have a negative impact, when it is exercised without measure and it begins to affect other parts of our life (e.g. relationships or health). A general balance should always be maintained.

To sum it all up, hacking with your computer, or actively engaging with technology in general, does not need to have a purpose. The experience itself can be immensely rewarding and there are real benefits to be had, even if not immediately visible to the naked eye.

Whether the word sticks or not, if I had to give one piece of advice, it would be the following.

Do not worry about the outcome. Techrastinate.

It’s been a while since my last post and I did not want to leave 2025 behind without making any.

During the past year I have been gradually migrating my development and configuration file setup to Nix Home Manager (aka home-manager).

This has not been a quick transition, but I am satisfied with the result and I believe it was worth it.

I note the following benefits:

1. It enables me to handle all changes (program versions and configuration files) from a single directory. A single source of truth that can be easily tracked by git.

2. I am a fan of Nix reproducible environments and builds and I considered using home-manager a nice opportunity to familiarize myself with the language.

3. Nix packages enable me to create a predictable development environment across different machines (e.g. home, work, etc.), irrespective of the underlying operating system and the packages that it provides by default.

I finally finished the migration last month, so I thought it is a good idea to share the interesting bits of my current setup. Maybe someone will find it useful.

I don’t know how many posts I will make about it, but let’s get started.

Template files

When sharing a home-manager configuration between multiple machines, a common scenario is to have a file that needs to be slightly different in each machine.

For example, in my vim configuration, I want to configure the number of async workers that clangd will use when launched by the LSP server. In my laptop which has only 4 cores, I want to use 3 of them. In my work computer that has 20, I want to use more (e.g. 16).

How can we utilize home-manager to automate this customization?

Baseline

This post does not provide an introduction to home-manager. Nevertheless, we need to agree on some necessary baseline knowledge.

home-manager requires a configuration file home.nix that typically lies in the $HOME/.config/home-manager directory. In home.nix we can define the files that are generated via home-manager by populating the home.file¹ attribute set.

{
  pkgs,
  lib,
  ...
}:
{
  # Other home-manager configuration options
  ...

  # Files
  home.file = {
    # Key-value file entries
  };
}

Every “key-value” entry in this attribute set corresponds to a file that we want to generate in our $HOME directory.

For example, if we want to generate the $HOME/.bashrc file, we need to add the corresponding entry in the home.file attribute set.

  ...
  home.file = {
    ".bashrc" = {
      # File options
    };
  };
  ...

The file options attribute set fully configures the generation of each file. This includes the contents, setting the executable bit, any actions to perform when the file changes and more.

This post only deals with the contents of the generated files. For this we have two options:

• the source attribute, which is a Nix path to a file whose content will populate the home-manager generated file

  home.file = {
    ".bashrc" = {
      source = /. + "<absolute-path-to-source-file>";
    };
  };
  

  or

• the text attribute, which is a Nix string defining the content of the home-manager generated file

  home.file = {
    ".bashrc" = {
      text = ''
        # This is the content of the $HOME/.bashrc file.
      '';
    };
  };
  

Implementation

We can create a templating layer on top of home-manager and programmatically generate files with parametrizable content.

How do we do that? We can use a template engine like jinja.

For the purposes of my configuration I am using jinja2-cli, because I want to easily invoke jinja from the command line.

Let’s take it step by step.

1. Decouple templating layer from the actual home.file attribute set.

We create an attribute set that mirrors the structure of the home.file. We do not want to deviate too much from the actual “structure” that home-manager expects, so that the configuration and programming logic is simpler.

  files = {
    ".bashrc" = {};
    ".inputrc" = {};
  };

2. Modify each “key-value” file entry using builtins.mapAttrs².

Currently the values of the file entries are empty. We need to populate these attribute sets, so that they are valid home-manager file entries.

As already mentioned, to set the file content, we need to define either the source or the text attribute.

For non-template files the map function is simple:

  makeSimple = builtins.mapAttrs (
    path: options: {
      source = /. + "<absolute-path-to-config-files>/${path}";
    }
  );

You may wonder what this <absolute-path-to-config-files> is.

In my configuration, I have created a directory inside $HOME/.config/home-manager that mirrors the directory structure of the $HOME directory. This allows referring to the home-manager source file and the actual generated location with the same relative path and permits using lib.mapAttrs to modify the initial files attribute set.

For template files we need to provide some more information (i.e. the jinja data). We do so by adding a data attribute.

  files = {
    ".bashrc" = {};
    ".inputrc" = {};
    ".vimrc" = {
        "data" = "<absolute-path-to-json-data-file>";
    };
  };

Now, we define the map function.

  makeTemplates = builtins.mapAttrs (
    path: options: {
      text = template {
        src = /. + "<absolute-path-to-config-files>/${path}";
        data = /. + "${options.data}";
      };
    }
  );

We can see that we rely on the output of a helper function: template. This function in its simplest form³ takes two paths as arguments:

1. src is the path to the template file.
2. data is the path to a file containing data in JSON format.

The return value of this function has to be a Nix string that is then used as the value of the text attribute.

We define the template function as follows:

  template =
    { src, data }:
    let
      out = pkgs.runCommand "" { buildInputs = [ pkgs.jinja2-cli ]; } ''
        # If jinja2 fails (e.g. missing keys), just use the input file unchanged.
        jinja2 --format=json ${src} <<< "$(< ${data})" -o $out 2>/dev/null || cp ${src} $out
      '';
    in
    builtins.readFile out;

How does the template function work?

The function uses pkgs.runCommand⁴ to create a Nix derivation. In our use case we only want to create one single file that we can then read from.

• We run jinja2 on the src file using the data in json format.
• We write the output to the $out file (note: the $out variable is used internally by Nix and points to the generated derivation file).
  If anything fails during the jinja2 call we copy the original template file content to the output file directly.
• Finally, we read the output file and return its content as a Nix string.

3. Merge simple and template files in one attribute set.

We are almost done. We need to map non-template files with the makeSimple function and template files with the makeTemplate function. The differentiating factor is the presence of the data attribute and we use that to create a filter.

  simpleFile = (lib.filterAttrs (path: options: !options ? data) files);
  templateFiles = (lib.filterAttrs (path: options: options ? data) files);

  result = makeSimple simpleFiles // makeTemplates templateFiles;

4. Assign the resulting attribute set to home.file.

{
  pkgs,
  lib,
  ...
}:
let
  files = ...;

  template = ...;

  makeSimple = ...;
  makeTemplate = ...;

  simpleFiles = ...;
  templateFiles = ...;

  result = ...;
in
{
  # Other home-manager configuration options.
  ...

  # Files
  home.file = result;
}

That’s it. We have successfully configured home-manager to generate files from templates.

In practice

At the beginning of this post I mentioned how one my use cases for template files is specifying a different number of async workers for clangd in my LSP configuration in vim.

How does this look like based on the described setup?

$HOME/.config/home-manager/home.nix:

  ...
  files = {
    ...
    ".vim/variables.vim" = {
      data = "/home/<username>/.local/share/home-mananger/data.json";
    };
    ...
  };
  ...

$HOME/.config/home-manager/files/.vim/variables.vim:

autocmd User LspSetup call LspAddServer([
    \   #{
    \       name: 'clangd',
    \       filetype: ['c', 'cpp'],
    \       path: 'clangd',
    \       args: ['--clang-tidy', '-j', {{ data.nproc * 80 // 100 }}]
    \  },
    ...

$HOME/.local/share/home-manager/data.json:

{
  "data": {
    "nproc": 4
  }
}

It is that simple⁵.

Extensions

Nix enables extensive configuration, so we could certainly improve on the described setup if we needed to. Here are some ideas:

• The template function in its current form requires two file paths as parameters. We may desire some more flexibility.
  For example, we may want to pass the template file as a Nix string. Or we may want to pass the data in a different format (e.g. as a Nix attribute set, a Nix string, etc.).
  We should be able to easily achieve that with a few small changes in the template function in order to correctly parse and transform parameters of different types.

• In a previous iteration of my configuration I was generating multiple files from a single template file by iterating over a JSON array.
  I now have no use for it, so I have not included it in this post, but it is certainly doable with a few changes.