Welcome

Hi! Welcome to the documentation site for my (Owais) dotfiles & flakes. More specifically, my NixOS workstation, dotfiles, editor setup, terminal workflow, and the parts that can be reused outside NixOS.

The repo is written for two audiences:

me, when I need to rebuild a machine or remember why something is configured a certain way
anyone trying to copy pieces of the setup on NixOS, Fedora, Ubuntu, Debian, or another Linux distro

Summary

What I use

The working set, not a full package inventory. The program pages cover the settings and failure modes I think are worth remembering.

Area	Current choice
System	NixOS or Fedora, flakes, Home Manager, and host-specific modules
Desktop	GNOME, or Umbriel with Noctalia
Terminal	Ghostty, usually running Zellij
Shell	Zsh with Starship
Editor	Neovim and Zed in vim mode
Notes	Neovim and Obsidian
Reading	Zathura with a compact dark interface
Networking	Tailscale for stable hostnames and private services

Entrypoints

Guides: common commands, checks, secrets, and migration notes
Nix concepts: flakes, modules, and the language itself
NixOS: hosts, rebuilds, and SOPS
Programs: per-application config and dotfiles
Other distros: how to recreate the setup without NixOS
Tools: small command-line notes and scripts

Where to start

If you are on NixOS, start with NixOS, then read Hosts and Secrets.

If the underlying Nix ideas are unclear, read Nix concepts.

If you are not on NixOS, start with Other distros. Then use the program pages for the tools you want to copy.

If you are editing this repo, read Development and Writing docs.

Structure

conf/
├── machines/      # host-specific NixOS config
├── modules/       # app config and focused modules
├── secrets/       # SOPS-encrypted secrets
└── shared.nix     # shared NixOS and Home Manager modules

docs/src/          # This book's source (mdBook)
shells/            # project shell helpers