Awesome

About

Base16 Universal Manager

Gets a base16 colorscheme the configured templates from the official repos and renders them out to the given locations It will use the levenstein distance to find the matching colorscheme from the supplied name.

Base16 themes

An architecture for building themes based on carefully chosen syntax highlighting using a base of sixteen colors. Base16 provides a set of guidelines detailing how to style syntax and how to code a builder for compiling Base16 schemes and templates.

Why another manager/builder?

Base16 themes look great and the fact that you can use them on a lot of different applications makes it easy to get a desktop configuration set up easealy that looks uniformly themed. I really like the idea of having theme colors and the templates for different applications separated.

The common workflow to set up a theme on your system looks like this in most cases:

Search for a theme you like
Scroll through the support list of supported applications to find all the ones you need
Download or build the theme files for every application
Copy them all in their respective places.
Restart or refresh every application

I found this pretty tedious to do, since I like to change my theme every now and then. This is where the need for a manager came up.

The idea: automate the complete workflow above. After setting up my configuration for the manager once I ideally want to run one command and have all my applicatins set-up and ready whith the theme I choose.

There are other projects that try to simplify this workflow, but I have had problems with them in the past and don't particulary like the designs. Setting a theme should not require me to download or build them all. It also should really set them, avoiding having to run a theme-setting script every time the application is started.

What Base16 Universal Manager is NOT

Even though this project builds the themes needed and could probably be expanded or used as a theme builder in the sense described in the official base16 guidelines, this is not what it is intended for. It is mainly aimed at users and not theme or template maintainers and desigend to only get and build the stuff the user really needs.

Similar projects

base16-shell A shell script to change your shell's default ANSI colors

I liked the idea, but it limits the use to command line applications. Also I found the script to be to slow on my system, which results in the colors of new terminals been changed about ~0.5s after start. In the meantime my terminal waits. There probably are usecases, where this is the better choice, but it was not what I was looking for.

base16-manager A command line tool to install base16 templates and set themes globally.

Even though this project aimed to provide the same funcionality, only very few applications are supported. Also it required me to download a lot of repos I will never use.

Installation

At the moment, you can only build and install this with go. You can install it directly or build it from source. I might provide packages for multiple linux distributions and pre-build binaries in the future.

Install directly

mkdir -p "$(go env GOPATH)/src"
go install github.com/pinpox/base16-universal-manager@latest

Get source and build manually

go get github.com/pinpox/base16-universal-manager
cd $GOPATH/src/github.com/pinpox/base16-universal-manager
go build

If you get errors on missing dependencies, install them as usual with go get.

Shell completions

fish shell completions: Add the completions/fish/base16-universal-manager.fish to ~/.config/fish/completions/

wget https://raw.githubusercontent.com/pinpox/base16-universal-manager/master/completions/fish/base16-universal-manager.fish -O ~/.config/fish/completions/base16-universal-manager.fish

Usage

To run, just execute the application without any command line flags. It will expect a config.yaml (example provided) in $XDG_CONFIG_HOME/.config/base16-universal-manager/ ($XDG_CONFIG_HOME defaults to ~/.config on *nix systems if unspecified) and renders all specified application templates with the selected colorscheme.

The following flags are planned and will be implemented soon:

usage: base16-universal-manager [<flags>]

Flags:
  --help             Show context-sensitive help (also try --help-long and --help-man).
  --update-list      Update the list of templates and colorschemes
  --clear-list       Delete local master list caches
  --clear-schemes    Delete local scheme caches
  --clear-templates  Delete local template caches
  --version          Show application version.

Configuration

GitHub Token (optional)

This program fetches data using the GitHub API. If you are not logged in, you might get blocked by the API's rate limiting

To increase the amout of allowed request, you can use personal access-token. Generate one here (Default options should be enough, just provide a name) and put it in your configuration file.

Putting the token in the configuration will automatically use it to make all requests as a registered user.

Configuration file

The configuration file specifies everything the program should do when run. It consists mainly of two parts:

General configuration values

Variable	Default	Explanation
GithubToken	set-your-token-here	see `GitHub Token (optinonal)`
Colorscheme	flat.yml	The colorscheme to use, uses local path if it contains a `/`
DryRun	false	Print the rendered files to stdout instead of saving them

The provided theme names, do not have to be exact. The Levenstein distance is used to calculate the best matching option. This is handy in case you only partly remember the name of a particular scheme, if you made a typo, or if you are just plain lazy.

Applications which you want to theme

The rest of the configuration are the application specific settings. It consists of a list of applications you want to use. Here is an example that would set up vim and i3 for you:

applications:
  i3:
    enabled: true
    hook: i3-msg 'restart'
    files:
      default:
        path: ~/.i3/i3_colors/
        mode: rewrite
      bar-colors:
        path: ~/.i3/i3_bar_colors/
        mode: rewrite
  vim:
    enabled: true
    files:
      default:
        path: ~/.vim/vim_colors/
        mode: rewrite

In this configuration we render the files called default and bar-colors from the base16-i3 templates repository to a to ~/.i3/i3_colors and ~/.i3/i3_bar_colors as well as the file called default from the base16-vim templates repo to ~/.vim/vim_colors. In the configurations of those applications you could then source that generated files.

Note: the convention for path is that if it ends with a / the rendered file will be placed in the directory path (it will be created if it doesn't exist). If it doesn't end with a / then path specifies exactly where the renered file should be placed. For example the above config will create/rewrite the following files:

~/.i3/i3_colors/default.config
~/.i3/i3_bar_colors/bar-colors.config
~/.vim/vim_colors/default.vim

Some applications have limitations in their configuration files and cannot source other configuration files. In that case rewriting the file won't help. That's why there is another mode called replace. Here's an example config demonstating this:

applications:
  alacritty:
    enabled: true
    files:
      default:
        path: ~/.config/alacritty/alacritty.yml
        mode: replace
        start_marker: "# <<<<<<<<<<"
        end_marker: "# >>>>>>>>>>"

With this configuration the rendered colors will be placed between the lines # <<<<<<<<<< and # >>>>>>>>>> in ~/.config/alacritty/alacritty.yml. Note that start_marker and end_marker are regexes and do not have to match exactly.

The hook variable can be set for every application configured. It allows to run a command after the files have been rendererd, e.g. to refersh the application in order to show the new values. In this example we use i3-msg 'restart' to restart the i3 window manager in place, thus reloading the colors.

Application examples

Base16 Universal Manager can support all applications listed in the base16 repo. For application-specific integration examples see the list in the wiki

Contributing

I hacked this project together in a weekend and it grew to be bigger than expected. The code quality could be way better and even though it is already pretty usable, you might find bugs or other issues. The documentation is work-in-progress.

Issues, bug-reports, pull requests or ideas for features and improvements are very welcome. Also it would be great if users of specific applications can document the usage of their respective templates, as I don't use all of them and can't/won't test the integration for every single application.