Mirrors/stylix
2
0
Fork 0
mirror of https://github.com/danth/stylix synced 2024-11-21 19:53:10 +00:00
Code Issues Projects Releases Packages Wiki Activity

Convert documentation to mdBook 📝 🔨

Browse source
This commit is contained in:
Daniel Thwaites 2023-03-29 00:54:14 +01:00
parent e626c4e54e
commit a3f9fa981b
No known key found for this signature in database
GPG key ID: D8AFC4BF05670F9D
26 changed files with 557 additions and 523 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

56
.github/workflows/docs.yml vendored
View file

@ -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

326
README.md
View file

@ -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 ];
};
};
}
```
<small>Minimal `flake.nix` for a NixOS configuration.</small>
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 ];
};
};
}
```
<small>Minimal `flake.nix` for a Home Manager configuration.</small>
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;
}
```
<small>Example usage of the Home Manager module without flakes.</small>
## 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).

9
docs/book.toml Normal file
View file

@ -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}"

106
docs/default.nix
View file

@ -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
'';
}

27
docs/hm_header.xml
View file

@ -1,27 +0,0 @@
<para>
The following options can only be set in a Home Manager configuration.
</para>
<para>
If you combined Home Manager with your NixOS configuration, write these
options within a Home Manager section, either for all users:
<programlisting language="nix"><![CDATA[
home-manager.sharedModules = [{
stylix.targets.xyz.enable = false;
}];
]]></programlisting>
Or for a specific user:
<programlisting language="nix"><![CDATA[
home-manager.users.«name» = {
stylix.targets.xyz.enable = false;
};
]]></programlisting>
<link
xmlns:xlink="http://www.w3.org/1999/xlink"
xlink:href="https://danth.github.io/stylix#multi-userconfigurations">
Read more about per-user themes.
</link>
</para>

3
docs/nixos_header.xml
View file

@ -1,3 +0,0 @@
<para>
The following options can only be set in a NixOS configuration.
</para>

12
docs/src/SUMMARY.md Normal file
View file

@ -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)

189
docs/src/configuration.md Normal file
View file

@ -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.

129
docs/src/installation.md Normal file
View file

@ -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 ];
};
};
}
```
<small>Minimal `flake.nix` for a NixOS configuration.</small>
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 ];
};
};
}
```
<small>Minimal `flake.nix` for a nix-darwin configuration.</small>
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 ];
};
};
}
```
<small>Minimal `flake.nix` for a Home Manager configuration.</small>
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;
}
```
<small>Example usage of the Home Manager module without flakes.</small>
[nix-flakes]: https://nixos.wiki/wiki/Flakes
[nix-hm]: https://github.com/nix-community/home-manager

24
docs/src/options/hm.md Normal file
View file

@ -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)
<!-- Auto-generated documentation will be added below. -->

5
docs/src/options/nixos.md Normal file
View file

@ -0,0 +1,5 @@
# NixOS options
The following options can only be set in a NixOS configuration.
<!-- Auto-generated documentation will be added below. -->

7
FAQ.md → docs/src/tricks.md
View file

@ -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
'';
}
```

57
flake.lock
View file

@ -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": {

30
flake.nix
View file

@ -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 { };
}
);

15
modules/bemenu/hm.nix
View file

@ -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)}'"
];
};

2
modules/gnome/nixos.nix
View file

@ -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;

2
modules/grub/nixos.nix
View file

@ -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;
};

5
modules/gtk/hm.nix
View file

@ -21,9 +21,8 @@ in {
"all GTK3, GTK4 and Libadwaita apps" true;
extraCss = mkOption {
description = ''
Extra code added to <literal>gtk-3.0/gtk.css</literal>
and <literal>gtk-4.0/gtk.css</literal>.
description = mdDoc ''
Extra code added to `gtk-3.0/gtk.css` and `gtk-4.0/gtk.css`.
'';
type = types.lines;
default = "";

10
modules/kitty/hm.nix
View file

@ -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 {

8
modules/plymouth/nixos.nix
View file

@ -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 "<literal>true</literal> if systemd-boot is enabled";
defaultText = literalMD "`true` if systemd-boot is enabled";
default = config.boot.loader.systemd-boot.enable;
};
};

2
modules/swaylock/hm.nix
View file

@ -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.
'';

8
stylix/darwin/default.nix
View file

@ -14,7 +14,7 @@ in {
options.stylix.homeManagerIntegration = {
followSystem = lib.mkOption {
description = ''
description = lib.mdDoc ''
When this option is <literal>true</literal>, 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 ''
<literal>true</literal> when Home Manager is present.
defaultText = lib.literalMD ''
`true` when Home Manager is present.
'';
};
};

20
stylix/fonts.nix
View file

@ -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.
'';

8
stylix/nixos/default.nix
View file

@ -14,7 +14,7 @@ in {
options.stylix.homeManagerIntegration = {
followSystem = lib.mkOption {
description = ''
description = lib.mdDoc ''
When this option is <literal>true</literal>, 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 ''
<literal>true</literal> when Home Manager is present.
defaultText = lib.literalMD ''
`true` when Home Manager is present.
'';
};
};

10
stylix/palette.nix
View file

@ -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.

10
stylix/target.nix
View file

@ -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 ''
<literal>true</literal> if <literal>stylix.autoEnable == true</literal>
and the target is installed, otherwise <literal>false</literal>.
defaultText = literalMD ''
`true` if `stylix.autoEnable == true` and the target is installed,
otherwise `false`.
'';
default = config.stylix.autoEnable && autoEnable;