I have been working hard on getting komorebi for Mac ready for the initial public release in January 2026, and a large part of that work has focused on improving the documentation and creating a new unified docs website for both komorebi for Windows and komorebi for Mac.

I am all-in on generating documentation from rustdoc, for both komorebi for Windows and komorebi for Mac.

I’m so deep in on this that not only am I generating configuration API documentation in Markdown, I am also generating Nix module options for komorebi for Mac users to be able to define their configuration in Nix with completions, documentation, and automatic JSONSchema validation of the generated JSON file.

In order to enable the generation of better documentation from rustdoc, I have been making a lot of updates to my rustdoc comments across both codebases.

The thing that sucks about having two similar codebases for two different platforms which implement a common configuration API is keeping documentation in sync.

(I think the future of komorebi is probably going to be a single repo for both komorebi for Windows and komorebi for Mac, but that’s a whole separate article...)

To do this I have spent way too much time switching inputs on my display to go from my Mac Mini to my PC and back. Although this is made significantly easier by having a cross-platform tiling window manager with all the same semantics and key bindings on both platforms, it still sucks and takes my out of my flow state.

The reason for having to do this display input switching dance is that cross-compilation of Rust projects that depend on the Windows MSVC toolchain is a pain; I can’t (or rather, couldn’t - past tense) just make an equivalent change in the komorebi for Windows repo checked out on the Mac Mini and run cargo clippy to make sure everything is okay, or cargo run to inspect the output of one of the documentation generation commands.

I reached my breaking point with this workflow today and decided to tackle it head on: by adding a flake.nix to komorebi for Windows which allows me to both build the entire project and run all of those cargo with the Windows MSVC toolchain on both NixOS and macOS.

I took the flake.nix from komorebi for Mac as a template and went diving into projects like cargo-xwin and the discussions in crane, and eventually got something working.

You can check it out here: LGUG2Z/komorebi/flake.nix@6e36b816699ef3f1c7ea3e9ab70f78dca9fe6008

One of my favorite components to set up in a flake is treefmt-nix, and integrating all of the formatters and linters it provides for different languages into nix flake check.

So once I got the flake.nix for komorebi for Windows working, I ran nix fmt followed by nix flake check, and I was very happy to see everything "just work" - as evidenced by all of the TOML files in the repo suddenly being formatted correctly (I had not been running taplo on Windows).

The initial lift to get this working is quite big (hopefully a little less now that you can copy and paste from my example), but I can already feel that this is going to have a huge payoff on the medium-to-long term as I work on both komorebi for Windows and komorebi for Mac concurrently and make refactors which will extract common duplicated code out of both codebases.

Even if you are not going cross-platform with whatever you’re building (yet, or ever), being able to leverage flake checks, dev shells and excellent tooling like treefmt-nix in WSL can have a significant positive impact on the ergonomic experience of a long-lived project.

If you have any questions or comments you can reach out to me on Bluesky and Mastodon.

If you’re interested in what I read to analyze problems like this, you can subscribe to my Software Development RSS feed.

If you’d like to watch me writing code while explaining what I’m doing, you can also subscribe to my YouTube channel.

If you would like early access to komorebi for Mac, you can sponsor me on GitHub.