diff --git a/README.md b/README.md index b4a703c..7db2688 100644 --- a/README.md +++ b/README.md @@ -1,78 +1,66 @@ -![logo](./logo.png) - -# base16.nix - -_1 configuration option, 16 colors_ +![logo](./logo.svg) ![demo](./demo.gif) -#### What's base16? +#### What's base16 and base16.nix? -base16 is a standard for specifying colorschemes and application -configuration templates, that produced a lot of templates and schemes -over the years. `base16.nix` makes using them in NixOS as easy as -possible, while retaining much flexibility. +- [base16](https://github.com/base16-project/base16) is a theming standard by + which hundreds of + [colorschemes](https://github.com/base16-project/base16-schemes) + and application configuration + [templates](https://github.com/base16-project/base16#template-repositories) + were made over the years. +- `base16.nix` is a **NixOS** / **home-manager** module and a library that + makes using base16 / base24 schemes and templates as **simple** as + possible, while leaving the user full **flexibility**. ### Features With `base16.nix`, you can: -- theme any application that has a base16 template in minimal amount of key strokes; -- use existing schemes, override them or create your own from scratch; - -This flake provides: -- a function to create a scheme attrset from a scheme, - that can further be used to create base16 (base24 is also supported) - themes from templates. -- a NixOS module, -- a home-manager module. +- use existing schemes, override them, write a new one in YAML / nix; +- theme any application with a base16 template in minimal amount of key strokes, + or write a new template in [mustache](https://mustache.github.io/) / nix. ### Nonfeatures -This project does not attempt to: -- aggregate schemes or templates, as you can discover most of them through - [base16 repository](https://github.com/chriskempson/base16) -- support EJS templates, which are part of the - [base16-builder/base16-builder](https://github.com/base16-builder/base16-builder) - repository, as it has been long time abandoned and almost all of the EJS templates - have mustache alternatives. +- `base16.nix` is simply a ultrasupermega convenient battle-tested + nix-y base16 standard implementation, **not a** _ricing_ engine — but if you want one, + please check out every r/unixporn admin's dream — [Stylix](https://github.com/danth/stylix)! built with `base16.nix`! +- `base16.nix` neither aggregates nor vendors schemes / templates to **keep data and logic separated**. +- No support for legacy template formats like + [Embedded Ruby](https://github.com/ntpeters/base16-template-converter) + and [EJS](https://github.com/base16-builder/base16-builder/issues/174). -## Module example (covers majority of use-cases) +## 👀 Module example (covers majority of use-cases) -In this example, we will use base16.nix as a NixOS module to theme -`zathura`, `neovim` and `alacritty` to use colors of -[eva scheme](https://github.com/kjakapat/eva-theme) +In this example, we will use `base16.nix` as a NixOS module to theme +`zathura`, `neovim` and `alacritty` to use the `nord` scheme in two steps — setup and theming. (home-manager module works the same way). -### Setup +### 1. Setup -- Open your NixOS configuration's `flake.nix` file. -- Optionally, open [base16 repository](https://github.com/chriskempson/base16#template-repositories) - to pick a scheme and templates you want to use, in this tutorial we already chose them. -- Add `base16.nix`, `eva` scheme and - [zathura](https://github.com/HaoZeke/base16-zathura) and - [vim](https://github.com/chriskempson/base16-vim) templates to the flake inputs. -- Import `base16.nix` module. -- Add `eva` scheme to config under `config.scheme` path. -- Import `theming.nix`, a file we will write in the next (and final) step. +In your configuration's `flake.nix`: `flake.nix` ```nix -inputs = { +{ inputs = { + # Add base16.nix, base16 schemes and + # zathura and vim templates to the flake inputs. base16.url = "/home/sencho/code/github.com/SenchoPens/base16.nix"; base16.inputs.nixpkgs.follows = "nixpkgs"; - base16-eva-scheme = { - url = github:kjakapat/base16-eva-scheme; + base16-schemes = { + url = github:base16-project/base16-schemes; flake = false; }; - base16-fzf = { - url = github:fnune/base16-fzf; + base16-zathura = { + url = github:haozeke/base16-zathura; flake = false; }; - base16-zathura = { - url = github:haozeke/base16-zathura; + base16-vim = { + url = github:base16-project/base16-vim; flake = false; }; ... @@ -81,11 +69,15 @@ outputs = { self, ... }@inputs { ... nixosSystem { modules = [ + # import the base16.nix module base16.nixosModule - { scheme = "${inputs.base16-eva-scheme}/eva.yaml"; } + # set system's scheme to nord by setting `config.scheme` + { scheme = "${inputs.base16-schemes}/nord.yaml"; } + # import `theming.nix`, we will write it in the next, final, step theming.nix ... ]; + # so you can use `inputs` in config files specialArgs = { inherit inputs; }; @@ -93,42 +85,41 @@ outputs = { self, ... }@inputs { }; ... }; -... +... } ``` -### Theming +### 2. Theming -- Theme `zathura`. - Now that `config.scheme` is set, we can use it like a function to - create a theme from a template. -- Theme `neovim` - more complex, but the principle is the same. -- Theme `alacritty`. home-manager doesn't provide an `extraConfig`, - but gives us `settings.colors` option of attrs type to set colors. - As alacritty expects colors to begin with '#', we use an attribute `withHashtag`. - Notice that we now use `config.scheme` as an attrset, and that this attrset, - besides from having attributes `base00`...`base0F`, has mnemonic attributes (`red`, etc.) - - read more on that in the next section. +Now that `config.scheme` is set, we can use it like a function to +create themes from templates. `theming.nix` ```nix { config, pkgs, inputs, ... }: { + # Theme zathura home-manager.users.sencho.programs.zathura.extraConfig = builtins.readFile (config.scheme inputs.base16-zathura); + # Theme `neovim` — more complex, but the principle is the same. home-manager.users.sencho.programs.neovim = { plugins = [ (pkgs.vimPlugins.base16-vim.overrideAttrs (old: let schemeFile = config.scheme inputs.base16-vim; in { patchPhase = ''cp ${schemeFile} colors/base16-scheme.vim''; } )) ]; extraConfig = '' - set termguicolors - colorscheme base16-scheme - set background=dark + set termguicolors background=dark let base16colorspace=256 + colorscheme base16-scheme ''; }; + # Theme `alacritty`. home-manager doesn't provide an `extraConfig`, + # but gives us `settings.colors` option of attrs type to set colors. + # As alacritty expects colors to begin with `#`, we use an attribute `withHashtag`. + # Notice that we now use `config.scheme` as an attrset, and that this attrset, + # besides from having attributes `base00`...`base0F`, has mnemonic attributes (`red`, etc.) - + # read more on that in the next section. home-manager.users.sencho.programs.alacritty.settings.colors = with config.scheme.withHashtag; let default = { black = base00; white = base07; @@ -144,28 +135,41 @@ outputs = { self, ... }@inputs { That's all, we themed 3 applications! -## Advanced examples and usage as a library +
-_Assuming you read the previous section._ +The attentive reader will notice that after setting `config.scheme` to a string, +we use it as a function (to theme `zathura` and `neovim`) +and as an attrset (to theme `alacritty`) — that's `base16.nix`' magic! +Read the **Documentation** section to see how it works. +-### All the ways to set `config.scheme`: +## 🍳 Cookbook + +### Setting `config.scheme` + +
-- Specifying a scheme by a yaml file: ```nix -config.scheme = "${inputs.base16-eva-scheme}/eva-dim.yaml"; +config.scheme = "${inputs.base16-schemes}/nord.yaml"; ``` -- Overriding a scheme. Now we need to explicitely use `mkSchemeAttrs` function - to use `override` field of the resulting scheme attrs: +
+ +Now we need to explicitly use `mkSchemeAttrs` function +to use the `override` field of the resulting scheme attrs: ```nix -config.scheme = (config.lib.base16.mkSchemeAttrs "${inputs.base16-eva-scheme}/eva-dim.yaml").override { +config.scheme = (config.lib.base16.mkSchemeAttrs "${inputs.base16-schemes}/nord.yaml").override { scheme = "Now it's my scheme >:]"; base00 = "000000"; # make background completely black }; ``` -- Specifying a scheme from scratch in Nix, - [source](https://code.balsoft.ru/balsoft/nixos-config/src/branch/master/modules/themes.nix) +
+ ```nix -{ +config.scheme = { slug = "balsoftheme"; scheme = "Theme by balsoft"; author = "balsoft"; base00 = "000000"; base01 = "333333"; base02 = "666666"; base03 = "999999"; base04 = "cccccc"; base05 = "ffffff"; base06 = "e6e6e6"; base07 = "e6e6e6"; @@ -173,44 +177,46 @@ config.scheme = (config.lib.base16.mkSchemeAttrs "${inputs.base16-eva-scheme}/ev base0C = "40bfbf"; base0D = "407fbf"; base0E = "7f40bf"; base0F = "bf40bf"; }; ``` +[source](https://code.balsoft.ru/balsoft/nixos-config/src/branch/master/modules/themes.nix) +
You can apply a template to a scheme without going through `config.scheme` option. -Example of theming `zathura` without `config.scheme` - by calling `mkSchemeAttrs`: +Example of theming `zathura` without `config.scheme` — by calling `mkSchemeAttrs`: ```nix home-manager.users.sencho.programs.zathura.extraConfig = - builtins.readFile (config.lib.base16.mkSchemeAttrs inputs.base16-eva-scheme inputs.base16-zathura); + builtins.readFile (config.lib.base16.mkSchemeAttrs inputs.base16-schemes inputs.base16-zathura); ``` or like this, without importing `base16.nix` as a module at all: ```nix home-manager.users.sencho.programs.zathura.extraConfig = - builtins.readFile (inputs.base16.lib.mkSchemeAttrs inputs.base16-eva-scheme inputs.base16-zathura); + builtins.readFile ((pkgs.callPackage inputs.base16.lib {}).mkSchemeAttrs inputs.base16-schemes inputs.base16-zathura); ``` -### More on mustache templates +
+ +Base16 template repositories often provide **multiple** templates. For example, [zathura](https://github.com/HaoZeke/base16-zathura) template repository -provides `default.mustache` and `recolor.mustache` templates (the latter will override the colors of the pdf itself). -By default, `base16.nix` will always use the `default.mustache` template, -so, if you want to use the `recolor` one, write this: +provides `default.mustache` **and** `recolor.mustache` templates +(the latter being used to color pdfs by the colorscheme along with the interface). +By default, `base16.nix` will use the `default.mustache` template, +so if you want to use e.g. the `recolor` one, write this: ```nix home-manager.users.sencho.programs.zathura.extraConfig = builtins.readFile (config.scheme { templateRepo = inputs.base16-zathura; target = "recolor"; }); ``` -or this: -```nix -home-manager.users.sencho.programs.zathura.extraConfig = - builtins.readFile (inputs.base16.lib.mkSchemeAttrs inputs.base16-eva-scheme - { templateRepo = inputs.base16-zathura; target = "recolor"; }); -``` +
-Now, suppose you like the `default.mustache`, but want to change the background from `base00` to `base01`. -You can use `override`: +Suppose you like the `default.mustache`, but want to **change** the background from `base00` to `base01`. +You can use the scheme's `override` method: ```nix home-manager.users.sencho.programs.zathura.extraConfig = builtins.readFile (config.scheme.override { @@ -218,7 +224,7 @@ home-manager.users.sencho.programs.zathura.extraConfig = } inputs.base16-zathura); ``` But, unfortunately, in this template it will not only change the `default-bg` color, but also `inputbar-bg`, -`notification-bg`, etc. Then we can copy-paste the template entirely and change what we want: +`notification-bg`, etc. All that's left is to copy-paste the template and change it how we want: ```nix home-manager.users.sencho.programs.zathura.extraConfig = builtins.readFile (config.scheme { template = '' @@ -231,57 +237,73 @@ home-manager.users.sencho.programs.zathura.extraConfig = ... ''); ``` +
+ +Given a scheme, which is **either** +- a path to a YAML file, +- a string in YAML format, +- an attrset with attributes `baseXX` and optionally `scheme` and `author`, + +returns a _scheme attrset_ with a ton of convenient color attributes: + +- **Most** importantly, every attribute from [the base16 standard](https://github.com/base16-project/base16/blob/main/builder.md#template-variables), +- Attributes `baseXX = baseXX-hex`, e.g. `base00 = "000000"`; +- `toList = [ base00 ... base0F ]`, e.g. for `config.console.colors`, +- mnemonic color names for `base08` — `base0F`: + ```nix + mnemonic = { + red = base08; + orange = base09; + yellow = base0A; + green = base0B; + cyan = base0C; + blue = base0D; + magenta = base0E; + brown = base0F; + }; + ``` + +Other cool stuff: +- `withHashtag` — a scheme with `#` prepended to colors. - meta attributes: `scheme-name` and `scheme`, `scheme-author` and `author`, `scheme-slug` and `slug` (used for filenames), -- `override` - a function with which you can override the colors (attributes `baseXX`), - and meta attributes (`scheme`, `slug` and `author`). -- `withHashtag` - a scheme with '#' prepended to colors. -- `__functor` - a magic attribute that calls `mkTheme` on call to scheme attrs, - and passes it the current scheme as `scheme` argument, and, - if an argument is a derivation or a flake input, it is passed to `mkTheme` as `templateRepo` argument. -- `outPath` - with it you can write `"${config.scheme}"` and get a path to a yaml file containing the current scheme. +- `override` — a function to override the colors (via `baseXX`) + and meta attributes (`scheme`, `slug` and `author`), see **Cookbook** section, +- `outPath` — so you can write `"${config.scheme}"` to get a yaml file path with the scheme. +- `__functor` — a magic attribute that calls `mkTheme` if you use _scheme attrs_ as a function: + it passes the scheme as `scheme` and the argument as `templateRepo` (if it's a derivation or a flake input), + otherwise it passes `argument // { scheme = `_scheme attrs_` }` -### `mkTheme` +Note: `∀ x . mkSchemeAttrs (mkSchemeAttrs x) == mkSchemeAttrs x` +
+ +Builds a theme file from a scheme and a template and returns its path. +If you don't supply `templateRepo`, then supply both `template` and `extension`. ```nix mkTheme = { @@ -303,8 +325,10 @@ mkTheme = { extension ? null, }: ``` +
+ Roughly nix-colors can be viewed as an alternative + to `base16.nix` + [Stylix](https://github.com/danth/stylix), + without the mustache template support: - `base16.nix` tries to have a rather minimalistic interface, exporting 1 - configuration option and 1 function, but provide a plenty of ergonomic - logic within, to give user a way to configure maximum amount of - applications with minimum effort, because I think that's the point - of base16 - you pick an ideal for you scheme, almost without making - compromises, and you want 99-100% of your applications to use this - scheme. - - So, the goal I was up to is not to provide a quick way to theme some popular - applications with some popular schemes, `nix-colors` with its libraries might do - that better, but to provide a general way to theme any application with any - scheme and to easily override it to your liking. With `base16.nix`, maybe you will - spend some more time on, say, generating a GTK theme, but you won't spend an - hour trying to figure out how to theme that one small not-so-popular app or how - to adjust a template a bit, or how to use a beautiful scheme you just found on - the internet, but with another orange color. - + `base16.nix` supports the existing + [≥ 80 mustache templates](https://github.com/base16-project/base16/blob/main/README.md#official-templates), + nix-colors does not — instead there are + [≥ 4 contributed nix functions](https://github.com/Misterio77/nix-colors/tree/308fe8855ee4c35347baeaf182453396abdbe8df/lib/contrib) + and planned (at the time of writing) support for translation from mustache templates to nix functions. + Stylix has [≥ 10 Stylix theming nix functions](https://github.com/danth/stylix/tree/master/modules). + + You can generate base16 scheme from a wallpaper — in nix-colors via + [flavours](https://github.com/Misterio77/flavours) + and in Stylix via home-made CIE-LAB colorspace Haskell genetic algorithm. + + Also, if you use nix-colors without it's nix functions, it does not depend on nixpkgs. +