From ebdcc2a1902a602eaf7dcf6246c830ddb10a96a7 Mon Sep 17 00:00:00 2001
From: Daniel Thwaites <danth@danth.me>
Date: Mon, 24 Feb 2025 18:10:45 +0000
Subject: [PATCH] doc: add module README for Firefox and derivatives (#897)

Link: https://github.com/danth/stylix/pull/897

Reviewed-by: NAHO <90870942+trueNAHO@users.noreply.github.com>
---
 modules/firefox/README.md | 37 +++++++++++++++++++++++++++++++++++++
 1 file changed, 37 insertions(+)
 create mode 100644 modules/firefox/README.md

diff --git a/modules/firefox/README.md b/modules/firefox/README.md
new file mode 100644
index 00000000..cb558a47
--- /dev/null
+++ b/modules/firefox/README.md
@@ -0,0 +1,37 @@
+# Firefox and its derivatives
+
+This module supports [Firefox](https://www.mozilla.org/firefox/), in addition
+to [Floorp](https://floorp.app/) and [LibreWolf](https://librewolf.net/),
+which are Firefox derivatives.
+
+The same implementation is shared between all of these browsers, but they don't
+share option values.
+
+> [!IMPORTANT]
+>
+> For any theming to be applied, you need to tell this module which
+> [profiles](https://support.mozilla.org/en-US/kb/profiles-where-firefox-stores-user-data)
+> you're using:
+>
+> ```nix
+> {
+>   programs.firefox = {
+>     enable = true;
+>
+>     profiles = {
+>       my-profile = {
+>         # bookmarks, extensions, search engines...
+>       };
+>       my-friends-profile = {
+>         # bookmarks, extensions, search engines...
+>       };
+>     };
+>   };
+>
+>   stylix.targets.firefox.profileNames = [ "my-profile" "my-friends-profile" ];
+> }
+> ```
+>
+> This is necessary due to a limitation of the module system: we can either
+> detect the list of profiles, or change their configuration, but we can't do
+> both without infinite recursion.