docs/site: write "The lay of the land" chapter

README.adoc

@@ -54,113 +54,6 @@ To install it, run the `nixos-install --flake {canonical_flake_url}#ni`.
 (Please see the respective appropriate host README for more information.)
 
 
-[#channels-support]
-=== Channels support
-
-While this primarily uses flakes as its main form of distribution, this project does keep some use cases for traditional channels.
-It's not guaranteed to be good as using it <<using-my-config-with-flakes>> but it's an option.
-
-The entry point is found at link:./default.nix[`./default.nix`].
-However, you have to keep some limitations and guidelines in mind.
-
-* It exports an attribute based from the link:https://github.com/nix-community/NUR/[NUR template].
-+
---
-Several exports includes...
-
-* My custom library at `lib`.
-* Custom NixOS modules at `modules`.
-* Custom home-manager modules at `hmModules`.
-* An overlay of my custom packages at `overlays.foo-dogsquared-pkgs`.
-* My packages as the rest of the top-level attributes from the attrset.
---
-
-* Keep in mind it doesn't export the NixOS hosts and home-manager user configurations.
-It would be pointless as it is duplicating effort plus I __really like managing my NixOS config more with the flakes way__ compared to setting up channels.
-It has a lot of advantages such as the ease of provisioning and updating your setups along with its dependencies, enforcing certain values in a certain attribute that can be seen in the revised Nix CLI, and nicer interface overall.
-While possible with channels, this is just better experience overall and I have no interest in maintaining setups in both ways.
-
-
-[#whats-in-my-flake]
-=== What's in my flake?
-
-You can see the full details with `nix flake show`.
-As a helpful summary, here's what my flake should contain sorting from the most interesting and helpful outputs to the most boring and unnecessary.
-
-* `packages` contains link:./pkgs[my custom packages] and some of usual images of several hosts which is nice for easily fetching custom images.
-
-* `overlays` contains the overlay for extending nixpkgs with my packages.
-If you want to use my packages alongside the nixpkgs attribute then this is what you're looking for.
-
-* `homeModules` are where my link:./modules/home-manager[custom home-manager modules] to be exported.
-footnote:[This is more useful than my NixOS modules.]
-
-* `nixosModules` are composed from NixOS modules defined in link:./modules/nixos[`./modules/nixos`].
-It can be used as additional modules for your own NixOS config in case you want to use mine for whatever reason.
-There are some niceties in there.
-+
---
-A few examples include:
-
-* A NixOS module for Pop launcher plugins and scripts.
-* Several service modules for archiving with link:https://github.com/yt-dlp/yt-dlp[yt-dlp], link:https://github.com/mikf/gallery-dl/[gallery-dl], and link:https://archivebox.io/[ArchiveBox].
-* My themes which contain full desktop environments which is nice for quickly initializing a NixOS configuration.
---
-
-* `devShells` from link:./shells/[my custom environments].
-Similar to `homeConfigurations`, you can easily use it outside of NixOS.
-
-* `homeConfigurations` contains my various link:https://github.com/nix-community/home-manager[home-manager] configurations from link:./users/home-manager/[`./users/home-manager/`].
-The neat thing about it is you can easily install it in a non-NixOS Linux distro.
-
-* `deploy` are nodes to be deployed by link:https://github.com/serokell/deploy-rs[deploy-rs].
-It's nice and currently not all of the nodes are publicly committed which is less useful but it'll be someday.
-
-* `nixosConfigurations` which is where you can install my various NixOS configurations directly (e.g., `nixos-install --flake {canonical_flake_url}#HOST`).
-This mainly uses the link:./hosts/[hosts configuration].
-
-* `templates` which contains my templates.
-Though, these are just templates mostly for my own purposes so it is not as useful as the other outputs.
-
-* `hydraJobs` contains link:https://github.com/NixOS/hydra[Hydra] build jobs where it is primarily used for my test Hydra instance.
-
-* `lib` is defined from link:./lib/[my custom library].
-It mainly assumes it is to be included in nixpkgs standard library (i.e., `import ./lib { lib = inputs.nixpkgs.lib; }`).
-It's another unnecessary export but it's there.
-
-* `formatter` is the preferred formatter to be used for my Nix files.
-Nothing special here.
-
-* `checks` contains checks for several outputs and are mainly for internal purposes.
-There's no use for anyone else, really. :(
-
-
-=== What should not be here?
-
-Despite being a NixOS configuration, this is not meant to be fully reproducible by anyone.
-There are still some things that would need to be privately held as indicated by the following list.
-
-- Associated private keys: GPG, SSH, age, you name it.
-They are used with a secret management tool (see <<secrets-management>> for more information) to encrypt the more sensitive parts of the system such as credentials and environment files.
-
-- Disposable hosts configurations.
-They will typically just make a messier mess than the current situation.
-
-Though the unreproducible part is only like 10% of the whole configuration, it can be successfully deployed by anyone.
-Keep in mind, it comes with a few restrictions due to the lack of the appropriate credentials.
-
-- Certain tasks will not start.
-Most of the project tasks found in this repo requires the associated private key with the task.
-An example would be the link:./modules/nixos/tasks/backup-archive[Borg backup task] where it needs several files and credentials locked from the secrets management tool.
-
-- Certain components will be missing.
-Most notably, the associated SSH key for the hosts.
-You won't be able to connect to the host if you don't have the private key.
-
-- Not to mention not all modules listed committed here are up-to-date.
-Though this only applies to non-critical services like the link:./modules/nixos/tasks/multimedia-archive[multimedia archiving service].
-
-
 === The remote repo
 
 For a complete overkill, we use a CI to further the configuration abomination.

docs/content/en-US/lay-of-the-land/channels-support/index.adoc

@@ -0,0 +1,28 @@
+---
+title: Channels support
+---
+= Channels support
+
+While this primarily uses flakes as its main form of distribution, this project does keep some use cases for traditional channels.
+It's not guaranteed to be good as xref:../../using-parts-of-my-configuration/index.adoc#using-my-config-with-flakes[Using my config with flakes] but it's an option.
+Anyhow, there is a section for using my configuration with channels as shown in xref:../../using-parts-of-my-configuration/index.adoc#using-my-config-with-channels[Using my config with channels].
+
+The entry point is found at github:{github-repo}[`./default.nix`, path=./default.nix, rev=master].
+However, you have to keep some limitations and guidelines in mind.
+
+* It exports an attribute based from the github:nix-community/NUR/[NUR template].
++
+--
+Several exports includes...
+
+* My custom library at `lib`.
+* Custom NixOS modules at `modules`.
+* Custom home-manager modules at `hmModules`.
+* An overlay of my custom packages at `overlays.foo-dogsquared-pkgs`.
+* My packages as the rest of the top-level attributes from the attrset.
+--
+
+* Keep in mind it doesn't export the NixOS hosts and home-manager user configurations.
+It would be pointless as it is duplicating effort plus **I really like managing my NixOS config more with the flakes way** compared to setting up channels.
+It has a lot of advantages such as the ease of provisioning and updating your setups along with its dependencies, enforcing certain values in a certain attribute that can be seen in the revised Nix CLI, and nicer interface overall.
+While possible with channels, this is just better experience overall and I have no interest in maintaining setups in both ways.

docs/content/en-US/lay-of-the-land/prerequisites/index.adoc

@@ -0,0 +1,37 @@
+---
+title: Prerequisites
+---
+= Prerequisites
+
+Before you get into dive into this configuration, let's establish a few things first.
+In order to make use of this system in the first place, you need the following components.
+
+- A NixOS installer image with flakes enabled.
+An example would be the unstable versions from link:https://releases.nixos.org/?prefix=nixos/unstable/[NixOS project release page].
+As an additional option, you can also use link:https://github.com/foo-dogsquared/nixos-config/releases/tag/latest[my personalized NixOS installers] which is primarily intended for me configs.
+
+- A flash drive or any storage device that will boot the installer image up for installation.
+
+- A computer with disabled secure boot.
+Because unfortunately, that's the state of most Linux distros right now. footnote:[But things change hopefully with github:nix-community/lanzaboote[Lanzaboote project] into usable and stable state.]
+
+This primarily uses Nix flakes so you can have a preview of what's available in my config.
+
+[source, shell, subs=attributes]
+----
+nix flake show {canonical-flake-url}
+----
+
+All you have to do is to flash the installer image into the flash drive and boot with the drive (with the disabled secure boot).
+Then run the following command in the shell as root.
+
+[source, shell, subs=attributes]
+----
+nixos-install --flake {canonical-flake-url}#INSTALLABLE
+----
+
+Despite being a NixOS system, it isn't entirely reproducible to the point of installing this config will work out-of-the-box.
+It has some things needed in the first place to work like my external backup setup where it needs my SSH private keys to work in the first place.
+You can see more details from xref:../what-should-not-be-here/index.adoc[What should not be here?].
+Nonetheless, the parts is it isn't reproducible is only about 10% of this config.
+Everything else is fine and dandy and can be deployed successfully (but not used as intended).

docs/content/en-US/lay-of-the-land/project-structure/index.adoc

@@ -0,0 +1,62 @@
+---
+title: Project structure
+---
+= Project structure
+
+Last and foremost, we have the project directory —  the environment you'll be living in for the next year, tinkering your Nix configs.
+.
+It is required to be familiar with the workspace, after all.
+My configuration takes a lot of cues from link:{devos_link}[devos] (which is unfortunately is a lot to take if you're just beginning to grok Nix as a whole).
+
+My NixOS config should look like the following:
+
+[source, tree]
+----
+nixos-config
+├── hosts/
+├── lib/
+├── modules/
+├── pkgs/
+├── scripts/
+├── secrets/
+├── shells/
+├── templates/
+├── users/
+├── default.nix
+├── flake.lock
+├── flake.nix
+├── images.toml
+└── README.adoc
+----
+
+One of the more notable files here when first start looking is the link:./images.toml[`./images.toml`] file where it contains a description of the images.
+For more details, see <<declarative-host-management>>.
+
+Most of the said folders are related to a flake output attribute, see <<whats-in-my-flake>> for more details.
+
+* link:./hosts/[`./hosts/`] contain machine-specific configuration.
+This usually configures like the hardware setup, timezone, and users.
+Host configurations are also exported in the flakes in `outputs.nixosConfigurations`.
+
+* link:./modules/[`./modules/`] contain my custom modules including NixOS and home-manager modules.
+For more information, see the link:./modules/README.adoc[related documentation].
+
+* link:./pkgs/[`./pkgs/`] contains my custom packages.
+It is exported in the flakes at `outputs.packages` compiled through various systems.
+
+* link:./scripts/[`./scripts/`] contains various scripts for various purposes.
+Should be self-explanatory.
+
+* link:./secrets/[`./secrets/`] contains my cluster-wide secrets managed with link:https://github.com/mozilla/sops[sops] and link:https://github.com/Mic92/sops-nix[sops-nix].
+Take note, each component (e.g., hosts, modules, users) could have their own specific secrets.
+
+* link:./shells/[`./shells/`] contains my development shells for interacting with the usual type of projects.
+Setting this up can bring benefits outside of NixOS (unless you're interacting with projects with any OpenGL-related stuff).
+footnote:[Since packages brought from Nix shells can only work with the store, a container might be better at some situations.]
+
+* link:./templates/[`./templates/`] contains my custom templates handy for quickly initializing for various types of projects.
+
+* link:./users/[`./users/`] contains my link:https://github.com/nix-community/home-manager[home-manager] configurations.
+It is exported in the flakes at `outputs.homeConfigurations`.
+For more information, see the link:./users/README.adoc[related documentation].
+

docs/content/en-US/lay-of-the-land/what-should-not-be-here/index.adoc

@@ -0,0 +1,27 @@
+---
+title: What should not be here?
+---
+= What should not be here?
+
+Despite being a NixOS configuration, this is not meant to be fully reproducible by anyone.
+There are still some things that would need to be privately held as indicated by the following list.
+
+- Associated private keys: GPG, SSH, age, you name it.
+They are used with a secret management tool (see xref:../../project-specific-setup/secrets-management/index.adoc[Secret management] for more information) to encrypt the more sensitive parts of the system such as credentials and environment files.
+
+- Disposable hosts configurations.
+They will typically just make a messier mess than the current situation.
+
+Though the unreproducible part is only like 10% of the whole configuration, it can be successfully deployed by anyone.
+Keep in mind, it comes with a few restrictions due to the lack of the appropriate credentials.
+
+- Certain tasks will not start.
+Most of the project tasks found in this repo requires the associated private key with the task.
+An example would be the github:{github-repo}[Borg backup task, path=./modules/nixos/tasks/backup-archive, rev=master] where it needs several files and credentials locked from the secrets management tool.
+
+- Certain components will be missing.
+Most notably, the associated SSH key for the hosts.
+You won't be able to connect to the host if you don't have the private key.
+
+- Not to mention not all modules listed committed here are up-to-date.
+Though this only applies to non-critical services like the github:{github-repo}[multimedia archiving service, path=./modules/nixos/tasks/multimedia-archive, rev=master].

docs/content/en-US/lay-of-the-land/whats-in-my-flake/index.adoc

@@ -0,0 +1,54 @@
+---
+title: What's in my flake?
+---
+= What's in my flake?
+
+You can see the full details with `nix flake show`.
+As a helpful summary, here's what my flake should contain sorting from the most interesting and helpful outputs to the most boring and unnecessary.
+
+* `packages` contains github:{github-repo}[my custom packages, path=./pkgs, rev=master] and some of usual images of several hosts which is nice for easily fetching custom images.
+
+* `overlays` contains the overlay for extending nixpkgs with my packages.
+If you want to use my packages alongside the nixpkgs attribute then this is what you're looking for.
+
+* `homeModules` are where my github:{github-repo}[custom home-manager modules, path=./modules/home-manager, rev=master] to be exported.
+footnote:[This is more useful than my NixOS modules.]
+
+* `nixosModules` are composed from NixOS modules defined in github:{github-repo}[`./modules/nixos`, path=./modules/nixos, rev=master].
+It can be used as additional modules for your own NixOS config in case you want to use mine for whatever reason.
+There are some niceties in there.
++
+--
+A few examples include:
+
+* A NixOS module for Pop launcher plugins and scripts.
+* Several service modules for archiving with github:yt-dlp/yt-dlp[opts=repo], github:mikf/gallery-dl[opts=repo], and link:https://archivebox.io/[ArchiveBox].
+* My themes which contain full desktop environments which is nice for quickly initializing a NixOS configuration.
+--
+
+* `devShells` from github:{github-repo}[my custom environments, path=./shells, rev=master].
+Similar to `homeConfigurations`, you can easily use it outside of NixOS.
+
+* `homeConfigurations` contains my various github:nix-community/home-manager[opts=repo] configurations from link:{github-repo}[`./users/home-manager/`, path=./users/home-manager/, rev=master].
+The neat thing about it is you can easily install it in a non-NixOS Linux distro.
+
+* `deploy` are nodes to be deployed by github:serokell/deploy-rs[opts=repo].
+It's nice and currently not all of the nodes are publicly committed which is less useful but it'll be someday.
+
+* `nixosConfigurations` which is where you can install my various NixOS configurations directly (e.g., `nixos-install --flake {canonical-flake-url}#HOST`).
+This mainly uses the github:{github-repo}[hosts configuration, path=./hosts, rev=master].
+
+* `templates` which contains my templates.
+Though, these are just templates mostly for my own purposes so it is not as useful as the other outputs.
+
+* `hydraJobs` contains github:NixOS/hydra[Hydra] build jobs where it is primarily used for my test Hydra instance.
+
+* `lib` is defined from github:{github-repo}[my custom library, path=./lib, rev=master].
+It mainly assumes it is to be included in nixpkgs standard library (i.e., `import ./lib { lib = inputs.nixpkgs.lib; }`).
+It's another unnecessary export but it's there.
+
+* `formatter` is the preferred formatter to be used for my Nix files.
+Nothing special here.
+
+* `checks` contains checks for several outputs and are mainly for internal purposes.
+There's no use for anyone else, really. :(

docs/content/en-US/menu.adoc

@@ -1,10 +1,10 @@
 * link:{{< relref "./introduction/" >}}[Introduction]
 
 * The lay of the land
-** link:./lay-of-the-land/prerequisites/[Prerequisites]
+** link:{{< relref "./lay-of-the-land/prerequisites/" >}}[Prerequisites]
-** link:./lay-of-the-land/channels-support[Channels support]
+** link:{{< relref "./lay-of-the-land/whats-in-my-flake/" >}}[What's in my flake?]
-** link:./lay-of-the-land/whats-in-my-flake[What's in my flake?]
+** link:{{< relref "./lay-of-the-land/channels-support/" >}}[Channels support]
-** link:./lay-of-the-land/what-should-not-be-here[What should not be here?]
+** link:{{< relref "./lay-of-the-land/what-should-not-be-here/" >}}[What should not be here?]
 
 * Project-specific setup
 ** link:./project-specific-setup/declarative-host-management[Declarative host management]