feat: adds flake.nix with home manager support

README.md

@@ -153,44 +153,241 @@ Add the plugin to the list of TPM plugins in your `~/.tmux.conf`:
 set -g @plugin 'alexwforsythe/tmux-which-key'
 ```
 
+<!-- markdownlint-disable MD033 -->
+
 Hit `prefix` + <kbd>I</kbd> to install and load the plugin. You'll be presented
 with a wizard to complete the installation.
 
+<!-- markdownlint-enable MD033 -->
+
 ### Manual installation
 
 <!-- markdownlint-disable MD033 -->
+
 <details>
 <summary>Installation steps</summary>
 
 1. Clone this repository flag using the `--recursive` flag:
 
-```sh
-git clone --recursive https://github.com/alexwforsythe/tmux-which-key $HOME/.tmux/plugins/
-```
+   ```sh
+   git clone --recursive https://github.com/alexwforsythe/tmux-which-key $HOME/.tmux/plugins/
+   ```
 
 2. Register the plugin in your `~/.tmux.conf`:
 
-```tmux
-run-shell $PATH_TO_PLUGIN/plugin.sh.tmux
-```
+   ```tmux
+   run-shell $PATH_TO_PLUGIN/plugin.sh.tmux
+   ```
 
 3. Reload your tmux config to load the plugin:
 
-```sh
-tmux source-file $HOME/.tmux.conf
+   ```sh
+   tmux source-file $HOME/.tmux.conf
+   ```
+
+</details>
+
+<!-- markdownlint-enable MD033 -->
+
+### Nix with home manager flake installation
+
+<!-- markdownlint-disable MD033 -->
+
+<details>
+<summary>Installation steps</summary>
+
+The default tmux options require the plugin directory to be writeable which will
+not work with the Nix store.  XDG user directory support was added in
+alexwforsythe/tmux-which-key#1.  Using this plugin with NixOS without home manager
+is technically possible, but it is not currently supported.
+
+Enabling this plugin with the home manager module currently sets the following options:
+
+```tmux
+# Enables XDG user directory support for the plugin.
+set -g @tmux-which-key-xdg-enable 1;
+
+# Disables building the tmux configuration from YAML everytime the plugin starts.
+# The home manager module calls `plugin/build.py` on each generation.
+set -g @tmux-which-key-disable-autobuild 1
+
+# Follows nixpkgs prefered path for plugins instead of the default
+# path of `${XDG_*_HOME}/tmux/plugins/tmux-which-key`.
+set -g @tmux-which-key-xdg-plugin-path tmux-plugins/tmux-which-key
 ```
 
+A symlink of the config file is created in `${XDG_CONFIG_HOME}/tmux-plugins/tmux-which-key/config.yaml`
+for reference.  This is the same file used to generate the actual configuration
+loaded at runtime: `${XDG_DATA_HOME}/tmux-plugins/tmux-which-key/init.tmux`
+
+The following steps go over adding this plugin from the included `flake.nix`:
+
+1. Add this repository as an input and apply its overlay to add the package as
+   `tmuxPlugins.tmux-which-key` with the other tmux plugins in `nixpkgs`:
+
+   ```nix
+   # flake.nix
+   ...
+
+   inputs = {
+     nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
+     home-manager.url = "github:nix-community/home-manager";
+     tmux-which-key = {
+       url = "github:alexwforsythe/tmux-which-key";
+       inputs.nixpkgs.follows = "nixpkgs";
+     };
+     ...
+   };
+
+   outputs = {
+     self,
+     nixpkgs,
+     home-manager,
+     tmux-which-key,
+     ...
+   } @ inputs: let
+     lib = nixpkgs.lib // home-manager.lib;
+     systems = ["x86_64-linux" "aarch64-linux" "x86_64-darwin" "aarch64-darwin"];
+     forAllSystems = f: lib.genAttrs systems (system: f pkgsFor.${system});
+     pkgsFor = lib.genAttrs systems (system:
+       import nixpkgs {
+         inherit system;
+         overlays = [tmux-which-key.overlays.default];
+       });
+   in {
+     nixosConfigurations = {
+       "<configuration name>" = lib.nixosSystem {
+         modules = [...];
+         specialArgs = {inherit inputs outputs;};
+         pkgs = pkgsFor.x86_64-linux;
+       };
+     };
+
+     homeConfigurations = {
+       "<configuration name>" = lib.homeManagerConfiguration {
+         modules = [...];
+         extraSpecialArgs = {inherit inputs outputs;};
+         pkgs = pkgsFor.x86_64-linux;
+       };
+     };
+   }
+   ```
+
+2. Import the home manager module and enable the plugin to use `config.example.yaml`
+   as the default configuration:
+
+   ```nix
+   # tmux.nix
+   {
+     config,
+     lib,
+     pkgs,
+     inputs,
+     ...
+   }: {
+     imports = [inputs.tmux-which-key.homeManagerModules.default];
+
+     programs = {
+       tmux = {
+         enable = true;
+         tmux-which-key = {
+           enable = true;
+         };
+       };
+
+       ...
+
+     };
+
+     ...
+   }
+   ```
+
+3. For customized settings, configure the plugin directly through the exposed home
+   manager `settings` option with an attribute set mirroring a YAML configuration.
+   The home manager module takes care of building `init.tmux` during each generation.
+   The `settings` option does not strictly enforce the configuration schema, but
+   it is validated using `check-jsonschema` so that any configuration errors will
+   be visible with `nix log`.
+
+   ```nix
+   # tmux.nix
+   ...
+
+         tmux-which-key = {
+           enable = true;
+           settings = {
+             command_alias_start_index = 200;
+             ... 
+           };
+         };
+
+   ...
+   ```
+
+   A YAML file may also be loaded from the file system and converted into an attribute
+   set by first converting the YAML into JSON with `yj` and then from JSON to Nix
+   using `builtins.fromJSON`.
+
+   ```nix
+   # tmux.nix
+   ...
+
+         tmux-which-key = {
+           enable = true;
+           settings = let
+             fromYaml = file: let
+               convertedJson = pkgs.runCommandNoCC "converted.json" {} ''
+                 ${lib.getExe pkgs.yj} < ${file} > $out
+               '';
+             in
+               builtins.fromJSON (builtins.readFile "${convertedJson}");
+           in
+             fromYaml ./path/to/config.yaml
+         };
+
+       ...
+
+     };
+
+   ...
+   ```
+
+   The default `config.example.yaml` configuration can also be exported as an
+   attribute set to use as a base.
+
+   ```sh
+   nix run "github:alexwforsythe/tmux-which-key#generate-config" > ./path/to/config.nix
+   ```
+
+   ```nix
+   # tmux.nix
+   ...
+
+         tmux-which-key = {
+           enable = true;
+           settings = import ./path/to/config.nix;
+         };
+
+   ...
+   ```
+
 </details>
