docs: document hardware generation flags

Author: Mic92

docs/quickstart.md

@@ -47,32 +47,7 @@ into a new directory. This example is tailored for a virtual machine setup
 similar to one on [Hetzner Cloud](https://www.hetzner.com/cloud), so you might
 need to adapt it for your setup.
 
-**Hardware-Specific Configuration**: If you're not using a virtual machine,
-you'll need to generate a custom hardware configuration with
-`nixos-generate-config`.
-
-If you already have a flake, you can use it by adding
-[disko configuration](https://github.com/nix-community/disko?tab=readme-ov-file#how-to-use-disko)
-to it.
-
-#### Get `nixos-generate-config` onto the Target Machine
-
-1. **Option 1**: If NixOS is not installed, boot into an installer without first
-   installing NixOS.
-2. **Option 2**: Use the kexec tarball method, as described
-   [here](https://github.com/nix-community/nixos-images#kexec-tarballs).
-
-#### Generate Configuration
-
-Run the following command on the target machine:
-
-```bash
-nixos-generate-config --no-filesystems --dir /mnt/etc/nixos
-```
-
-This creates the necessary configuration files under `/mnt/etc/nixos/`, which
-you can then customize as needed and copy them to your local machine in order to
-include them in your flake.
+If you already have a flake, you can use it by adding [disko configuration](https://github.com/nix-community/disko?tab=readme-ov-file#how-to-use-disko) to it.
 
 ### 3. Configure your SSH key
 
@@ -128,6 +103,10 @@ and add `--env-password` to the `nixos-anywhere` command.
 
 ### 7. (Optional) Test your NixOS and Disko configuration
 
+Skip this step and continue with Step 8, if you don't have a hardware configuration
+(hardware-configuration.nix or facter.json) generated yet or make sure you don't
+import non-existing hardware-configuration.nix or facter.json during running the vm test.
+
 The following command will automatically test your nixos configuration and run
 disko inside a virtual machine, where
 
@@ -142,7 +121,64 @@ disko inside a virtual machine, where
 nix run github:nix-community/nixos-anywhere -- --flake <path to configuration>#<configuration name> --vm-test
 ```
 
-### 8. Run it
+### 8. Prepare hardware configuration
+
+If you are not using a virtual machine, it is recommended to let `nixos-anywhere` generate a hardware configuration during installation.
+This ensures that, for example, drivers needed to detect disks are set up correctly.
+
+To allow `nixos-anywhere` to import its generated configuration into your NixOS configuration, you need to add an import for the hardware configuration upfront.
+
+Here is an example:
+
+```diff
+ nixosConfigurations.generic = nixpkgs.lib.nixosSystem {
+   system = "x86_64-linux";
+   modules = [
+     disko.nixosModules.disko
+     ./configuration.nix
++    ./hardware-configuration.nix
+   ];
+ };
+```
+
+When running `nixos-anywhere`, this file is then generated by adding the following flags:
+`--generate-hardware-config nixos-generate-config ./hardware-configuration.nix`
+to your `nixos-anywhere` command. The second flag, `./hardware-configuration.nix`, is the path where `nixos-generate-config` will write the configuration.
+Adjust it to the path where the `hardware-configuration.nix` for this machine should be stored.
+
+#### 8.1 nixos-facter
+
+Instead of `nixos-generate-config`, you can also use the new [nixos-facter](https://github.com/numtide/nixos-facter) command.
+`nixos-facter` is currently experimental but provides more comprehensive hardware reports and more advanced hardware configuration modules.
+
+In your flake inputs, add `nixos-facter-modules`:
+
+```diff
+ {
++ inputs.nixos-facter-modules.url = "github:numtide/nixos-facter-modules";
+ }
+```
+
+Then, import the module into your configuration and set `facter.json` to the path where you will later import it:
+
+```diff
+ nixosConfigurations.generic-nixos-facter = nixpkgs.lib.nixosSystem {
+   system = "x86_64-linux";
+   modules = [
+     disko.nixosModules.disko
+     ./configuration.nix
++    nixos-facter-modules.nixosModules.facter
++    { config.facter.reportPath = ./facter.json }
+   ];
+ };
+```
+
+To let `nixos-anywhere` generate a configuration for `nixos-facter`, add the following flags:
+`--generate-hardware-config nixos-facter ./facter.json`.
+The second flag, `./facter.json`, is the path where the `nixos-generate-config` will write the configuration.
+Adjust it to the path where the `facter.json` for this machine should be stored.
+
+### 9. Run it
 
 You can now run **nixos-anywhere** from the command line as shown below, where:
 
@@ -167,6 +203,20 @@ named `/home/mydir/test` and the IP address of your target machine is
 nix run github:nix-community/nixos-anywhere -- --flake /home/mydir/test#hetzner-cloud root@37.27.18.135
 ```
 
+If you also need to generate hardware configuration amend flags for nixos-generate-config:
+
+```
+nix run --generate-hardware-config nixos-generate-config ./hardware-configuration.nix github:nix-community/nixos-anywhere -- --flake <path to configuration>#<configuration name> root@<ip address>
+```
+
+Or these flags if you are using nixos-facter instead:
+
+```
+nix run --generate-hardware-config nixos-facter ./facter.json github:nix-community/nixos-anywhere -- --flake <path to configuration>#<configuration name> root@<ip address>
+```
+
+Adjust the location of `./hardware-configuration.nix` and `./facter.json` accordingly.
+
 **nixos-anywhere** will then run, showing various output messages at each stage.
 It may take some time to complete, depending on Internet speeds. It should
 finish by showing the messages below before returning to the command prompt.