From b45eb498944ffeae47aba8d1e42b8449fd07ca08 Mon Sep 17 00:00:00 2001
From: awwpotato <153149335+awwpotato@users.noreply.github.com>
Date: Mon, 31 Mar 2025 13:09:12 -0700
Subject: [PATCH] docs: add trick about lib.mkAfter (#1055)

---
 docs/src/tricks.md | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)

diff --git a/docs/src/tricks.md b/docs/src/tricks.md
index 042a2750..cf3d3d35 100644
--- a/docs/src/tricks.md
+++ b/docs/src/tricks.md
@@ -76,3 +76,27 @@ itself:
 imports = [ flake.inputs.stylix.nixosModules.stylix ];
 disabledModules = [ "${flake.inputs.stylix}/modules/<some-module>/nixos.nix" ];
 ```
+
+## Extending CSS options
+
+When trying to extend an attrset option, the order does not matter because a
+declaration can only exist once. This is not the case for an option with the
+type of `lines` (most commonly `style` options in Home Manager). For these options,
+the order does matter and Nix cannot guarantee that there aren't conflicting
+definitions. Nix will still merge these options, but it will not warn you if
+there are conflicting declaration. In order to get around this, you can make sure
+Nix puts your CSS at the end - and thus prioritizes it - by using `lib.mkAfter`:
+
+```nix
+{ lib, ... }:
+{
+  programs.waybar = {
+    enable = true;
+    style = lib.mkAfter ''
+      #workspaces button {
+        background: @base01;
+      }
+    '';
+  };
+}
+```