+
 <!-- markdownlint-enable MD033 -->
 
 ## 🎬️ Quickstart
 
 Once you've installed the plugin and reloaded your tmux config, you can open the
 action using:
 
+<!-- markdownlint-disable MD033 -->
+
 - The default root keybinding <kbd>ctrl</kbd> + <kbd>space</kbd>, or
 - The default prefix keybinding `prefix` + <kbd>space</kbd>
 
+<!-- markdownlint-enable MD033 -->
+
 ## ⚙️ Configuration
 
 Menus can be customized either by:
@@ -292,51 +489,7 @@ set -g @plugin 'alexwforsythe/tmux-which-key'
 ```
 
 This allows the plugin to also be used with immutable or declarative operating
-systems.
-
-<!-- markdownlint-disable MD033 -->
-<details>
-<summary>Example Home Manager Nix Config</summary>
-
-```nix
-{
-  lib,
-  pkgs,
-  ...
-}: let
-  tmux-which-key =
-    pkgs.tmuxPlugins.mkTmuxPlugin
-    {
-      pluginName = "tmux-which-key";
-      version = "2024-01-10";
-      src = pkgs.fetchFromGitHub {
-        owner = "alexwforsythe";
-        repo = "tmux-which-key";
-        rev = "<commit hash>";
-        sha256 = lib.fakeSha256;
-      };
-      rtpFilePath = "plugin.sh.tmux";
-    };
-in {
-  xdg.configFile = {
-    "tmux/plugins/tmux-which-key/config.yaml".text = lib.generators.toYAML {} {
-      command_alias_start_index = 200;
-      # rest of config here
-    };
-  };
-  programs.tmux.plugins = [
-    {
-      plugin = tmux-which-key;
-      extraConfig = ''
-        set -g @tmux-which-key-xdg-enable 1;
-      '';
-    }
-  ];
-}
-```
-
-</details>
-<!-- markdownlint-enable MD033 -->
+systems such as NixOS.
 
 <!-- markdownlint-disable MD024 -->
 
@@ -357,11 +510,15 @@ You can open tmux-which-key from the command line by running its tmux alias:
 tmux show-wk-menu-root
 ```
 
+<!-- markdownlint-disable MD033 -->
+
 You can trigger the menu with <kbd>Space</kbd> from vicmd mode--similarly to
 [Spacemacs](https://github.com/syl20bnr/spacemacs) or
 [VSpaceCode](https://github.com/VSpaceCode/VSpaceCode)--by adding a ZLE widget
 and keybinding to your `~/.zshrc`:
 
+<!-- markdownlint-enable MD033 -->
+
 ```sh
 tmux-which-key() { tmux show-wk-menu-root ; }
 zle -N tmux-which-key