diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 571a5e54..8f7771f0 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -6,8 +6,54 @@ on: - master jobs: - pages: - name: Pages - uses: danth/coricamu/.github/workflows/pages.yml@cd253a6940853ffc3da7c14c9311940f1d70e222 - with: - output_name: docs + build: + name: Build + + permissions: + contents: read + + runs-on: ubuntu-latest + + steps: + - name: Install Nix + uses: cachix/install-nix-action@v19 + + - name: Set up Cachix + uses: cachix/cachix-action@v12 + with: + name: danth + authToken: '${{ secrets.CACHIX_AUTH_TOKEN }}' + + - name: Checkout repository + uses: actions/checkout@v3 + + - name: Build docs + run: nix -L build .#docs + + - name: Prepare docs for upload + run: cp -r --dereference --no-preserve=mode,ownership result/ public/ + + - name: Upload artifact + uses: actions/upload-pages-artifact@v1 + with: + path: public/ + + deploy: + name: Deploy + + needs: build + + permissions: + pages: write + id-token: write + + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + + runs-on: ubuntu-latest + + steps: + - name: Deploy docs to GitHub Pages + id: deployment + uses: actions/deploy-pages@v1 diff --git a/README.md b/README.md index 9d569741..51b9957f 100644 --- a/README.md +++ b/README.md @@ -4,330 +4,16 @@ Stylix is a NixOS module which applies the same color scheme, font and wallpaper to a wide range of applications and desktop environments. It also exports utilities for you to use the theme in custom parts of your configuration. -Stylix is built using [base16.nix](https://github.com/SenchoPens/base16.nix#readme), +Stylix is built upon [base16.nix](https://github.com/SenchoPens/base16.nix#readme), a library which processes themes created for [base16](https://github.com/chriskempson/base16#readme) or [Tinted Theming](https://github.com/tinted-theming). -## Installation +## Manual -### NixOS +Please refer to the [Stylix book](https://danth.github.io/stylix/) for +more details, including installation instructions. -You can install Stylix into your NixOS configuration using [Flakes][nix-flakes]. -This will provide theming for system level programs such as bootloaders, splash -screens, and display managers. +## License -```nix -{ - inputs = { - nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable"; - stylix.url = "github:danth/stylix"; - }; - - outputs = { nixpkgs, stylix, ... }: { - nixosConfigurations."«hostname»" = nixpkgs.lib.nixosSystem { - system = "x86_64-linux"; - modules = [ stylix.nixosModules.stylix ./configuration.nix ]; - }; - }; -} -``` -Minimal `flake.nix` for a NixOS configuration. - -Many applications cannot be configured system wide, so Stylix will also need -[Home Manager][nix-hm] to be able to change their settings within your home -directory. - -[Installing Home Manager as a NixOS module](https://nix-community.github.io/home-manager/index.html#sec-install-nixos-module) -is highly recommended if you don't use it already. This will combine it with -your existing configuration, so you don't need to run any extra commands when -you rebuild, and the theme you set in NixOS will automatically be used for Home -Manager too. - -When Stylix is installed to a NixOS configuration, it will automatically set up -its Home Manager modules if it detects that Home Manager is available. You can -theoretically use it without installing Home Manager, however most features -will be unavailable. - -### nix-darwin - -You can install Stylix intor your nix-darwin configuration in a similar fashion -to NixOS via [Flakes][nix-flakes]. - -```nix -{ - inputs = { - darwin = { - url = "github:LnL7/nix-darwin"; - inputs.nixpkgs.follows = "nixpkgs"; - }; - nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable"; - stylix.url = "github:danth/stylix"; - }; - - outputs = { darwin, nixpkgs, stylix, ... }: { - darwinConfigurations."«hostname»" = darwin.lib.darwinSystem { - system = "aarch64-darwin"; - modules = [ stylix.darwinModules.stylix ./configuration.nix ]; - }; - }; -} -``` - -While this won't have an effect on the looks of macOS, since we don't have the -controls to theme it like we do NixOS, it will automatically set up its [Home -Manager][nix-hm] modules if it detects that Home Manager is available. You can -theoretically use it without installing Home Manager, however most features will -be unavailable. - -### Home Manager - -If you would prefer to use the standalone version of Home Manager, you can -install Stylix directly into your Home Manager configuration instead. This -could be useful if you are on a different Linux distribution, or a NixOS -machine which is managed by someone else. - - -```nix -{ - inputs = { - nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable"; - home-manager.url = "github:nix-community/home-manager"; - stylix.url = "github:danth/stylix"; - }; - - outputs = { nixpkgs, home-manager, stylix, ... }: { - homeConfigurations."«username»" = home-manager.lib.homeManagerConfiguration { - pkgs = nixpkgs.legacyPackages.x86_64-linux; - modules = [ stylix.nixosModules.stylix ./home.nix ]; - }; - }; -} -``` -Minimal `flake.nix` for a Home Manager configuration. - -If you choose to use both NixOS and Home Manager but configure them separately, -you will need to copy the settings described below into both of your -configurations, as keeping them separate means that they cannot follow each -other automatically. - -### Without flakes - -If you haven't enabled flakes yet or don't want to use this feature, `default.nix` -re-exports all the flake outputs, without requiring flakes to be enabled. This means -that once you have a copy of this repo, using either a local checkout, -[niv](https://github.com/nmattia/niv), or any other method, you can import it to -get the NixOS module as the `nixosModules.stylix` attribute and the Home Manager -module as the `homeManagerModules.stylix` attribute. - -```nix -let - stylix = pkgs.fetchFromGitHub { - owner = "danth"; - repo = "stylix"; - rev = "..."; - sha256 = "..."; - }; -in { - imports = [ (import stylix).homeManagerModules.stylix ]; - - stylix.image = ./wallpaper.jpg; -} - -``` -Example usage of the Home Manager module without flakes. - -## Wallpaper - -To start theming, you need to set a wallpaper image. - -```nix -{ - stylix.image = ./wallpaper.png; -} -``` - -The option accepts derivations as well as paths, so you can fetch a wallpaper -directly from the internet: - -```nix -{ - stylix.image = pkgs.fetchurl { - url = "https://www.pixelstalk.net/wp-content/uploads/2016/05/Epic-Anime-Awesome-Wallpapers.jpg"; - sha256 = "enQo3wqhgf0FEPHj2coOCvo7DuZv+x5rL/WIo4qPI50="; - }; -} -``` - -At this point you should be able to rebuild and have a reasonable color scheme -generated based on the image you chose. - -## Color scheme - -### Automatic color schemes - -If you only set a wallpaper, Stylix will use a [genetic -algorithm](https://en.wikipedia.org/wiki/Genetic_algorithm) to create a color -scheme. The quality of these automatically generated schemes can vary, but more -colorful images tend to have better results. - -You can force the generation of a light or dark theme using the polarity -option: - -```nix -{ - stylix.polarity = "dark"; -} -``` - -After rebuilding, the full theme can be previewed in a web browser by -opening either of these files: - -- `/etc/stylix/palette.html` if you are using NixOS, or -- `$XDG_CONFIG_HOME/stylix/palette.html` (by default - `~/.config/stylix/palette.html`) if you are using home-manager - without NixOS. - -### Manual color schemes - -If you would prefer to choose a color scheme, you can use anything from -[the Tinted Theming repository](https://github.com/tinted-theming/base16-schemes), -or another file following that format. - -To use Tinted Theming, either add their repository to your Flake inputs, or -fetch it as follows: - -```nix -let - base16-schemes = pkgs.fetchFromGitHub { - owner = "tinted-theming"; - repo = "base16-schemes"; - rev = "..."; - sha256 = "..."; - }; -in { } -``` - -Then set the following option to the path of the color scheme you would like to -use: - -```nix -{ - stylix.base16Scheme = "${base16-schemes}/gruvbox-dark-hard.yaml"; -} -``` - -`base16Scheme` can also accept other formats as supported by -[`mkSchemeAttrs`](https://github.com/SenchoPens/base16.nix/blob/main/DOCUMENTATION.md#mkschemeattrs). - -### Overriding - -For convenience, it is possible to override parts of `stylix.base16Scheme` using -`stylix.override`. Anything that -[base16.nix](https://github.com/SenchoPens/base16.nix) accepts as override is -valid. - -When using both the Home Manager and NixOS modules, both the system overrides -and the user-provided one are used in the user configuration if -`stylix.base16Scheme` is not changed in the user config. If that is the case, -only the user override is used. - -## Fonts - -The default combination of fonts is: - -```nix -{ - stylix.fonts = { - serif = { - package = pkgs.dejavu_fonts; - name = "DejaVu Serif"; - }; - - sansSerif = { - package = pkgs.dejavu_fonts; - name = "DejaVu Sans"; - }; - - monospace = { - package = pkgs.dejavu_fonts; - name = "DejaVu Sans Mono"; - }; - - emoji = { - package = pkgs.noto-fonts-emoji; - name = "Noto Color Emoji"; - }; - }; -} -``` - -These can be changed as you like. - -To make things look more uniform, you could replace the serif font with -the sans-serif font: - -```nix -{ - stylix.fonts.serif = config.stylix.fonts.sansSerif; -} -``` - -Or even choose monospace for everything: - -```nix -{ - stylix.fonts = { - serif = config.stylix.fonts.monospace; - sansSerif = config.stylix.fonts.monospace; - emoji = config.stylix.fonts.monospace; - }; -} -``` - -## Multi-user configurations - -For those apps which are configured through Home Manager, Stylix allows you to -choose a different theme for each user. This can be done by setting the theme -within Home Manager for that user rather than at the system level. - -By default, all users follow the system theme. This can be turned off by -setting `stylix.homeManagerIntegration.followSystem = false`, in which case you -must explicitly set a theme for each user. Setting that option is not required -just to be able to override an individual theme. - -If you would like to disable all Home Manager activity for a user, you can set -`stylix.homeManagerIntegration.autoImport = false`, then manually import the -Home Manager module for the users for which it should be enabled. - -Note that if the wallpaper image for a user is different to the rest of the -system, a separate theme will always be generated for them, even though their -`base16Scheme` option has not been overridden. If you want that user to follow -the system theme while having a different wallpaper, you will need to manually -copy the system theme into their configuration. (This behaviour is necessary as -otherwise it would be impossible to use a generated theme for a user while -having a manually created theme for the rest of the system.) - -## Turning targets on and off - -In Stylix terms, a target is anything which can have colors, fonts or a -wallpaper applied to it. Each module in this repository should correspond to a -target of the same name. - -Each target has an option like `stylix.targets.«target».enable` to turn its -styling on or off. Normally, it's turned on automatically when the target is -installed. You can set `stylix.autoEnable = false` to opt out of this -behaviour, in which case you'll need to manually enable each target you want to -be styled. - -Targets are different between Home Manager and NixOS, and sometimes available -in both cases. If both are available, it is always correct to enable both. - -The Stylix website has a list of the available targets -[for NixOS](https://danth.github.io/stylix/options.html) -and -[for Home Manager](https://danth.github.io/stylix/options-hm.html) -respectively. - -[nix-flakes]: https://nixos.wiki/wiki/Flakes -[nix-hm]: https://github.com/nix-community/home-manager +Stylix is released under the [MIT License](https://github.com/danth/stylix/blob/master/LICENSE). diff --git a/docs/book.toml b/docs/book.toml new file mode 100644 index 00000000..c16729c3 --- /dev/null +++ b/docs/book.toml @@ -0,0 +1,9 @@ +[book] +title = "Stylix" +language = "en" + +[output.html] +site-url = "/stylix/" +git-repository-url = "https://github.com/danth/stylix" +edit-url-template = "https://github.com/danth/stylix/edit/master/docs/{path}" + diff --git a/docs/default.nix b/docs/default.nix index 54bca205..9e95d4c0 100644 --- a/docs/default.nix +++ b/docs/default.nix @@ -1,68 +1,56 @@ -{ pkgs, pkgsLib, coricamuLib, config, inputs, ... }: +{ pkgs, lib, inputs, ... }: -with coricamuLib; +let + makeOptionsDoc = configuration: pkgs.nixosOptionsDoc { + inherit (configuration) options; -rec { - baseUrl = "https://danth.github.io/stylix/"; - siteTitle = "Stylix"; - language = "en-gb"; - - header = makeProjectHeader { - title = siteTitle; - inherit (config) pages; - repository = "https://github.com/danth/stylix"; + # Filter out any options not beginning with `stylix` + transformOptions = option: option // { + visible = option.visible && + builtins.elemAt option.loc 0 == "stylix"; + }; }; - pages = makeProjectPages ../. ++ [ - { - path = "options.html"; - title = "NixOS options"; + nixos = makeOptionsDoc + (lib.nixosSystem { + inherit (pkgs) system; + modules = [ + inputs.home-manager.nixosModules.home-manager + inputs.self.nixosModules.stylix + ./settings.nix + ]; + }); - body.docbook = - let - configuration = pkgsLib.nixosSystem { - inherit (pkgs) system; - modules = [ - inputs.self.nixosModules.stylix - ./settings.nix - { _module.check = false; } - ]; + homeManager = makeOptionsDoc + (inputs.home-manager.lib.homeManagerConfiguration { + inherit pkgs; + modules = [ + inputs.self.homeManagerModules.stylix + ./settings.nix + { + home = { + homeDirectory = "/home/book"; + stateVersion = "22.11"; + username = "book"; }; - in - builtins.readFile ./nixos_header.xml + - makeOptionsDocBook { - inherit (configuration) options; - customFilter = option: builtins.elemAt option.loc 0 == "stylix"; - }; - } + } + ]; + }); - { - path = "options-hm.html"; - title = "Home Manager options"; +in pkgs.stdenvNoCC.mkDerivation { + name = "stylix-book"; + src = ./.; - body.docbook = - let - configuration = inputs.home-manager.lib.homeManagerConfiguration { - inherit pkgs; - modules = [ - inputs.self.homeManagerModules.stylix - ./settings.nix - { - home = { - homeDirectory = "/home/docs"; - stateVersion = "22.11"; - username = "docs"; - }; - } - ]; - check = false; - }; - in - builtins.readFile ./hm_header.xml + - makeOptionsDocBook { - inherit (configuration) options; - customFilter = option: builtins.elemAt option.loc 0 == "stylix"; - }; - } - ]; + patchPhase = '' + cp ${../README.md} src/README.md + + # 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 + sed '/*Declared by:*/,/^$/d' <${homeManager.optionsCommonMark} >>src/options/hm.md + ''; + + buildPhase = '' + ${pkgs.mdbook}/bin/mdbook build --dest-dir $out + ''; } diff --git a/docs/hm_header.xml b/docs/hm_header.xml deleted file mode 100644 index 6890bbb9..00000000 --- a/docs/hm_header.xml +++ /dev/null @@ -1,27 +0,0 @@ - -The following options can only be set in a Home Manager configuration. - - -If you combined Home Manager with your NixOS configuration, write these -options within a Home Manager section, either for all users: - - - -Or for a specific user: - - - - -Read more about per-user themes. - - diff --git a/docs/nixos_header.xml b/docs/nixos_header.xml deleted file mode 100644 index 3de4c821..00000000 --- a/docs/nixos_header.xml +++ /dev/null @@ -1,3 +0,0 @@ - -The following options can only be set in a NixOS configuration. - diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md new file mode 100644 index 00000000..eb82e40a --- /dev/null +++ b/docs/src/SUMMARY.md @@ -0,0 +1,12 @@ +[Introduction](README.md) + +# User guide + +- [Installation](installation.md) +- [Configuration](configuration.md) +- [Tips and tricks](tricks.md) + +# Reference + +- [NixOS options](options/nixos.md) +- [Home Manager options](options/hm.md) diff --git a/docs/src/configuration.md b/docs/src/configuration.md new file mode 100644 index 00000000..540abbe3 --- /dev/null +++ b/docs/src/configuration.md @@ -0,0 +1,189 @@ +# Configuration + +## Wallpaper + +To start theming, you need to set a wallpaper image. + +```nix +{ + stylix.image = ./wallpaper.png; +} +``` + +The option accepts derivations as well as paths, so you can fetch a wallpaper +directly from the internet: + +```nix +{ + stylix.image = pkgs.fetchurl { + url = "https://www.pixelstalk.net/wp-content/uploads/2016/05/Epic-Anime-Awesome-Wallpapers.jpg"; + sha256 = "enQo3wqhgf0FEPHj2coOCvo7DuZv+x5rL/WIo4qPI50="; + }; +} +``` + +At this point you should be able to rebuild and have a reasonable color scheme +generated based on the image you chose. + +## Color scheme + +### Automatic color schemes + +If you only set a wallpaper, Stylix will use a [genetic +algorithm](https://en.wikipedia.org/wiki/Genetic_algorithm) to create a color +scheme. The quality of these automatically generated schemes can vary, but more +colorful images tend to have better results. + +You can force the generation of a light or dark theme using the polarity +option: + +```nix +{ + stylix.polarity = "dark"; +} +``` + +After rebuilding, the full theme can be previewed in a web browser by +opening either of these files: + +- `/etc/stylix/palette.html` if you are using NixOS, or +- `$XDG_CONFIG_HOME/stylix/palette.html` (by default + `~/.config/stylix/palette.html`) if you are using home-manager + without NixOS. + +### Manual color schemes + +If you would prefer to choose a color scheme, you can use anything from +[the Tinted Theming repository](https://github.com/tinted-theming/base16-schemes), +or another file following that format. + +To use Tinted Theming, either add their repository to your Flake inputs, or +fetch it as follows: + +```nix +let + base16-schemes = pkgs.fetchFromGitHub { + owner = "tinted-theming"; + repo = "base16-schemes"; + rev = "..."; + sha256 = "..."; + }; +in { } +``` + +Then set the following option to the path of the color scheme you would like to +use: + +```nix +{ + stylix.base16Scheme = "${base16-schemes}/gruvbox-dark-hard.yaml"; +} +``` + +`base16Scheme` can also accept other formats as supported by +[`mkSchemeAttrs`](https://github.com/SenchoPens/base16.nix/blob/main/DOCUMENTATION.md#mkschemeattrs). + +### Overriding + +For convenience, it is possible to override parts of `stylix.base16Scheme` using +`stylix.override`. Anything that +[base16.nix](https://github.com/SenchoPens/base16.nix) accepts as override is +valid. + +When using both the Home Manager and NixOS modules, both the system overrides +and the user-provided one are used in the user configuration if +`stylix.base16Scheme` is not changed in the user config. If that is the case, +only the user override is used. + +## Fonts + +The default combination of fonts is: + +```nix +{ + stylix.fonts = { + serif = { + package = pkgs.dejavu_fonts; + name = "DejaVu Serif"; + }; + + sansSerif = { + package = pkgs.dejavu_fonts; + name = "DejaVu Sans"; + }; + + monospace = { + package = pkgs.dejavu_fonts; + name = "DejaVu Sans Mono"; + }; + + emoji = { + package = pkgs.noto-fonts-emoji; + name = "Noto Color Emoji"; + }; + }; +} +``` + +These can be changed as you like. + +To make things look more uniform, you could replace the serif font with +the sans-serif font: + +```nix +{ + stylix.fonts.serif = config.stylix.fonts.sansSerif; +} +``` + +Or even choose monospace for everything: + +```nix +{ + stylix.fonts = { + serif = config.stylix.fonts.monospace; + sansSerif = config.stylix.fonts.monospace; + emoji = config.stylix.fonts.monospace; + }; +} +``` + +## Multi-user configurations + +For those apps which are configured through Home Manager, Stylix allows you to +choose a different theme for each user. This can be done by setting the theme +within Home Manager for that user rather than at the system level. + +By default, all users follow the system theme. This can be turned off by +setting `stylix.homeManagerIntegration.followSystem = false`, in which case you +must explicitly set a theme for each user. Setting that option is not required +just to be able to override an individual theme. + +If you would like to disable all Home Manager activity for a user, you can set +`stylix.homeManagerIntegration.autoImport = false`, then manually import the +Home Manager module for the users for which it should be enabled. + +Note that if the wallpaper image for a user is different to the rest of the +system, a separate theme will always be generated for them, even though their +`base16Scheme` option has not been overridden. If you want that user to follow +the system theme while having a different wallpaper, you will need to manually +copy the system theme into their configuration. (This behaviour is necessary as +otherwise it would be impossible to use a generated theme for a user while +having a manually created theme for the rest of the system.) + +## Turning targets on and off + +In Stylix terms, a target is anything which can have colors, fonts or a +wallpaper applied to it. Each module in this repository should correspond to a +target of the same name. + +Each target has an option like `stylix.targets.«target».enable` to turn its +styling on or off. Normally, it's turned on automatically when the target is +installed. You can set `stylix.autoEnable = false` to opt out of this +behaviour, in which case you'll need to manually enable each target you want to +be styled. + +Targets are different between Home Manager and NixOS, and sometimes available +in both cases. If both are available, it is always correct to enable both. +The reference pages have a list of targets for [NixOS](options/nixos.md) and +[Home Manager](options/hm.md) respectively. diff --git a/docs/src/installation.md b/docs/src/installation.md new file mode 100644 index 00000000..d30152da --- /dev/null +++ b/docs/src/installation.md @@ -0,0 +1,129 @@ +# Installation + +## NixOS + +You can install Stylix into your NixOS configuration using [Flakes][nix-flakes]. +This will provide theming for system level programs such as bootloaders, splash +screens, and display managers. + +```nix +{ + inputs = { + nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable"; + stylix.url = "github:danth/stylix"; + }; + + outputs = { nixpkgs, stylix, ... }: { + nixosConfigurations."«hostname»" = nixpkgs.lib.nixosSystem { + system = "x86_64-linux"; + modules = [ stylix.nixosModules.stylix ./configuration.nix ]; + }; + }; +} +``` +Minimal `flake.nix` for a NixOS configuration. + +Many applications cannot be configured system wide, so Stylix will also need +[Home Manager][nix-hm] to be able to change their settings within your home +directory. + +[Installing Home Manager as a NixOS module](https://nix-community.github.io/home-manager/index.html#sec-install-nixos-module) +is highly recommended if you don't use it already. This will combine it with +your existing configuration, so you don't need to run any extra commands when +you rebuild, and the theme you set in NixOS will automatically be used for Home +Manager too. + +When Stylix is installed to a NixOS configuration, it will automatically set up +its Home Manager modules if it detects that Home Manager is available. You can +theoretically use it without installing Home Manager, however most features +will be unavailable. + +## nix-darwin + +You can install Stylix intor your nix-darwin configuration in a similar fashion +to NixOS via [Flakes][nix-flakes]. + +```nix +{ + inputs = { + darwin = { + url = "github:LnL7/nix-darwin"; + inputs.nixpkgs.follows = "nixpkgs"; + }; + nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable"; + stylix.url = "github:danth/stylix"; + }; + + outputs = { darwin, nixpkgs, stylix, ... }: { + darwinConfigurations."«hostname»" = darwin.lib.darwinSystem { + system = "aarch64-darwin"; + modules = [ stylix.darwinModules.stylix ./configuration.nix ]; + }; + }; +} +``` +Minimal `flake.nix` for a nix-darwin configuration. + +While this won't have an effect on the looks of MacOS, since we don't have the +controls to theme it like we do NixOS, it will automatically set up the [Home +Manager][nix-hm] modules for you. + +## Home Manager + +If you would prefer to use the standalone version of Home Manager, you can +install Stylix directly into your Home Manager configuration instead. This +could be useful if you are on another operating system, or a machine which +is managed by someone else. + + +```nix +{ + inputs = { + nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable"; + home-manager.url = "github:nix-community/home-manager"; + stylix.url = "github:danth/stylix"; + }; + + outputs = { nixpkgs, home-manager, stylix, ... }: { + homeConfigurations."«username»" = home-manager.lib.homeManagerConfiguration { + pkgs = nixpkgs.legacyPackages.x86_64-linux; + modules = [ stylix.nixosModules.stylix ./home.nix ]; + }; + }; +} +``` +Minimal `flake.nix` for a Home Manager configuration. + +If you choose to use both NixOS and Home Manager but configure them separately, +you will need to copy the settings described below into both of your +configurations, as keeping them separate means that they cannot follow each +other automatically. + +## Without flakes + +If you haven't enabled flakes yet or don't want to use this feature, `default.nix` +re-exports all the flake outputs, without requiring flakes to be enabled. This means +that once you have a copy of this repo, using either a local checkout, +[niv](https://github.com/nmattia/niv), or any other method, you can import it to +get the NixOS module as the `nixosModules.stylix` attribute and the Home Manager +module as the `homeManagerModules.stylix` attribute. + +```nix +let + stylix = pkgs.fetchFromGitHub { + owner = "danth"; + repo = "stylix"; + rev = "..."; + sha256 = "..."; + }; +in { + imports = [ (import stylix).homeManagerModules.stylix ]; + + stylix.image = ./wallpaper.jpg; +} + +``` +Example usage of the Home Manager module without flakes. + +[nix-flakes]: https://nixos.wiki/wiki/Flakes +[nix-hm]: https://github.com/nix-community/home-manager diff --git a/docs/src/options/hm.md b/docs/src/options/hm.md new file mode 100644 index 00000000..99b63fef --- /dev/null +++ b/docs/src/options/hm.md @@ -0,0 +1,24 @@ +# Home Manager options + +The following options can only be set in a Home Manager configuration. + +If you combined Home Manager with your NixOS configuration, write these +options within a Home Manager section, either for all users: + +```nix +home-manager.sharedModules = [{ + stylix.targets.xyz.enable = false; +}]; +``` + +Or for a specific user: + +```nix +home-manager.users.«name» = { + stylix.targets.xyz.enable = false; +}; +``` + +[Read more about per-user themes.](../configuration.md#multi-user-configurations) + + diff --git a/docs/src/options/nixos.md b/docs/src/options/nixos.md new file mode 100644 index 00000000..bfb9de37 --- /dev/null +++ b/docs/src/options/nixos.md @@ -0,0 +1,5 @@ +# NixOS options + +The following options can only be set in a NixOS configuration. + + diff --git a/FAQ.md b/docs/src/tricks.md similarity index 87% rename from FAQ.md rename to docs/src/tricks.md index e7ff5dbc..5b1a6b6c 100644 --- a/FAQ.md +++ b/docs/src/tricks.md @@ -1,8 +1,6 @@ -# FAQ +# Tips and tricks -## NixOS Stylix Tricks - -### Adjusting the brightness and contrast of a background image +## Adjusting the brightness and contrast of a background image If you want to use a background image for your desktop but find it too bright or distracting, you can use the `imagemagick` package to dim the image, or adjust its brightness and contrast to suit your preference. @@ -22,3 +20,4 @@ in ${pkgs.imagemagick}/bin/convert "${inputImage}" -brightness-contrast ${brightness},${contrast} -fill ${fillColor} $out ''; } +``` diff --git a/flake.lock b/flake.lock index 3423caf3..5ea87a50 100644 --- a/flake.lock +++ b/flake.lock @@ -20,27 +20,6 @@ "type": "github" } }, - "coricamu": { - "inputs": { - "nixpkgs": [ - "nixpkgs" - ], - "utils": "utils" - }, - "locked": { - "lastModified": 1677749800, - "narHash": "sha256-xIqxDr4fkOA5R4OudbQoUMS8xvPJNCyGfqugENutSP4=", - "owner": "danth", - "repo": "coricamu", - "rev": "40db414609dc6d72319987d3e9d7b56fe405c28f", - "type": "github" - }, - "original": { - "owner": "danth", - "repo": "coricamu", - "type": "github" - } - }, "flake-compat": { "flake": false, "locked": { @@ -62,14 +41,14 @@ "nixpkgs": [ "nixpkgs" ], - "utils": "utils_2" + "utils": "utils" }, "locked": { - "lastModified": 1658924727, - "narHash": "sha256-Fhh9FK9CvuCLxG1WkWJPoendDeXKI4gHYTfezo1n2Zg=", + "lastModified": 1680000368, + "narHash": "sha256-TlgC4IJ7aotynUdkGRtaAVxquaiddO38Ws89nB7VGY8=", "owner": "nix-community", "repo": "home-manager", - "rev": "0e2f7876d2f2ae98a67d89a8bef8c49332aae5af", + "rev": "765e4007b6f9f111469a25d1df6540e8e0ca73a6", "type": "github" }, "original": { @@ -80,11 +59,11 @@ }, "nixpkgs": { "locked": { - "lastModified": 1659102345, - "narHash": "sha256-Vbzlz254EMZvn28BhpN8JOi5EuKqnHZ3ujFYgFcSGvk=", + "lastModified": 1679793451, + "narHash": "sha256-JafTtgMDATE8dZOImBhWMA9RCn9AP8FVOpN+9K/tTlg=", "owner": "NixOS", "repo": "nixpkgs", - "rev": "11b60e4f80d87794a2a4a8a256391b37c59a1ea7", + "rev": "0cd51a933d91078775b300cf0f29aa3495231aa2", "type": "github" }, "original": { @@ -97,7 +76,6 @@ "root": { "inputs": { "base16": "base16", - "coricamu": "coricamu", "flake-compat": "flake-compat", "home-manager": "home-manager", "nixpkgs": "nixpkgs" @@ -105,26 +83,11 @@ }, "utils": { "locked": { - "lastModified": 1642700792, - "narHash": "sha256-XqHrk7hFb+zBvRg6Ghl+AZDq03ov6OshJLiSWOoX5es=", + "lastModified": 1676283394, + "narHash": "sha256-XX2f9c3iySLCw54rJ/CZs+ZK6IQy7GXNY4nSOyu2QG4=", "owner": "numtide", "repo": "flake-utils", - "rev": "846b2ae0fc4cc943637d3d1def4454213e203cba", - "type": "github" - }, - "original": { - "owner": "numtide", - "repo": "flake-utils", - "type": "github" - } - }, - "utils_2": { - "locked": { - "lastModified": 1653893745, - "narHash": "sha256-0jntwV3Z8//YwuOjzhV2sgJJPt+HY6KhU7VZUL0fKZQ=", - "owner": "numtide", - "repo": "flake-utils", - "rev": "1ed9fb1935d260de5fe1c2f7ee0ebaae17ed2fa1", + "rev": "3db36a8b464d0c4532ba1c7dda728f4576d6d073", "type": "github" }, "original": { diff --git a/flake.nix b/flake.nix index 15d2b3b2..708edd13 100644 --- a/flake.nix +++ b/flake.nix @@ -7,10 +7,6 @@ }; # Used for documentation - coricamu = { - url = "github:danth/coricamu"; - inputs.nixpkgs.follows = "nixpkgs"; - }; home-manager = { url = "github:nix-community/home-manager"; inputs.nixpkgs.follows = "nixpkgs"; @@ -23,21 +19,23 @@ }; outputs = - { nixpkgs, base16, coricamu, self, ... }@inputs: - with nixpkgs.lib; - - let - docsOutputs = coricamu.lib.generateFlakeOutputs { - outputName = "docs"; - modules = [ ./docs/default.nix ]; - specialArgs = { inherit inputs; }; - }; - - in recursiveUpdate docsOutputs { - packages = genAttrs [ "aarch64-darwin" "aarch64-linux" "i686-linux" "x86_64-darwin" "x86_64-linux" ] ( + { nixpkgs, base16, self, ... }@inputs: + { + packages = nixpkgs.lib.genAttrs [ + "aarch64-darwin" + "aarch64-linux" + "i686-linux" + "x86_64-darwin" + "x86_64-linux" + ] ( system: let pkgs = nixpkgs.legacyPackages.${system}; in { + docs = import ./docs { + inherit pkgs inputs; + inherit (nixpkgs) lib; + }; + palette-generator = pkgs.callPackage ./palette-generator { }; } ); diff --git a/modules/bemenu/hm.nix b/modules/bemenu/hm.nix index 8d55f3f6..686845da 100644 --- a/modules/bemenu/hm.nix +++ b/modules/bemenu/hm.nix @@ -5,11 +5,22 @@ with config.stylix.fonts; { options.stylix.targets.bemenu = { enable = config.lib.stylix.mkEnableTarget "bemenu" true; + fontSize = lib.mkOption { + description = lib.mdDoc '' + Font size used for bemenu. + ''; type = with lib.types; nullOr int; default = sizes.popups; }; # optional argument - alternate = lib.mkOption { type = lib.types.bool; default = false; }; + + alternate = lib.mkOption { + description = lib.mdDoc '' + Whether to use alternating colours. + ''; + type = lib.types.bool; + default = false; + }; }; config = lib.mkIf config.stylix.targets.bemenu.enable { @@ -27,10 +38,8 @@ with config.stylix.fonts; "--nf '${base05}'" "--scb '${base01}'" "--scf '${base03}'" - # Alternating colours, currently set to match primary. Adding a module option to enable or disable alternating in Stylix could be useful "--ab '${if alternate then base00 else base01}'" "--af '${if alternate then base04 else base05}'" - "--fn '${sansSerif.name} ${lib.optionalString (fontSize != null) (builtins.toString fontSize)}'" ]; }; diff --git a/modules/gnome/nixos.nix b/modules/gnome/nixos.nix index 16a1247f..987d0511 100644 --- a/modules/gnome/nixos.nix +++ b/modules/gnome/nixos.nix @@ -7,7 +7,7 @@ let in { options.stylix.targets.gnome.enable = lib.mkOption { - description = "Whether to style GNOME"; + description = lib.mdDoc "Whether to style GNOME"; type = lib.types.bool; default = config.stylix.autoEnable && config.services.xserver.desktopManager.gnome.enable; diff --git a/modules/grub/nixos.nix b/modules/grub/nixos.nix index 7b985be5..21825341 100644 --- a/modules/grub/nixos.nix +++ b/modules/grub/nixos.nix @@ -27,7 +27,7 @@ in { enable = config.lib.stylix.mkEnableTarget "GRUB" true; useImage = lib.mkOption { - description = "Whether to use your wallpaper image as the GRUB background."; + description = lib.mdDoc "Whether to use your wallpaper image as the GRUB background."; type = lib.types.bool; default = false; }; diff --git a/modules/gtk/hm.nix b/modules/gtk/hm.nix index 91f8aef4..a75bd50f 100644 --- a/modules/gtk/hm.nix +++ b/modules/gtk/hm.nix @@ -21,9 +21,8 @@ in { "all GTK3, GTK4 and Libadwaita apps" true; extraCss = mkOption { - description = '' - Extra code added to gtk-3.0/gtk.css - and gtk-4.0/gtk.css. + description = mdDoc '' + Extra code added to `gtk-3.0/gtk.css` and `gtk-4.0/gtk.css`. ''; type = types.lines; default = ""; diff --git a/modules/kitty/hm.nix b/modules/kitty/hm.nix index 481a1130..1e7b0183 100644 --- a/modules/kitty/hm.nix +++ b/modules/kitty/hm.nix @@ -14,7 +14,15 @@ let in { options.stylix.targets.kitty = { enable = config.lib.stylix.mkEnableTarget "Kitty" true; - variant256Colors = lib.mkOption { type = lib.types.bool; default = false; }; + + variant256Colors = lib.mkOption { + description = lib.mdDoc '' + Whether to use the [256-color variant](https://github.com/kdrag0n/base16-kitty#256-color-variants) + rather than the default combination of colors. + ''; + type = lib.types.bool; + default = false; + }; }; config = lib.mkIf cfg.enable { diff --git a/modules/plymouth/nixos.nix b/modules/plymouth/nixos.nix index 80688bcc..22084a34 100644 --- a/modules/plymouth/nixos.nix +++ b/modules/plymouth/nixos.nix @@ -48,14 +48,14 @@ in { enable = config.lib.stylix.mkEnableTarget "the Plymouth boot screen" true; logo = mkOption { - description = '' + description = mdDoc '' Logo to be used on the boot screen. This defaults to the NixOS logo, but you could set it to your OEM logo if it suits the theme. ''; type = with types; either path package; - defaultText = literalDocBook "NixOS snowflake"; + defaultText = literalMD "NixOS snowflake"; default = pkgs.fetchurl { url = "https://raw.githubusercontent.com/NixOS/nixos-artwork/master/logo/nix-snowflake.svg"; # Reduce size @@ -69,14 +69,14 @@ in { }; blackBackground = mkOption { - description = '' + description = mdDoc '' Whether to use a black background rather than a theme colour. This looks good in combination with systemd-boot, as it means that the background colour doesn't change throughout the boot process. ''; type = types.bool; - defaultText = literalDocBook "true if systemd-boot is enabled"; + defaultText = literalMD "`true` if systemd-boot is enabled"; default = config.boot.loader.systemd-boot.enable; }; }; diff --git a/modules/swaylock/hm.nix b/modules/swaylock/hm.nix index 21bde6c8..d4adc6dd 100644 --- a/modules/swaylock/hm.nix +++ b/modules/swaylock/hm.nix @@ -14,7 +14,7 @@ in { options.stylix.targets.swaylock = { enable = config.lib.stylix.mkEnableTarget "Swaylock" true; useImage = lib.mkOption { - description = '' + description = lib.mdDoc '' Whether to use your wallpaper image for the Swaylock background. If this is disabled, a plain color will be used instead. ''; diff --git a/stylix/darwin/default.nix b/stylix/darwin/default.nix index 2767559f..715e7bbe 100644 --- a/stylix/darwin/default.nix +++ b/stylix/darwin/default.nix @@ -14,7 +14,7 @@ in { options.stylix.homeManagerIntegration = { followSystem = lib.mkOption { - description = '' + description = lib.mdDoc '' When this option is true, Home Manager will follow the system theme by default, rather than requiring a theme to be set. @@ -26,7 +26,7 @@ in { }; autoImport = lib.mkOption { - description = '' + description = lib.mdDoc '' Whether to enable Stylix automatically for every user. This only applies to users for which Home Manager is set up within the @@ -34,8 +34,8 @@ in { ''; type = lib.types.bool; default = options ? home-manager; - defaultText = lib.literalDocBook '' - true when Home Manager is present. + defaultText = lib.literalMD '' + `true` when Home Manager is present. ''; }; }; diff --git a/stylix/fonts.nix b/stylix/fonts.nix index 7c14b26b..90a21397 100644 --- a/stylix/fonts.nix +++ b/stylix/fonts.nix @@ -10,12 +10,12 @@ let fontType = types.submodule { options = { package = mkOption { - description = "Package providing the font."; + description = mdDoc "Package providing the font."; type = types.package; }; name = mkOption { - description = "Name of the font within the package."; + description = mdDoc "Name of the font within the package."; type = types.str; }; }; @@ -24,7 +24,7 @@ let in { options.stylix.fonts = { serif = mkOption { - description = "Serif font."; + description = mdDoc "Serif font."; type = fontType; default = fromOs [ "fonts" "serif" ] { package = pkgs.dejavu_fonts; @@ -33,7 +33,7 @@ in { }; sansSerif = mkOption { - description = "Sans-serif font."; + description = mdDoc "Sans-serif font."; type = fontType; default = fromOs [ "fonts" "sansSerif" ] { package = pkgs.dejavu_fonts; @@ -42,7 +42,7 @@ in { }; monospace = mkOption { - description = "Monospace font."; + description = mdDoc "Monospace font."; type = fontType; default = fromOs [ "fonts" "monospace" ] { package = pkgs.dejavu_fonts; @@ -51,7 +51,7 @@ in { }; emoji = mkOption { - description = "Emoji font."; + description = mdDoc "Emoji font."; type = fontType; default = fromOs [ "fonts" "emoji" ] { package = pkgs.noto-fonts-emoji; @@ -61,7 +61,7 @@ in { sizes = { desktop = mkOption { - description = '' + description = mdDoc '' The font size used in window titles/bars/widgets elements of the desktop. ''; @@ -70,7 +70,7 @@ in { }; applications = mkOption { - description = '' + description = mdDoc '' The font size used by applications. ''; type = types.ints.unsigned; @@ -78,7 +78,7 @@ in { }; terminal = mkOption { - description = '' + description = mdDoc '' The font size for terminals/text editors. ''; type = types.ints.unsigned; @@ -86,7 +86,7 @@ in { }; popups = mkOption { - description = '' + description = mdDoc '' The font size for notifications/popups and in general overlay elements of the desktop. ''; diff --git a/stylix/nixos/default.nix b/stylix/nixos/default.nix index 8aef53c4..b2a5ae06 100644 --- a/stylix/nixos/default.nix +++ b/stylix/nixos/default.nix @@ -14,7 +14,7 @@ in { options.stylix.homeManagerIntegration = { followSystem = lib.mkOption { - description = '' + description = lib.mdDoc '' When this option is true, Home Manager will follow the system theme by default, rather than requiring a theme to be set. @@ -26,7 +26,7 @@ in { }; autoImport = lib.mkOption { - description = '' + description = lib.mdDoc '' Whether to enable Stylix automatically for every user. This only applies to users for which Home Manager is set up within the @@ -34,8 +34,8 @@ in { ''; type = lib.types.bool; default = options ? home-manager; - defaultText = lib.literalDocBook '' - true when Home Manager is present. + defaultText = lib.literalMD '' + `true` when Home Manager is present. ''; }; }; diff --git a/stylix/palette.nix b/stylix/palette.nix index c8ef3939..89da9666 100644 --- a/stylix/palette.nix +++ b/stylix/palette.nix @@ -52,7 +52,7 @@ in { polarity = mkOption { type = types.enum [ "either" "light" "dark" ]; default = fromOs [ "polarity" ] "either"; - description = '' + description = mdDoc '' Use this option to force a light or dark theme. By default we will select whichever is ranked better by the genetic @@ -63,7 +63,7 @@ in { image = mkOption { type = types.coercedTo types.package toString types.path; - description = '' + description = mdDoc '' Wallpaper image. This is set as the background of your desktop environment, if possible, @@ -91,7 +91,7 @@ in { }; base16Scheme = mkOption { - description = '' + description = mdDoc '' A scheme following the base16 standard. This can be a path to a file, a string of YAML, or an attribute set. @@ -101,7 +101,7 @@ in { if args ? "osConfig" && cfg.image != args.osConfig.stylix.image then generatedScheme else fromOs [ "base16Scheme" ] generatedScheme; - defaultText = literalDocBook '' + defaultText = literalMD '' The colors used in the theming. Those are automatically selected from the background image by default, @@ -110,7 +110,7 @@ in { }; override = mkOption { - description = '' + description = mdDoc '' An override that will be applied to stylix.base16Scheme when generating lib.stylix.colors. diff --git a/stylix/target.nix b/stylix/target.nix index 46b75066..772b955e 100644 --- a/stylix/target.nix +++ b/stylix/target.nix @@ -6,7 +6,7 @@ let fromOs = import ./fromos.nix { inherit lib args; }; in { options.stylix.autoEnable = mkOption { - description = "Whether to automatically enable styling for installed targets."; + description = mdDoc "Whether to automatically enable styling for installed targets."; type = types.bool; default = fromOs [ "autoEnable" ] true; }; @@ -25,14 +25,14 @@ in { autoEnable: mkOption { - description = "Whether to style ${humanName}."; + description = mdDoc "Whether to style ${humanName}."; type = types.bool; # We can't substitute the target name into this description because some # don't make sense: "if the desktop background using Feh is installed" - defaultText = literalDocBook '' - true if stylix.autoEnable == true - and the target is installed, otherwise false. + defaultText = literalMD '' + `true` if `stylix.autoEnable == true` and the target is installed, + otherwise `false`. ''; default = config.stylix.autoEnable && autoEnable;