1. Introduction
+1. Introduction
This repository contains a literate NixOS configuration built using Emacs Org mode. The primary source of truth is this document itself, which embeds configuration blocks that are tangled into individual files. These generated files are evaluated as a NixOS flake, resulting in an immutable, reproducible system configuration.
@@ -399,8 +405,8 @@ Customization is designed to occur primarily through modular .conf files, allowi Before proceeding with installation, it is strongly recommended to read this documentation carefully. Understanding the structure and design philosophy will help ensure a smooth setup and provide the necessary context for extending the system effectively.1.1. What do you get?
+1.1. What do you get?
This repository delivers a reproducible foundation built on NixOS, Home-Manager, and Flakes. It assumes a clean NixOS installation as a starting point, preferably minimal or headless, onto which the configuration is applied. @@ -415,22 +421,38 @@ Core packages are installed as part of the base configuration. Additional softwa
2. what you don't get
-1.2. What you do not get
+-This is by no means a complete or bug-free environment. Certain components — such as the XDG portals — may still behave unpredictably or require additional tweaking. The goal is to provide a solid starting point for those who want to learn how to build an iterative system from a minimal foundation. Consider it a base to extend, refine, and improve over time. This project is very much a work in progress. +This repository does not provide a fully polished, bug-free desktop system with every default preconfigured and validated across all hardware combinations. It is a structured foundation, not a turnkey end-user distribution. +
+ ++You should not expect graphical configuration tools, wizard-driven setup screens, or extensive GUI-based system management. Configuration is performed declaratively through Nix modules and supporting configuration files. Familiarity with reading logs, adjusting modules, and rebuilding the system is assumed. +
+ ++Certain subsystems may require manual tuning depending on hardware, desktop environment, or portal backend selection. For example, XDG desktop portals can exhibit inconsistent behavior across compositors and applications, particularly in Wayland-based environments. File chooser dialogs, screen sharing, or drag-and-drop functionality may require additional configuration or troubleshooting. +
+ ++This project favors clarity, reproducibility, and modular structure over convenience abstractions. As a result, some integration details are intentionally left explicit rather than hidden behind automated defaults. +
+ ++In short, this repository provides a coherent and extensible base, not a finished consumer product. It is a work in progress.
2.1. What Is a Literate System in the Context of NixOS?
-2. What Is a Literate System in the Context of NixOS?
+A literate system combines documentation and implementation into a single, coherent source. In this repository, that source is:
-README.org@@ -439,7 +461,6 @@ In this repository, that source is:
Everything originates from this file:
-- Architectural explanations
- Design decisions @@ -459,118 +480,74 @@ Org-mode turns that narrative into both executable configuration and readable do The README is not describing the system. The README is the system. - -
-— -
2.2. Two Types of Code Blocks
-2.1. Two Types of Code Blocks
+This literate system uses two different kinds of source blocks.
1. Documentation Blocks -
- -These blocks exist purely for documentation purposes. They generate visible code blocks in the exported documentation, but they do not create files. -
- -Example:
- -<tekst> ++#+begin_src bash :tangle no +<tekst> +#+end_src-
These are used to show commands, examples, or explanatory snippets in the generated documentation. -
- -They are never tangled into the filesystem.
--— -
-
2. File-Generating Blocks
+These blocks generate real .nix files and insert the same code into the documentation.
+Example:
-These blocks generate real `.nix` files and insert the same code into the documentation. -
- --Example structure: -
-2.3. install_packages.nix
-+
+** install_packages.nix <tekst> - - --<tekst> +#+begin_src nix :tangle configuration/apps/install_packages.nix :noweb tangle :mkdirp yes +<nixos code> +#+end_src-Explanation:
-
-
-
- The headline `=installpackages.nix=` becomes a documentation chapter. -
- The paragraph `<tekst>` explains what the module does. -
-The source block generates the file: -
- --configuration/apps/installpackages.nix -
-
+- The headline
install_packages.nixbecomes a documentation chapter.
+ - The paragraph
<tekst>explains what the module does.
+ <nixos code>is exactly what will be written into the .nix moduleconfiguration/apps/install_packages.nix- The same source block is rendered as a code block in the documentation.
This means:
-- The explanation and the implementation live side-by-side.
- The documentation cannot drift away from the code. -
- The generated `.nix` file is always derived from the canonical explanation. +
- The generated .nix file is always derived from the canonical explanation.
-— -
2.4. The Two Core Commands
-2.2. The Two Core Commands
+There are exactly two commands that matter.
-1. Generate all `.nix` files +1. Generate all .nix files
-emacs README.org --batch -f org-babel-tangle@@ -579,22 +556,16 @@ There are exactly two commands that matter.
This command:
--
-
- Regenerates `./configuration` -
- Regenerates `./home` +
- Regenerates ./configuration +
- Regenerates ./home
- Overwrites previously generated modules
- Ensures the system matches the README
-— -
-2. Generate documentation
-emacs --batch -l org -l ox-html README.org -f org-html-export-to-html --kill@@ -602,16 +573,8 @@ This command:
This command exports the same README into HTML documentation. -
- --— -
- -In practice you usually combine them:
-emacs README.org --batch -f org-babel-tangle && emacs --batch -l org -l ox-html README.org -f org-html-export-to-html --kill@@ -622,28 +585,22 @@ First the system is generated. Then the documentation is generated. Both come from the same source. - -
-— -
2.5. Editing Generated Files
-2.3. Editing Generated Files
+The directories:
--
-
- `./configuration` -
- `./home` +
- ./configuration +
- ./home
are fully generated by:
-emacs README.org --batch -f org-babel-tangle@@ -651,37 +608,23 @@ are fully generated by:
Editing these files directly is allowed only temporarily, for experimentation or testing. -
- --Structural or permanent changes must always be implemented in the corresponding section inside `README.org`. -
- --If you change a file in `./configuration` or `./home` without updating the README, your changes will disappear on the next tangle. -
- -+Structural or permanent changes must always be implemented in the corresponding section inside README.org. +If you change a file in ./configuration or ./home without updating the README, your changes will disappear on the next tangle. Generated directories are output, not source.
- --— -
2.6. Recommended Workflow
-2.4. Recommended Workflow
+This workflow allows safe experimentation while preserving literate structure.
--
-
- Change any existing file in `./assets`, `./home` or `./configuration` +
- Change any existing file in ./assets, ./home or ./configuration
- Commit your experimental change
- Test the configuration -
- If satisfied, migrate the change into `README.org` +
- If satisfied, migrate the change into README.org
- Regenerate system and documentation
- Commit again
- Test again @@ -690,11 +633,9 @@ This workflow allows safe experimentation while preserving literate structure.
Commands:
-git add . git commit -m "experiment: local change" - sudo nixos-rebuild test --flake .#your_hostname
After confirming the change:
-emacs README.org --batch -f org-babel-tangle && emacs --batch -l org -l ox-html README.org -f org-html-export-to-html --kill - git add . git commit -m "literate: structural update" - sudo nixos-rebuild test --flake .#your_hostname
-If you are confident about your changes, you may skip steps 1–3 and edit `README.org` directly. -
- --— +If you are confident about your changes, you may skip steps 1–3 and edit README.org directly.
2.7. Folder Structure Explained
-2.5. Folder Structure Explained
+The repository separates generated system code from non-generated supporting files.
- --**./assets** -
- +2.5.1. ./assets
+Contains non-generated assisting files such as:
-- Icons
- Themes
- Static configuration files
These files are safe to edit directly.
- --— -
- --*./assets/configuration** -
- +2.5.2. ./assets/conf
+Contains non-generated assisting configuration files that influence several aspects of builds. -
- -Users are expected to modify these when needed.
- +2.5.3. ./configuration
+-— -
- --*./configuration** -
- --Fully (re)generated by `README.org`. +Fully (re)generated by README.org.
Contains:
-- All NixOS modules
- Service definitions
- System-level configuration
This directory is output.
- --— -
- --*./hardware** -
- --Contains non-generated `hardware.nix` files detailing hardware-specific details. -
- +2.5.4. ./hardware
++Contains non-generated hardware.nix files detailing hardware-specific details. This directory will likely be deprecated in the future.
- +2.5.5. ./home
+-— -
- --*./home** -
- --Fully (re)generated by `README.org`. +Fully (re)generated by README.org.
Contains:
-- All Home-Manager modules
- User-level configuration
- Shell and desktop configuration
-This directory is generated output. -
- --— -
- --*./machines** -
- +2.5.6. ./machines
+Contains one folder per machine you want to configure. -
- -Each machine folder contains non-generated files detailing specifics for that machine:
-- Host-specific overrides
- Hardware references @@ -856,19 +750,15 @@ Each machine folder contains non-generated files detailing specifics for that ma
These determine how shared modules apply to each system.
- --— -
2.8. Final Principle
-2.6. Final Principle
+A literate NixOS system guarantees:
-- Single source of truth
- No divergence between documentation and configuration @@ -879,16 +769,13 @@ A literate NixOS system guarantees:
You are not maintaining configuration files. -
- -You are maintaining a structured narrative that builds an operating system.
2.9. Base packages
-2.7. Base packages
+The baseline package set is defined explicitly within the repository to ensure reproducibility:
@@ -960,9 +847,9 @@ The baseline package set is defined explicitly within the repository to ensure r2.10. Additional packages
-2.8. Additional packages
+Additional software can be installed by extending the dedicated configuration files that define system and Flatpak packages:
@@ -989,7 +876,7 @@ Available Flatpak identifiers can be discovered using:-or by browsing: https://flathub.org/.(manually) +or by browsing: https://flathub.org/.
@@ -1001,37 +888,13 @@ This separation maintains clarity between system-level packages and user-facing
2.11. What you do not get
--This repository does not provide a fully polished, bug-free desktop system with every default preconfigured and validated across all hardware combinations. It is a structured foundation, not a turnkey end-user distribution. -
- --You should not expect graphical configuration tools, wizard-driven setup screens, or extensive GUI-based system management. Configuration is performed declaratively through Nix modules and supporting configuration files. Familiarity with reading logs, adjusting modules, and rebuilding the system is assumed. -
- --Certain subsystems may require manual tuning depending on hardware, desktop environment, or portal backend selection. For example, XDG desktop portals can exhibit inconsistent behavior across compositors and applications, particularly in Wayland-based environments. File chooser dialogs, screen sharing, or drag-and-drop functionality may require additional configuration or troubleshooting. -
- --This project favors clarity, reproducibility, and modular structure over convenience abstractions. As a result, some integration details are intentionally left explicit rather than hidden behind automated defaults. -
- --In short, this repository provides a coherent and extensible base, not a finished consumer product. It is a work in progress. -
3. Setting up your system manually
+3. Setting up your system manually
3.1. Pre-requisites to build this setup
+3.1. Pre-requisites to build this setup
- a NIXOS system installed with a user with sudo rights. @@ -1041,8 +904,8 @@ In short, this repository provides a coherent and extensible base, not a finishe
3.2. Setup when Emacs not (yet) available
+3.2. Setup when Emacs not (yet) available
- Copy the folder henrovnix to your machine @@ -1111,8 +974,8 @@ Run the build command to set up the system for the first time
4. Testing and generating builds
+4. Testing and generating builds
At this stage, you should have a functional and reproducible system that can be edited, rebuilt, and extended according to your needs. The foundational structure is now in place, and further customization can occur incrementally through the modular configuration files. @@ -1175,46 +1038,46 @@ Other important files:
5. flake.lock for pinning input versions.
+5. flake.lock for pinning input versions.
6. assets/* for non-Nix-managed artifacts such as images and wallpapers.
+6. assets/* for non-Nix-managed artifacts such as images and wallpapers.
Generated outputs should not be edited directly. A CI workflow can tangle and commit generated outputs when they differ.
6.1. Emacs + Org + Tangle
+6.1. Emacs + Org + Tangle
7. [Emacs](https://www.gnu.org/software/emacs/][Emacs) is used as the editor and execution environment for this literate configuration.
+7. [Emacs](https://www.gnu.org/software/emacs/][Emacs) is used as the editor and execution environment for this literate configuration.
8. [Org](https://orgmode.org/][Org) mode provides the document structure and the source block execution model used here.
+8. [Org](https://orgmode.org/][Org) mode provides the document structure and the source block execution model used here.
9. Tangling exports source blocks from this Org document into the corresponding configuration files.
+9. Tangling exports source blocks from this Org document into the corresponding configuration files.
- References of the form
<<code-id>>are noweb placeholders that are expanded from other blocks during tangling.
9.1. Nix & NixOS
+9.1. Nix & NixOS
10. [Nix](https://nix.dev/][Nix) is used to define packages, environments, and configuration as pure expressions.
+10. [Nix](https://nix.dev/][Nix) is used to define packages, environments, and configuration as pure expressions.
11. [NixOS](https://nixos.org/][NixOS) evaluates Nix expressions into a complete system configuration that can be applied by rebuild operations.
+11. [NixOS](https://nixos.org/][NixOS) evaluates Nix expressions into a complete system configuration that can be applied by rebuild operations.
11.1. Repository layout and folder conventions
+11.1. Repository layout and folder conventions
<p> @@ -1227,8 +1090,8 @@ Generated outputs should not be edited directly. A CI workflow can tangle and co
11.2. Shared domain folders
+11.2. Shared domain folders
<ul> @@ -1242,8 +1105,8 @@ Generated outputs should not be edited directly. A CI workflow can tangle and co
11.3. Full tree (including unchanged parts)
+11.3. Full tree (including unchanged parts)
The tree below shows the full repository layout, with the standardized internal structure applied only inside @@ -1359,8 +1222,8 @@ The tree below shows the full repository layout, with the standardized internal
11.4. Notes
+11.4. Notes
<ul> @@ -1393,8 +1256,8 @@ This prevents unwanted and surprise updates when rebuilding without changing the
12. TLDR App List
+12. TLDR App List
13. Configuration Variables
+13. Configuration Variables
I have a bunch of constant strings that I would rather put in a file. Thats what user.nix is.
@@ -1491,8 +1354,8 @@ The values are imported at the beginning and are available to almost all the fun
14. Flake Inputs
+14. Flake Inputs
The inputs for my system's configuration are very simple @@ -1533,8 +1396,8 @@ Sometimes pinned to a specific commit because unstable broke something and the f
15. Flake Output
+15. Flake Output
Now that the inputs are ready, the outputs define what the system will actually look like. I also define the machines that this configuration specifies early on. Finally, I iterate over the machines list and pull files from /.machines/${name} subdirectory. This allows me to have configuration that has machine specific configuration limited to those files while also keeping a modular reusable base.
@@ -1542,7 +1405,7 @@ We also add a devshell that makes editing this repository easier in emacs.
outputs = inputs@{
+outputs = inputs@{
nixpkgs,
home-manager,
emacs-overlay,
@@ -1603,7 +1466,7 @@ Overlays are a special nix way to override existing packages within a repository
-({ ... }: {
+({ ... }: {
nixpkgs.overlays = [ emacs-overlay.overlays.default ];
})
@@ -1613,7 +1476,7 @@ Overlays are a special nix way to override existing packages within a repository
Then the machine specific configuration, in this case, just "machine1".
-./machines/${machine}/configuration.nix
+./machines/${machine}/configuration.nix
@@ -1623,7 +1486,7 @@ This can be initialized and managed on its own but I'd rather use the nixo
-home-manager.nixosModules.home-manager
+home-manager.nixosModules.home-manager
{
home-manager.useGlobalPkgs = true;
home-manager.useUserPackages = true;
@@ -1666,8 +1529,8 @@ Finally I pull in the machine specific home configuration. Along with the overri
-
-15.1. Envrc + Direnv
+
+15.1. Envrc + Direnv
Editing this file will be much nicer if we have the dev environment configured.
@@ -1688,14 +1551,14 @@ fi
-
-16. Machines
+
+16. Machines
The individual machines subdirectory is configured as follows :-
-+--machine
++--machine
| +--configuration.nix
| +--home.nix
| +--hardware-configuration.nix
@@ -1716,12 +1579,12 @@ This imported object (or function result) is just trivially merged into a common
We can take a look at that the common hardware options I have for all my machines.
-
-16.0.1. Other Utils
+
+16.0.1. Other Utils
-
-17. Hardware
+
+17. Hardware
I'll let the code comments explain the file here.
@@ -1770,8 +1633,8 @@ I'll let the code comments explain the file here.
-
-18. Configuration
+
+18. Configuration
This section describes the main system configuration for the computers that I have. Nix will look for a default.nix file if you give it a path to a folder to import. And default.nix looks as follows :-
@@ -1814,16 +1677,16 @@ This section describes the main system configuration for the computers that I ha
-
-18.1. Apps section
+
+18.1. Apps section
This section describes a way of installing packages, either through nixpkgs orr flatpak. What apps to instal is decided in the files ./assets/conf/apps/packages.conf and flatpaks.conf
-
-18.2. install_packages.nix
+
+18.2. install_packages.nix
{ config, lib, pkgs, flakeRoot, inputs, ... }:
@@ -1883,8 +1746,8 @@ in
-
-18.3. install_flatpaks.nix
+
+18.3. install_flatpaks.nix
{ config, pkgs, lib, flakeRoot, ... }:
@@ -1995,8 +1858,8 @@ in
-
-18.4. Nix Settings
+
+18.4. Nix Settings
These are global nix settings that configure the settings for the actual tool.
@@ -2045,8 +1908,8 @@ These are global nix settings that configure the settings for the actual tool.
-
-18.5. Boot
+
+18.5. Boot
This file has most of the settings the control how the computer boots up.
@@ -2084,16 +1947,16 @@ This file has most of the settings the control how the computer boots up.
-
-18.6. Login
+
+18.6. Login
Here we control what the login screen would look like. In configuration/default.nix you can choose whether to use tuigreet (very minimalistic) or LightDM (nicer, themeable)
-
-18.7. Tuigreet
+
+18.7. Tuigreet
Doesn't match the rest of the aesthetic of the system (with hyprland), but I like its simplicity.
@@ -2118,8 +1981,8 @@ Doesn't match the rest of the aesthetic of the system (with hyprland), but I lik
-
-18.8. LightDM
+
+18.8. LightDM
{ config, pkgs, lib, ... }:
@@ -2266,8 +2129,8 @@ in
-
-18.9. Terminal (default system)
+
+18.9. Terminal (default system)
This is the initial system level configuration for the terminal that I use on this machine. Its just zsh.
@@ -2286,8 +2149,8 @@ This is the initial system level configuration for the terminal that I use on th
-
-18.10. Files
+
+18.10. Files
I use Thunar as the file explorer. Also setup a few plugins for Thunar in this config.
@@ -2328,8 +2191,8 @@ Along with that, a few other utilities like zip and enabling services to automou
-
-18.11. Locale
+
+18.11. Locale
I live in Netherlands and would like all my locale and timezone settings to match. Except my default locale.
@@ -2363,8 +2226,8 @@ in
-
-18.12. Networking
+
+18.12. Networking
Not much to see here. I want networking to be enabled. I want firewall as well.
@@ -2395,8 +2258,8 @@ Not much to see here. I want networking to be enabled. I want firewall as well.
-
-18.13. Hyprland
+
+18.13. Hyprland
This is a big one because the DE needs so much configuration. This section mostly installs Hyprland.
@@ -2467,8 +2330,8 @@ The configuration is done in the home manager section.
-
-18.14. Services
+
+18.14. Services
These are some of the services that I enable at the system level. Explanation in the comments.
@@ -2501,8 +2364,8 @@ These are some of the services that I enable at the system level. Explanation in
-
-18.15. Audio
+
+18.15. Audio
{ config, pkgs, lib, ... }:
@@ -2580,11 +2443,11 @@ These are some of the services that I enable at the system level. Explanation in
-
-18.16. Miscellaneous Packages and Programs
+
+18.16. Miscellaneous Packages and Programs
-environment.systemPackages = with pkgs; [
+environment.systemPackages = with pkgs; [
wget # fetch utility
curl # more fetch utility
binutils # executable utilities, like ld
@@ -2612,7 +2475,7 @@ programs.gdk-pixbuf.modulePackages = [ pkgs.librsvg ];
-programs = {
+programs = {
nix-ld.enable = true; # helps with linking troubles with dynamic libraries
appimage.enable = true; # allow appimage installations
dconf.enable = true; # to save user settings
@@ -2628,14 +2491,14 @@ programs.gdk-pixbuf.modulePackages = [ pkgs.librsvg ];
-
-18.17. Fonts
+
+18.17. Fonts
Nothing much to see here. I love Aporetic, and I use it everywhere.
-fonts.packages = with pkgs; [
+fonts.packages = with pkgs; [
aporetic
nerd-fonts.iosevka
];
@@ -2643,14 +2506,14 @@ Nothing much to see here. I love
-18.18. User Config
+
+18.18. User Config
This creates the user profile that I login with. Initially created during install.
-users.users.${user.username} = {
+users.users.${user.username} = {
isNormalUser = true;
description = "<defaultUser>";
extraGroups = [
@@ -2665,8 +2528,8 @@ This creates the user profile that I login with. Initially created during instal
-
-19. Home
+
+19. Home
I use home-manager to manage my user level dotfiles and configurations.
@@ -2674,8 +2537,8 @@ Most of the "theme" of the system is decided here.
I also use it to install programs that are okay with being installed at the user level instead of the system.
-
-19.1. default.nix
+
+19.1. default.nix
This module will import all necessities.
@@ -2711,8 +2574,8 @@ This module will import all necessities.
-
-19.2. Wallpaper
+
+19.2. Wallpaper
wallpaper.nix installs wpaperd and deploys your wallpaper files from the repo (./assets/conf/desktop/wallpaper/pictures/) into ~/conf/desktop/wallpaper/pictures. It also deploys the default wallpaper configuration from assets/conf/desktop/wallpaper/wallpaper.conf into ~/conf/desktop/wallpaper/wallpaper.conf, which is the file you can edit as a user override.
@@ -2766,11 +2629,11 @@ in
-
-19.3. Waybar
+
+19.3. Waybar
-
+
@@ -2807,8 +2670,8 @@ in
-
-19.4. Lock Screen
+
+19.4. Lock Screen
The lock screen configured using hyprlock.
@@ -2830,8 +2693,8 @@ in
-
-19.5. Idle Screen
+
+19.5. Idle Screen
<henro: needs instruction>
@@ -2849,8 +2712,8 @@ in
-
-19.6. Hyprshell
+
+19.6. Hyprshell
For nice task-starting and -switching
@@ -2890,8 +2753,8 @@ in
-
-19.7. Hyprland
+
+19.7. Hyprland
This configures the desktop environment along with the peripherals. The comments should explain whats happening.
@@ -2941,8 +2804,8 @@ in
-
-19.8. Walker
+
+19.8. Walker
This is how I launch applications. It is bound to Win+Space in the ./asstes/conf/desktop/hypr/bindings.conf.
@@ -3043,8 +2906,8 @@ in
-
-19.9. Theme
+
+19.9. Theme
I use the Catppuccin almost everywhere. The nix module integrates almost automatically everywhere (except gtk).
@@ -3077,8 +2940,8 @@ You'll notice the color values in multiple places outside this as well.
-
-19.10. Default-apps
+
+19.10. Default-apps
This is where you can set defaults
@@ -3097,8 +2960,8 @@ This is where you can set defaults
-
-19.11. Hyperexpo
+
+19.11. Hyperexpo
hyprexpo gets installed and configured
@@ -3138,8 +3001,8 @@ hyprexpo gets installed and configured
-
-19.12. Alacritty
+
+19.12. Alacritty
Alacritty gets installed and configured
@@ -3161,8 +3024,8 @@ in
-
-19.13. Dev Tools
+
+19.13. Dev Tools
All the miscellaneous dev tools on this computer.
@@ -3221,8 +3084,8 @@ All the miscellaneous dev tools on this computer.
-
-19.14. Kitty
+
+19.14. Kitty
Kitty gets installed and configured
@@ -3246,8 +3109,8 @@ in
-
-19.15. Shells
+
+19.15. Shells
The aliases mentioned in ./assets/conf/dev/terminal/shells.conf will be added to enabled shells
@@ -3470,8 +3333,8 @@ EOF
-
-19.16. Zsh
+
+19.16. Zsh
Zsh gets installed and configured
@@ -3514,8 +3377,8 @@ in
-
-19.17. Starship
+
+19.17. Starship
The configuration mentioned in ./assets/conf/dev/terminal/starship.toml will be added to enabled shells
@@ -3547,18 +3410,18 @@ in
-
-19.18. Other Settings
+
+19.18. Other Settings
Some repeated info from the configuration.
-
-19.18.1. Home User
+
+19.18.1. Home User
-home.username = "${user.username}";
+home.username = "${user.username}";
home.homeDirectory = pkgs.lib.mkDefault "/home/${user.username}";
home.stateVersion = user.stateVersion;
@@ -3567,8 +3430,8 @@ home.stateVersion = user.stateVersion;
-
-20. Emacs
+
+20. Emacs
I practically live inside emacs. The configuration for it is a mix between init.el and the nix configuration.
@@ -3647,8 +3510,8 @@ Comments describe the emacs package and what it does.
-
-20.1. Early Initialization
+
+20.1. Early Initialization
There are some emacs settings that can be configured before the gui shows up.
@@ -3753,8 +3616,8 @@ These are listed here.
-
-20.2. Initialization
+
+20.2. Initialization
Now starts the main emacs configuration.
@@ -4166,22 +4029,22 @@ ting a file within such a
-
-21. Machines
+
+21. Machines
Only a few more things left. Specifically the machine level extra settings.
-
-21.1. Traveldroid
+
+21.1. Traveldroid
The configuration for the laptop does not change much. Most changes are because the hardware is different.
-
-21.1.1. System Level
+
+21.1.1. System Level
Nothing specific for the laptop.
@@ -4199,8 +4062,8 @@ Nothing specific for the laptop.
-
-21.1.2. Hardware
+
+21.1.2. Hardware
This is the most different. Mostly taken from hardware-configuration.nix setup at first install.
@@ -4249,8 +4112,8 @@ hardware.cpu.intel.updateMicrocode = lib.mkDefault config.hardware.enableRedistr
-
-21.1.3. Home
+
+21.1.3. Home
This is mostly about configuring the monitor. And laptop specific utilities.
@@ -4277,18 +4140,18 @@ This is mostly about configuring the monitor. And laptop specific utilities.
-
-22. README Utils
+
+22. README Utils
-
-22.0.1. Headers
+
+22.0.1. Headers
This script adds a DO NOT MODIFY header to all the generated nix files.
-(progn
+(progn
(defun add-tangle-headers ()
(message "running in %s" (buffer-file-name))
(when (string= (file-name-extension (buffer-file-name)) "nix")
@@ -4305,7 +4168,7 @@ This script adds a DO NOT MODIFY header to all the generated nix fi
diff --git a/henrovnix/README.org b/henrovnix/README.org
index a0517d2f9..6c873e0c7 100755
--- a/henrovnix/README.org
+++ b/henrovnix/README.org
@@ -28,10 +28,7 @@ gf#+OPTIONS: toc:nil broken-links:t
* Introduction
#+HTML:
-
#+HTML_HEAD:
-
-
This repository contains a literate NixOS configuration built using Emacs Org mode. The primary source of truth is *this document itself*, which embeds configuration blocks that are tangled into individual files. These generated files are evaluated as a NixOS flake, resulting in an immutable, reproducible system configuration.
This work is based on the foundational efforts of Sandeep Nambiar (https://github.com/gamedolphin).
@@ -44,28 +41,31 @@ Customization is designed to occur primarily through modular .conf files, allowi
Before proceeding with installation, it is strongly recommended to read this documentation carefully. Understanding the structure and design philosophy will help ensure a smooth setup and provide the necessary context for extending the system effectively.
** What do you get?
-
This repository delivers a reproducible foundation built on NixOS, Home-Manager, and Flakes. It assumes a clean NixOS installation as a starting point, preferably minimal or headless, onto which the configuration is applied.
The system provides a predefined baseline configuration that installs and enables the essential components required for a functional and extensible environment. Rather than prescribing a complete desktop experience, it establishes the structural framework upon which such an environment can be composed.
Core packages are installed as part of the base configuration. Additional software can be incorporated in a controlled and modular manner by extending configuration files.
-* what you don't get
+** What you do not get
+This repository does not provide a fully polished, bug-free desktop system with every default preconfigured and validated across all hardware combinations. It is a structured foundation, not a turnkey end-user distribution.
-This is by no means a complete or bug-free environment. Certain components — such as the XDG portals — may still behave unpredictably or require additional tweaking. The goal is to provide a solid starting point for those who want to learn how to build an iterative system from a minimal foundation. Consider it a base to extend, refine, and improve over time. This project is very much a work in progress.
+You should not expect graphical configuration tools, wizard-driven setup screens, or extensive GUI-based system management. Configuration is performed declaratively through Nix modules and supporting configuration files. Familiarity with reading logs, adjusting modules, and rebuilding the system is assumed.
-** What Is a Literate System in the Context of NixOS?
+Certain subsystems may require manual tuning depending on hardware, desktop environment, or portal backend selection. For example, XDG desktop portals can exhibit inconsistent behavior across compositors and applications, particularly in Wayland-based environments. File chooser dialogs, screen sharing, or drag-and-drop functionality may require additional configuration or troubleshooting.
+This project favors clarity, reproducibility, and modular structure over convenience abstractions. As a result, some integration details are intentionally left explicit rather than hidden behind automated defaults.
+
+In short, this repository provides a coherent and extensible base, not a finished consumer product. It is a work in progress.
+
+* What Is a Literate System in the Context of NixOS?
A literate system combines documentation and implementation into a single, coherent source.
In this repository, that source is:
-
#+begin_src bash :tangle no block
README.org
#+end_src
Everything originates from this file:
-
- Architectural explanations
- Design decisions
- NixOS modules
@@ -80,92 +80,65 @@ Org-mode turns that narrative into both executable configuration and readable do
The README is not describing the system.
The README *is* the system.
----
-
** Two Types of Code Blocks
-
This literate system uses two different kinds of source blocks.
**1. Documentation Blocks**
-
These blocks exist purely for documentation purposes.
They generate visible code blocks in the exported documentation, but they do not create files.
-
Example:
-
-#+begin_src bash :tangle no
-
-#+end_src
+#+begin_example
+ #+begin_src bash :tangle no
+
+ #+end_src
+#+end_example
These are used to show commands, examples, or explanatory snippets in the generated documentation.
-
They are never tangled into the filesystem.
----
-
**2. File-Generating Blocks**
-
-These blocks generate real `.nix` files and insert the same code into the documentation.
-
-Example structure:
-
-** =install_packages.nix=
-
-
-
-#+begin_src nix :tangle configuration/apps/install_packages.nix :noweb tangle :mkdirp yes
-
-#+end_src
+These blocks generate real =.nix= files and insert the same code into the documentation.
+Example:
+#+begin_example
+ ** install_packages.nix
+
+ #+begin_src nix :tangle configuration/apps/install_packages.nix :noweb tangle :mkdirp yes
+
+ #+end_src
+#+end_example
Explanation:
-
-- The headline `=install_packages.nix=` becomes a documentation chapter.
-- The paragraph `` explains what the module does.
-- The source block generates the file:
-
- configuration/apps/install_packages.nix
-
+- The headline =install_packages.nix= becomes a documentation chapter.
+- The paragraph == explains what the module does.
+- == is exactly what will be written into the .nix module =configuration/apps/install_packages.nix=
- The same source block is rendered as a code block in the documentation.
This means:
-
- The explanation and the implementation live side-by-side.
- The documentation cannot drift away from the code.
-- The generated `.nix` file is always derived from the canonical explanation.
-
----
+- The generated .nix file is always derived from the canonical explanation.
** The Two Core Commands
-
There are exactly two commands that matter.
-**1. Generate all `.nix` files**
-
+**1. Generate all .nix files**
#+begin_src bash :tangle no block
emacs README.org --batch -f org-babel-tangle
#+end_src
This command:
-
-- Regenerates `./configuration`
-- Regenerates `./home`
+- Regenerates ./configuration
+- Regenerates ./home
- Overwrites previously generated modules
- Ensures the system matches the README
----
-
**2. Generate documentation**
-
#+begin_src bash :tangle no block
emacs --batch -l org -l ox-html README.org -f org-html-export-to-html --kill
#+end_src
This command exports the same README into HTML documentation.
-
----
-
In practice you usually combine them:
-
#+begin_src bash :tangle no block
emacs README.org --batch -f org-babel-tangle && emacs --batch -l org -l ox-html README.org -f org-html-export-to-html --kill
#+end_src
@@ -174,145 +147,94 @@ First the system is generated.
Then the documentation is generated.
Both come from the same source.
----
-
** Editing Generated Files
-
The directories:
-
-- `./configuration`
-- `./home`
+- ./configuration
+- ./home
are fully generated by:
-
#+begin_src bash :tangle no block
emacs README.org --batch -f org-babel-tangle
#+end_src
Editing these files directly is allowed only temporarily, for experimentation or testing.
-
-Structural or permanent changes must always be implemented in the corresponding section inside `README.org`.
-
-If you change a file in `./configuration` or `./home` without updating the README, your changes will disappear on the next tangle.
-
+Structural or permanent changes must always be implemented in the corresponding section inside README.org.
+If you change a file in ./configuration or ./home without updating the README, your changes will disappear on the next tangle.
Generated directories are output, not source.
----
-
** Recommended Workflow
-
This workflow allows safe experimentation while preserving literate structure.
-
-1. Change any existing file in `./assets`, `./home` or `./configuration`
+1. Change any existing file in ./assets, ./home or ./configuration
2. Commit your experimental change
3. Test the configuration
-4. If satisfied, migrate the change into `README.org`
+4. If satisfied, migrate the change into README.org
5. Regenerate system and documentation
6. Commit again
7. Test again
Commands:
-
#+begin_src bash :tangle no block
git add .
git commit -m "experiment: local change"
-
sudo nixos-rebuild test --flake .#your_hostname
#+end_src
After confirming the change:
-
#+begin_src bash :tangle no block
emacs README.org --batch -f org-babel-tangle && emacs --batch -l org -l ox-html README.org -f org-html-export-to-html --kill
-
git add .
git commit -m "literate: structural update"
-
sudo nixos-rebuild test --flake .#your_hostname
#+end_src
-If you are confident about your changes, you may skip steps 1–3 and edit `README.org` directly.
-
----
+If you are confident about your changes, you may skip steps 1–3 and edit README.org directly.
** Folder Structure Explained
-
The repository separates generated system code from non-generated supporting files.
-****./assets**
-
+*** ./assets
Contains non-generated assisting files such as:
-
- Icons
- Themes
- Static configuration files
-
These files are safe to edit directly.
----
-
-***./assets/configuration**
-
+*** ./assets/conf
Contains non-generated assisting configuration files that influence several aspects of builds.
-
Users are expected to modify these when needed.
----
-
-***./configuration**
-
-Fully (re)generated by `README.org`.
+*** ./configuration
+Fully (re)generated by README.org.
Contains:
-
- All NixOS modules
- Service definitions
- System-level configuration
-
This directory is output.
----
-
-***./hardware**
-
-Contains non-generated `hardware.nix` files detailing hardware-specific details.
-
+*** ./hardware
+Contains non-generated hardware.nix files detailing hardware-specific details.
This directory will likely be deprecated in the future.
----
-
-***./home**
-
-Fully (re)generated by `README.org`.
+*** ./home
+Fully (re)generated by README.org.
Contains:
-
- All Home-Manager modules
- User-level configuration
- Shell and desktop configuration
-This directory is generated output.
-
----
-
-***./machines**
-
+*** ./machines
Contains one folder per machine you want to configure.
-
Each machine folder contains non-generated files detailing specifics for that machine:
-
- Host-specific overrides
- Hardware references
- Host definitions
These determine how shared modules apply to each system.
----
-
** Final Principle
-
A literate NixOS system guarantees:
-
- Single source of truth
- No divergence between documentation and configuration
- Reproducible system builds
@@ -320,7 +242,6 @@ A literate NixOS system guarantees:
- Controlled experimentation
You are not maintaining configuration files.
-
You are maintaining a structured narrative that builds an operating system.
** Base packages
@@ -409,25 +330,12 @@ Available Flatpak identifiers can be discovered using:
flatpak search
#+end_src
-or by browsing: https://flathub.org/.(manually)
+or by browsing: https://flathub.org/.
The behavior and integration of Flatpak installation within the system are defined in =install_flatpaks.nix=, which reads the corresponding configuration files and ensures declarative installation.
This separation maintains clarity between system-level packages and user-facing Flatpak applications while preserving reproducibility and modular structure.
-** What you do not get
-
-This repository does not provide a fully polished, bug-free desktop system with every default preconfigured and validated across all hardware combinations. It is a structured foundation, not a turnkey end-user distribution.
-
-You should not expect graphical configuration tools, wizard-driven setup screens, or extensive GUI-based system management. Configuration is performed declaratively through Nix modules and supporting configuration files. Familiarity with reading logs, adjusting modules, and rebuilding the system is assumed.
-
-Certain subsystems may require manual tuning depending on hardware, desktop environment, or portal backend selection. For example, XDG desktop portals can exhibit inconsistent behavior across compositors and applications, particularly in Wayland-based environments. File chooser dialogs, screen sharing, or drag-and-drop functionality may require additional configuration or troubleshooting.
-
-This project favors clarity, reproducibility, and modular structure over convenience abstractions. As a result, some integration details are intentionally left explicit rather than hidden behind automated defaults.
-
-In short, this repository provides a coherent and extensible base, not a finished consumer product. It is a work in progress.
-
-
* Setting up your system manually
** Pre-requisites to build this setup
#+begin_src bash :tangle no block