Home

Themer allows you to fastly swap variables in configurations by managing all files you specify in Themer's config.
You can update all colors inside your DE with single command, isn't this awesome?

How it works?

Themer consists of 2 parts:

• Themer config
• Themer block inside of your configuration files. It's a peice of code surrounded with comments, dynamically swapped by Themer.

Themer configuration contains 2 main parts: themes and files.

• themes contains sets of variables that can be used to build theme colors or something else.
• files contains list of files Themer will update when you decide to change your theme.

In order to manage different file types Themer needs to know where and how it should put variable inside of your configs, let's see how you tell Themer everything it needs.

Disclaimer

• Reading this documentation, you'll often see word colors used to represents variables inside theme. It's just how it started. Actually, Themer allows to do more than just listing theme colors as variables, you can inject fully functional peices of code dynamically by importing files for your blocks (you'll understand what it is if you'll read the rest) and many more!
• Besides reading this Wiki, you may find easier to just read the config. If you've already installed a Themer, you can find an example config at ~/.config/themer/config.yml

Configuration

The first place you should check after installing Themer is ~/.config/themer. You will find config.yml file, this is the Themer's config.

Themes config

Themes configuration block may contain any amout of objects that contain any amout of fields. Object name is the theme name, and the entries inside it are the variables for the theme.

Let's see an example:

themes:
   dark:
     background: "#000000"
     foreground: "#ffffff"

Themes contains a theme named dark. dark theme contains background and foreground variables that represent colors of the theme.

Note: varaibles might be anything, not only colors.

Note: if you're using hex, put it in quotes, since # symbol will be treated as comment

❗ You can set any name for the variable except vars and name. The reason is explained on the Custom Block wiki page.

Files config

One of the questions you may ask yourself when reading the description of the project may be

"How Themer can manage different configuration files at once? They all have different formats!"

This is fair, so you've got to help themer a bit. Firstly, you need to put somewhere 2 comment lines inside of the configuration file:

...your config goes here...
# THEMER
# THEMER_END
...your config continues here...

Note: comment symbol may differ from file to file.
For example, for ini files it would be ; instead of #

This 2 lines are define Themer Block and they tell where Themer will place it's code when you tell it to switch theme.
When theme changes, Themer swaps this block with set of variables that are defined inside theme. For theme dark Themer Block would look like this:

# THEMER
background = #000000
foregorund = #ffffff
# THEMER_BLOCK

Now we need to register a file inside of themer files block. Here's the schema:

files:
  file_name:
    path: "/path/to/file" # required
    comment: "#" # default value, may be omitted
    closing_comment: ""
    ignore: [] # optional
    only: [] # optional
    format: "<key> = <value>" # default value, may be omitted
    custom: "custom block" # optional

Let's discuss all of the fields:

• comment is a sequence for a single line comment (so Themer can surround blocks of code with comments it can parse)
• closing_comment is an optional value for file formats like css when it's required to have a sequence that ends comment: /* a comment */
  Example css setup:

css:
  comment: "/*"
  closing_comment: "*/"

• file_name is an arbitrary name for your file, it may be anything, say vim or i3
• path is a path to config file with Themer Block inside of it
• ignore and only will be discussed a little bit later.
• format defines how variables will be injected inside Themer Block.
  Default format is <key> = <value>. You may need to change this quite often, so here's an example how format would look for i3 config:

format: "set $<key> <value>"

• custom is discussed in it's own chapter, but basically it allows you to override default Themer block with your code

ignore and only

only and ignore allow you to change the way how variables are inserted in Themer block. As you may guess, ignore ignores varibles from the list, so if you put ignore: ["foreground"] inside your config, variable foreground will be omitted. only works exactly the oppossite, it leaves only listed values

Note: only has more priority than ignore, so if you use them both inside your config, be aware that ignore is, ironically, ignored

Extra: reloading your environment on the fly

Besides files and themes configs, you can set a string to reload varible like this:

reload: "i3 restart"

This tells Themer to run shell command after it has updated all files. May be usefull for something like i3 or polybar since they need to be manually reloaded after config change.

Command will be piped to sh -c <reload_command>, so put any command.

Usage

Now, when you created a few themes, updated and listed all of your config files inside Themer's config, you can try this out.

• First of all, check if your themes config is valid by running themer themes. It'll show you all avaliable themes you can set.
• Second of all, check is files config valid by running themer files --check. In case of error you will see red message, something like this

err not_found (/not_found) [Failed to read file.]
err nvim (~/.config/nvim/init.vim) [No THEMER block found.]

• When everything is green, you can try to set your theme. Remember dark theme we created? Set it with themer set dark

Additional resources:

Now, when you have a decent understanding what's going on, you can check additional resources:

• Multiple block inside of a single file
• Custom Themer block
• Command line reference