SenchoPens / base16.nix

What's base16 and base16.nix?

• base16 is a theming standard by which hundreds of colorschemes and application configuration templates 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:

• 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 / nix.

Nonfeatures

• 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! 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 and EJS.

👀 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 the nord scheme (home-manager module works the same way).

Import and set the scheme (step 1/2)

In your NixOS configuration directory:

flake.nix

{ inputs = {
  # Add base16.nix, base16 schemes and
  # zathura and vim templates to the flake inputs.
  base16.url = github:SenchoPens/base16.nix;
  base16.inputs.nixpkgs.follows = "nixpkgs";

  base16-schemes = {
    url = github:base16-project/base16-schemes;
    flake = false;
  };

  base16-zathura = {
    url = github:haozeke/base16-zathura;
    flake = false;
  };

  base16-vim = {
    url = github:base16-project/base16-vim;
    flake = false;
  };
  ...
};
outputs = { self, ... } @ inputs {
  ...
    nixosSystem {
      modules = [
        # import the base16.nix module
        base16.nixosModule
        # 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;
      };
      ...
    };
  ...
};
... }

Theme (step 2/2)

Now that config.scheme is set, we can use it like a function to create themes from templates.

theming.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 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;
        inherit red green yellow blue cyan magenta;
      };
    in {
      primary = { background = base00; foreground = base07; };
      cursor = { text = base02; cursor = base07; };
      normal = default; bright = default; dim = default;
    };
}

That's all, we themed 3 applications!

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.

🍳 How To

📚 Documentation

Consult the DOCUMENTATION.md to learn about every feature in detail and see how base16.nix works underhood.

🤍 Repositories that use base16.nix

NixOS modules:

• Stylix — System-wide colorscheming and typography for NixOS.
• tmux-flake — a flake that configures tmux.

Configs by:

• pborzenkov
• nryz
• MoritzBoehme
• IllustratedMan-code
• Lyndeno

Please feel free to list your repository above, it will make my day :)

🎎 Alternatives

• base16-nix by @atpotts and its forks, notably base16-nix by @AlukardBF and base16-nix by @lukebfox.

• nix-colors by @misterio. Thanks for the competition spirit! :)) And for the nix-wallpaper function, with which the preview GIF was generated.

  differences:

  Roughly nix-colors can be viewed as an alternative to base16.nix + Stylix, without the mustache template support:

  base16.nix supports the existing ≥ 80 mustache templates, nix-colors does not — instead there are ≥ 4 contributed nix functions and planned (at the time of writing) support for translation from mustache templates to nix functions. Stylix has ≥ 10 Stylix theming nix functions.

  You can generate base16 scheme from a wallpaper — in nix-colors via 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.

• theme-base16 by @rycee.

☎️ Help

If you need any help, feel free to open an issue or contact me via email or telegram (my contacts are here).

💙 Acknowledgments

Thanks to:

• @balsoft for nixos-config, which inspired this library;
• @cab404 for Genix7000 — icon generator for nix projects;
• @chriskempson for creating base16 and @belak and base16-project team for maintaining it;
• @mmanchkin for being a great support and mastermind behind all of this.

👩‍💻 Contributing

See CONTRIBUTING.md