Update NixOS docs to target flake-based installation

documentation/mkdocs.yml

@@ -7,6 +7,8 @@ theme:
   palette:
     primary: 'blue grey'
     accent: 'red'
+  features:
+    - content.code.annotate
 repo_name: 'jmacdonald/amp'
 repo_url: 'https://github.com/jmacdonald/amp'
 nav:
@@ -20,6 +22,8 @@ extra:
     accent: 'red'
 markdown_extensions:
   - admonition
+  - attr_list
+  - md_in_html
   - pymdownx.highlight
   - pymdownx.superfences
   - pymdownx.smartsymbols

documentation/pages/installation.md

@@ -10,15 +10,98 @@ project!
 
 ## NixOS
 
-```bash
-# Nix3-based build
-nix build
+If you're using flakes, you can add Amp as an input to your configuration and
+track the main branch. Here's what that looks like in a simplified example,
+with Amp available in plain NixOS and Home Manager configurations:
+
+```nix title="flake.nix" hl_lines="12-15 22 32 45"
+{
+  description = "System config";
+
+  inputs = {
+    nixpkgs.url = "github:nixos/nixpkgs/nixos-24.05";
+
+    home-manager = {
+      url = "github:nix-community/home-manager/release-24.05";
+      inputs.nixpkgs.follows = "nixpkgs";
+    };
+
+    amp = {
+      url = "github:jmacdonald/amp/main";
+      inputs.nixpkgs.follows = "nixpkgs";
+    };
+  };
+
+  outputs = {
+    self,
+    nixpkgs,
+    home-manager,
+    amp,
+    ...
+  } @ inputs: let
+    inherit (self) outputs;
+  in {
+    nixosConfigurations = {
+      desktop = nixpkgs.lib.nixosSystem {
+        system = "x86_64-linux";
+
+        specialArgs = {
+          inherit inputs outputs amp; # (1)!
+        };
+
+        # Main configuration
+        modules = [ ./nixos ];
+      };
+    };
+
+    homeConfigurations = {
+      "jmacdonald@desktop" = home-manager.lib.homeManagerConfiguration {
+        pkgs = nixpkgs.legacyPackages.x86_64-linux;
+
+        extraSpecialArgs = {
+          inherit inputs outputs amp; # (2)!
+          host = "desktop";
+        };
+
+        # Main configuration
+        modules = [ ./home-manager/default.nix ];
+      };
+    };
+  };
+}
+```
+
+1.  This adds the Amp flake to your NixOS config.
+
+2.  This adds the Amp flake to your Home Manager config.
+
+You can then use the flake in your NixOS/Home Manager modules:
+
+```nix title="home-manager/default.nix" hl_lines="1 5"
+{ pkgs, amp, ... }: { # (1)!
+
+  # Text editors
+  home.packages = [
+    amp.packages.${pkgs.system}.default # (2)!
+    pkgs.vim
+  ];
+}
+```
+
+1. Specify the flake as an argument to your module to get a reference to it.
+2. Add Amp to the list of installed packages. This long format including the
+   reference to `pkgs.system` is a necessary evil, since the Amp flake needs to
+   know which system/architecture to target, and I've yet to find a way to set a
+   default package that is able to automatically take that into consideration.
+
+Now you can update Amp by running the following:
 
-# Flake-based build
-nix build --flake
+```shell
+# Bump flake.lock
+nix flake lock --update-input amp
 
-# Interactive console
-nix develop
+# Build and switch to the new version
+home-manager switch --flake /path-to-your-nixos-conf
 ```
 
 ## Arch Linux