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 #

This is the working set behind the screenshot, not a full package inventory. The deeper pages document the behavior worth remembering.

Area	Current choice
System	NixOS or Fedora, flakes, Home Manager, and host-specific modules.
Desktop	GNOME or Noctalia with Umbriel.
Term	Ghostty, usually running Zellij.
Shell	Zsh with Starship.
Editor	Neovim & Zed (vim-mode)
Notes	Neovim & 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
NixOS: flakes, hosts, and SOPS
Programs: Dotfiles
Other Distros: how to recreate the working setup without NixOS
Tools: small command-line notes and scripts

Guidelines #

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