treewide: add stylix.enable option

README.md

@@ -34,6 +34,12 @@ For a visual guide, watch the [*Ricing Linux Has Never Been Easier | NixOS +
 Stylix*](https://youtu.be/ljHkWgBaQWU) YouTube video by
 [Vimjoyer](https://www.youtube.com/@vimjoyer).
 
+> [!NOTE]
+>
+> It's now necessary to include `stylix.enable = true` in your configuration
+> for any other settings to take effect. This is not mentioned in the video
+> linked above.
+
 If you have any questions, you are welcome to
 join our [Matrix room](https://matrix.to/#/#stylix:danth.me),
 or ask on [GitHub Discussions](https://github.com/danth/stylix/discussions).

docs/default.nix

@@ -47,6 +47,14 @@ in pkgs.stdenvNoCC.mkDerivation {
     cp ${../kde.png} src/kde.png
     cp ${../CONTRIBUTING.md} src/contributing.md
 
+    # mdBook doesn't support this Markdown extension yet
+    substituteInPlace **/*.md \
+      --replace-quiet '> [!NOTE]' '> **Note**' \
+      --replace-quiet '> [!TIP]' '> **Tip**' \
+      --replace-quiet '> [!IMPORTANT]' '> **Important**' \
+      --replace-quiet '> [!WARNING]' '> **Warning**' \
+      --replace-quiet '> [!CAUTION]' '> **Caution**'
+
     # The "declared by" links point to a file which only exists when the docs
     # are built locally. This removes the links.
     sed '/*Declared by:*/,/^$/d' <${nixos.optionsCommonMark} >>src/options/nixos.md

docs/src/configuration.md

@@ -1,5 +1,21 @@
 # Configuration
 
+## Enable
+
+To enable the Stylix module, declare:
+
+```nix
+{
+  stylix.enable = true;
+}
+```
+
+> [!NOTE]
+>
+> The global enable option was recently added, so you may come across old
+> examples which don't include it. No other settings will take effect unless
+> `stylix.enable` is set to `true`.
+
 ## Wallpaper
 
 To start theming, you need to set a wallpaper image.

docs/src/installation.md

@@ -119,7 +119,10 @@ let
 in {
     imports = [ (import stylix).homeManagerModules.stylix ];
 
-    stylix.image = ./wallpaper.jpg;
+    stylix = {
+      enable = true;
+      image = ./wallpaper.jpg;
+    };
 }
 
 ```

docs/src/modules.md

@@ -37,6 +37,7 @@ All modules should have an enable option created using `mkEnableTarget`.
 This is similar to
 [`mkEnableOption`](https://nix-community.github.io/docnix/reference/lib/options/lib-options-mkenableoption/)
 from the standard library, however it integrates with
+[`stylix.enable`](./options/nixos.md#stylixenable) and
 [`stylix.autoEnable`](./options/nixos.md#stylixautoenable)
 and generates more specific documentation.
 
@@ -46,16 +47,29 @@ A general format for modules is shown below.
 { config, lib, ... }:
 
 {
-  stylix.targets.«name».enable = config.lib.stylix.mkEnableTarget "«human readable name»";
+  options.stylix.targets.«name».enable =
+    config.lib.stylix.mkEnableTarget "«human readable name»" true;
 
-  config = lib.mkIf config.stylix.targets.«name».enable {
+  config = lib.mkIf (config.stylix.enable && config.stylix.targets.«name».enable) {
+    programs.«name».backgroundColor = config.lib.stylix.colors.base00;
   };
 }
 ```
 
-The human readable name must fit into the following sentence:
+The human readable name will be inserted into the following sentence:
 
-> Whether to style «human readable name».
+> Whether to enable theming for «human readable name».
+
+If your module will touch options outside of `programs.«name»` or `services.«name»`,
+it should include an additional condition in `mkIf` to prevent any effects
+when the target is not installed.
+
+The boolean value after `mkEnableTarget` should be changed to `false` if
+one of the following applies:
+
+- The module requires further manual setup to work correctly.
+- There is no reliable way to detect whether the target is installed, *and*
+  enabling it unconditionally would cause problems.
 
 ## How to apply colors
 

modules/alacritty/hm.nix

@@ -9,7 +9,7 @@ in
 {
   options.stylix.targets.alacritty.enable = config.lib.stylix.mkEnableTarget "Alacritty" true;
 
-  config = lib.mkIf config.stylix.targets.alacritty.enable {
+  config = lib.mkIf (config.stylix.enable && config.stylix.targets.alacritty.enable) {
     programs.alacritty.settings = {
       font = with config.stylix.fonts; {
         normal = {

modules/avizo/hm.nix

@@ -10,7 +10,7 @@ in
     config.lib.stylix.mkEnableTarget "Avizo" true;
 
   # Referenced https://github.com/stacyharper/base16-mako
-  config = lib.optionalAttrs (options.services ? avizo) (lib.mkIf config.stylix.targets.avizo.enable {
+  config = lib.optionalAttrs (options.services ? avizo) (lib.mkIf (config.stylix.enable && config.stylix.targets.avizo.enable) {
     services.avizo = {
         settings = {
             default = {

modules/bat/hm.nix

@@ -2,9 +2,9 @@
 
 {
   options.stylix.targets.bat.enable =
-    config.lib.stylix.mkEnableTarget "Bat" config.programs.bat.enable;
+    config.lib.stylix.mkEnableTarget "Bat" true;
 
-  config = lib.mkIf config.stylix.targets.bat.enable {
+  config = lib.mkIf (config.stylix.enable && config.stylix.targets.bat.enable) {
     programs.bat = {
       # This theme is reused for yazi. Changes to the template 
       # will need to be applied to modules/yazi/hm.nix

modules/bemenu/hm.nix

@@ -25,7 +25,7 @@ in {
     };
   };
 
-  config = lib.mkIf config.stylix.targets.bemenu.enable {
+  config = lib.mkIf (config.stylix.enable && config.stylix.targets.bemenu.enable) {
     programs.bemenu.settings = with config.stylix.targets.bemenu; {
       tb = "${base01}${bemenuOpacity}"; # Title bg
       nb = "${base01}${bemenuOpacity}"; # Normal bg

modules/bspwm/hm.nix

@@ -6,7 +6,7 @@ in {
   options.stylix.targets.bspwm.enable =
     config.lib.stylix.mkEnableTarget "bspwm" true;
 
-  config = lib.mkIf config.stylix.targets.bspwm.enable {
+  config = lib.mkIf (config.stylix.enable && config.stylix.targets.bspwm.enable) {
     xsession.windowManager.bspwm.settings = {
       normal_border_color = colors.base03;
       active_border_color = colors.base0C;

modules/btop/hm.nix

@@ -3,9 +3,9 @@
 let
     colors = config.lib.stylix.colors.withHashtag;
 in {
-    options.stylix.targets.btop.enable = config.lib.stylix.mkEnableTarget "btop" config.programs.btop.enable;
+    options.stylix.targets.btop.enable = config.lib.stylix.mkEnableTarget "btop" true;
 
-      config = lib.mkIf config.stylix.targets.btop.enable {
+      config = lib.mkIf (config.stylix.enable && config.stylix.targets.btop.enable && config.programs.btop.enable) {
 
         programs.btop.settings = {
             color_theme = "stylix";

modules/chromium/nixos.nix

@@ -4,7 +4,7 @@
   options.stylix.targets.chromium.enable =
     config.lib.stylix.mkEnableTarget "Chromium, Google Chrome and Brave" true;
 
-  config.programs.chromium = lib.mkIf config.stylix.targets.chromium.enable {
+  config.programs.chromium = lib.mkIf (config.stylix.enable && config.stylix.targets.chromium.enable) {
     # This enables policies without installing the browser. Policies take up a
     # negligible amount of space, so it's reasonable to have this always on.
     enable = true;

modules/console/nixos.nix

@@ -6,7 +6,7 @@ with config.lib.stylix.colors;
   options.stylix.targets.console.enable =
     config.lib.stylix.mkEnableTarget "the Linux kernel console" true;
 
-  config.console.colors = lib.mkIf config.stylix.targets.console.enable [
+  config.console.colors = lib.mkIf (config.stylix.enable && config.stylix.targets.console.enable) [
     base00-hex
     red
     green

modules/dunst/hm.nix

@@ -8,7 +8,7 @@ in {
   options.stylix.targets.dunst.enable =
     config.lib.stylix.mkEnableTarget "Dunst" true;
 
-  config = lib.mkIf config.stylix.targets.dunst.enable {
+  config = lib.mkIf (config.stylix.enable && config.stylix.targets.dunst.enable) {
     services.dunst.settings = {
       global = {
         separator_color = base02;

modules/emacs/hm.nix

@@ -8,9 +8,9 @@ let
 in
 {
   options.stylix.targets.emacs.enable =
-    config.lib.stylix.mkEnableTarget "Emacs" config.programs.emacs.enable;
+    config.lib.stylix.mkEnableTarget "Emacs" true;
 
-  config = lib.mkIf config.stylix.targets.emacs.enable {
+  config = lib.mkIf (config.stylix.enable && config.stylix.targets.emacs.enable) {
     programs.emacs = {
       extraPackages = epkgs:
         [

modules/feh/hm.nix

@@ -4,13 +4,20 @@
   options.stylix.targets.feh.enable =
     config.lib.stylix.mkEnableTarget
     "the desktop background using Feh"
-    (with config.xsession.windowManager; bspwm.enable
-                                      || herbstluftwm.enable
-                                      || i3.enable
-                                      || spectrwm.enable
-                                      || xmonad.enable);
+    true;
 
   config.xsession.initExtra =
-    lib.mkIf config.stylix.targets.feh.enable
+    lib.mkIf (
+      config.stylix.enable
+      && config.stylix.targets.feh.enable
+      && (
+        with config.xsession.windowManager;
+        bspwm.enable
+        || herbstluftwm.enable
+        || i3.enable
+        || spectrwm.enable
+        || xmonad.enable
+      )
+    )
     "${pkgs.feh}/bin/feh --no-fehbg --bg-scale ${config.stylix.image}";
 }

modules/feh/nixos.nix

@@ -4,9 +4,17 @@
   options.stylix.targets.feh.enable =
     config.lib.stylix.mkEnableTarget
     "the desktop background using Feh"
-    (with config.services.xserver.windowManager; xmonad.enable || i3.enable);
+    true;
 
   config.services.xserver.displayManager.sessionCommands =
-    lib.mkIf config.stylix.targets.feh.enable
+    lib.mkIf (
+      config.stylix.enable
+      && config.stylix.targets.feh.enable
+      && (
+        with config.services.xserver.windowManager;
+        xmonad.enable
+        || i3.enable
+      )
+    )
     "${pkgs.feh}/bin/feh --no-fehbg --bg-scale ${config.stylix.image}";
 }

modules/firefox/hm.nix

@@ -13,7 +13,7 @@ let
 in {
   options.stylix.targets.firefox = {
     enable =
-      config.lib.stylix.mkEnableTarget "Firefox" config.programs.firefox.enable;
+      config.lib.stylix.mkEnableTarget "Firefox" true;
 
     profileNames = lib.mkOption {
       description = "The Firefox profile names to apply styling on.";
@@ -22,7 +22,7 @@ in {
     };
   };
 
-  config = lib.mkIf config.stylix.targets.firefox.enable {
+  config = lib.mkIf (config.stylix.enable && config.stylix.targets.firefox.enable) {
     programs.firefox.profiles = lib.listToAttrs
       (map makeProfileSettingsPair config.stylix.targets.firefox.profileNames);
   };

modules/fish/hm.nix

@@ -4,7 +4,7 @@
   options.stylix.targets.fish.enable =
     config.lib.stylix.mkEnableTarget "Fish" true;
 
-  config = lib.mkIf config.stylix.targets.fish.enable {
+  config = lib.mkIf (config.stylix.enable && config.stylix.targets.fish.enable) {
     programs.fish.interactiveShellInit = import ./prompt.nix { inherit pkgs config; };
   };
 }

modules/fish/nixos.nix

@@ -4,7 +4,7 @@
   options.stylix.targets.fish.enable =
     config.lib.stylix.mkEnableTarget "Fish" true;
 
-  config = lib.mkIf config.stylix.targets.fish.enable {
+  config = lib.mkIf (config.stylix.enable && config.stylix.targets.fish.enable) {
     programs.fish.promptInit = import ./prompt.nix { inherit pkgs config; };
   };
 }

modules/fuzzel/hm.nix

@@ -7,10 +7,10 @@ let
 
 in {
   options.stylix.targets.fuzzel.enable =
-    config.lib.stylix.mkEnableTarget "Fuzzel" config.programs.fuzzel.enable;
+    config.lib.stylix.mkEnableTarget "Fuzzel" true;
 
   config.programs.fuzzel.settings =
-    lib.mkIf config.stylix.targets.fuzzel.enable {
+    lib.mkIf (config.stylix.enable && config.stylix.targets.fuzzel.enable) {
       colors = {
         background = "${base00-hex}${opacity}";
         text = "${base05-hex}ff";

modules/fzf/hm.nix

@@ -20,10 +20,10 @@ let
 in
 {
   options.stylix.targets.fzf = {
-    enable = config.lib.stylix.mkEnableTarget "Fzf" config.programs.fzf.enable;
+    enable = config.lib.stylix.mkEnableTarget "Fzf" true;
   };
 
-  config = lib.mkIf config.stylix.targets.fzf.enable {
+  config = lib.mkIf (config.stylix.enable && config.stylix.targets.fzf.enable) {
     programs.fzf.defaultOptions = lib.mkAfter [ "--color=${colorConfig}" ];
   };
 }

modules/gedit/hm.nix

@@ -10,7 +10,7 @@ in {
   options.stylix.targets.gedit.enable =
     config.lib.stylix.mkEnableTarget "GEdit" true;
 
-  config = lib.mkIf config.stylix.targets.gedit.enable {
+  config = lib.mkIf (config.stylix.enable && config.stylix.targets.gedit.enable) {
     xdg.dataFile = {
       "gedit/styles/stylix.xml".source = style;
     };

modules/gitui/hm.nix

@@ -14,7 +14,7 @@ in
   options.stylix.targets.gitui.enable =
     config.lib.stylix.mkEnableTarget "GitUI" true;
 
-  config = lib.mkIf config.stylix.targets.gitui.enable {
+  config = lib.mkIf (config.stylix.enable && config.stylix.targets.gitui.enable) {
     programs.gitui.theme = ''
       (
           selected_tab: Some(Reset),

modules/gnome/hm.nix

@@ -6,7 +6,7 @@ with lib;
   options.stylix.targets.gnome.enable =
     config.lib.stylix.mkEnableTarget "GNOME" true;
 
-  config = mkIf config.stylix.targets.gnome.enable {
+  config = mkIf (config.stylix.enable && config.stylix.targets.gnome.enable) {
     dconf.settings = {
       "org/gnome/desktop/background" = {
         color-shading-type = "solid";

modules/gnome/nixos.nix

@@ -5,11 +5,13 @@ let
 
 in {
   options.stylix.targets.gnome.enable =
-    config.lib.stylix.mkEnableTarget
-    "GNOME and GDM"
-    config.services.xserver.desktopManager.gnome.enable;
+    config.lib.stylix.mkEnableTarget "GNOME and GDM" true;
 
-  config = lib.mkIf config.stylix.targets.gnome.enable {
+  config = lib.mkIf (
+    config.stylix.enable
+    && config.stylix.targets.gnome.enable
+    && config.services.xserver.desktopManager.gnome.enable
+  ) {
     # As Stylix is controlling the wallpaper, there is no need for this
     # pack of default wallpapers to be installed.
     # If you want to use one, you can set stylix.image to something like

modules/grub/nixos.nix

@@ -34,7 +34,7 @@ in {
     };
   };
 
-  config.boot.loader.grub = lib.mkIf config.stylix.targets.grub.enable {
+  config.boot.loader.grub = lib.mkIf (config.stylix.enable && config.stylix.targets.grub.enable) {
     backgroundColor = base00;
     # Need to override the NixOS splash, this will match the background
     splashImage = pixel "base00";

modules/gtk/nixos.nix

@@ -4,7 +4,7 @@
   options.stylix.targets.gtk.enable =
     config.lib.stylix.mkEnableTarget "all GTK3, GTK4 and Libadwaita apps" true;
 
-  config = lib.mkIf config.stylix.targets.gtk.enable {
+  config = lib.mkIf (config.stylix.enable && config.stylix.targets.gtk.enable) {
     # Required for Home Manager's GTK settings to work
     programs.dconf.enable = true;
   };

modules/helix/hm.nix

@@ -14,9 +14,9 @@ let
 
 in {
   options.stylix.targets.helix.enable =
-    config.lib.stylix.mkEnableTarget "Helix" config.programs.helix.enable;
+    config.lib.stylix.mkEnableTarget "Helix" true;
 
-  config = lib.mkIf config.stylix.targets.helix.enable {
+  config = lib.mkIf (config.stylix.enable && config.stylix.targets.helix.enable && config.programs.helix.enable) {
     programs.helix.settings.theme = "stylix";
 
     xdg.configFile."helix/themes/stylix.toml".source =

modules/hyprland/hm.nix

@@ -25,5 +25,5 @@ in {
     config.lib.stylix.mkEnableTarget "Hyprland" true;
 
   config.wayland.windowManager.hyprland.settings =
-    lib.mkIf config.stylix.targets.hyprland.enable settings;
+    lib.mkIf (config.stylix.enable && config.stylix.targets.hyprland.enable) settings;
 }