From 6d72fc259b6f595f5bcf9634bf2f82b76f939a0d Mon Sep 17 00:00:00 2001
From: "Shahar \"Dawn\" Or" <mightyiampresence@gmail.com>
Date: Wed, 11 Jun 2025 00:28:41 +0700
Subject: [PATCH] fontconfig: align Home Manager with NixOS and enhance docs
 (#1292)

BREAKING CHANGE: The fontconfig target no longer enables Home Manager's
fonts.fontconfig.enable option and now sets Home Manager's
fonts.fontconfig.defaultFonts option instead.

Link: https://github.com/nix-community/stylix/pull/1292

Reviewed-by: awwpotato <awwpotato@voidq.com>
Reviewed-by: Flameopathic <64027365+Flameopathic@users.noreply.github.com>
Reviewed-by: Matt Sturgeon <matt@sturgeon.me.uk>
Reviewed-by: NAHO <90870942+trueNAHO@users.noreply.github.com>
---
 doc/src/configuration.md          | 12 ++++++++++++
 modules/font-packages/meta.nix    |  6 +-----
 modules/fontconfig/fontconfig.nix | 16 ++++++++++++++++
 modules/fontconfig/hm.nix         | 13 +++++--------
 modules/fontconfig/meta.nix       | 11 +++--------
 modules/fontconfig/nixos.nix      | 20 +++++---------------
 6 files changed, 42 insertions(+), 36 deletions(-)
 create mode 100644 modules/fontconfig/fontconfig.nix

diff --git a/doc/src/configuration.md b/doc/src/configuration.md
index ff4ed762..e01deeae 100644
--- a/doc/src/configuration.md
+++ b/doc/src/configuration.md
@@ -111,6 +111,18 @@ or at `~/.config/stylix/palette.html` on Home Manager.
 
 ## Fonts
 
+Fonts can apply in three ways:
+
+1. An app's own font options
+  (e.g. [the Alacritty module](./options/modules/alacritty.html) sets home-manager's
+  `programs.alacritty.settings.font`).
+
+2. Widely, through
+  [the Fontconfig module](./options/modules/fontconfig.html).
+
+3. Made available in an environment using
+  [the font packages module](./options/modules/font-packages.html).
+
 The default combination of fonts is:
 
 ```nix
diff --git a/modules/font-packages/meta.nix b/modules/font-packages/meta.nix
index ee8abe65..3541d872 100644
--- a/modules/font-packages/meta.nix
+++ b/modules/font-packages/meta.nix
@@ -6,10 +6,6 @@
     This module makes the Stylix fonts available in the environment of each of
     the platforms that this module supports.
 
-    ### Related modules
-
-    <!-- If updating this section, make sure to update it on the linked pages too. -->
-
-    - [Fontconfig](fontconfig.md)
+    Also see [general fonts documentation](../../configuration.html#fonts).
   '';
 }
diff --git a/modules/fontconfig/fontconfig.nix b/modules/fontconfig/fontconfig.nix
new file mode 100644
index 00000000..ccabdf1a
--- /dev/null
+++ b/modules/fontconfig/fontconfig.nix
@@ -0,0 +1,16 @@
+{ mkTarget }:
+mkTarget {
+  name = "fontconfig";
+  humanName = "Fontconfig";
+
+  configElements =
+    { fonts }:
+    {
+      fonts.fontconfig.defaultFonts = {
+        monospace = [ fonts.monospace.name ];
+        serif = [ fonts.serif.name ];
+        sansSerif = [ fonts.sansSerif.name ];
+        emoji = [ fonts.emoji.name ];
+      };
+    };
+}
diff --git a/modules/fontconfig/hm.nix b/modules/fontconfig/hm.nix
index 8a1df997..9e14cdbc 100644
--- a/modules/fontconfig/hm.nix
+++ b/modules/fontconfig/hm.nix
@@ -1,9 +1,6 @@
-{ mkTarget, ... }:
-mkTarget {
-  name = "fontconfig";
-  humanName = "Fontconfig";
-
-  configElements = {
-    fonts.fontconfig.enable = true;
-  };
+{ lib, mkTarget, ... }:
+{
+  imports = [
+    (lib.modules.importApply ./fontconfig.nix { inherit mkTarget; })
+  ];
 }
diff --git a/modules/fontconfig/meta.nix b/modules/fontconfig/meta.nix
index 27d6f7e3..a3ea26b6 100644
--- a/modules/fontconfig/meta.nix
+++ b/modules/fontconfig/meta.nix
@@ -4,14 +4,9 @@
   homepage = "https://fontconfig.org";
   maintainers = [ lib.maintainers.mightyiam ];
   description = ''
-    On NixOS, `fonts.fontconfig.defaultFonts` options are declared without
-    enabling `fonts.fontconfig.enable`. On Home Manager, only the
-    `fonts.fontconfig.enable` option is declared and enabled.
+    This module adds the Stylix fonts to `fonts.fontconfig.defaultFonts` in
+    each of the platforms that this module supports.
 
-    ### Related modules
-
-    <!-- If updating this section, make sure to update it on the linked pages too. -->
-
-    - [Font packages](font-packages.md)
+    Also see [general fonts documentation](../../configuration.html#fonts).
   '';
 }
diff --git a/modules/fontconfig/nixos.nix b/modules/fontconfig/nixos.nix
index 2877f7ae..9e14cdbc 100644
--- a/modules/fontconfig/nixos.nix
+++ b/modules/fontconfig/nixos.nix
@@ -1,16 +1,6 @@
-{ mkTarget, ... }:
-mkTarget {
-  name = "fontconfig";
-  humanName = "Fontconfig";
-
-  configElements =
-    { fonts }:
-    {
-      fonts.fontconfig.defaultFonts = {
-        monospace = [ fonts.monospace.name ];
-        serif = [ fonts.serif.name ];
-        sansSerif = [ fonts.sansSerif.name ];
-        emoji = [ fonts.emoji.name ];
-      };
-    };
+{ lib, mkTarget, ... }:
+{
+  imports = [
+    (lib.modules.importApply ./fontconfig.nix { inherit mkTarget; })
+  ];
 }