Back Discord Discord
Open Repo
Matugen Header

Matugen

A cross-platform material you and base16 color generation tool

Getting started

Basics

Matugen uses templates with keywords inside of them. First it replaces those keywords and then writes the replaced text to a file. Templates can be files with any file extension with text inside of them that uses the UTF-8 encoding.

Keywords are used inside of these brackets {{ }}. For more advanced functions you can use the block syntax <* *>. You can also modify the syntax in your configuration.

Matugen generates Material Design 3 and base16 colors. You can also import custom JSON through the config, CLI or overwrite it by providing JSON as a string argument. You can then use the imported JSON in your templates.

More about importing JSON

Template syntax and colors

Matugen has keywords for colors and templates that you use for theming. Check this section to see all colors and syntax you should use.

Making a template for waybar

Make a file in ~/.config/matugen/colors.css.

/*
* Css Colors
* Generated with Matugen
*/
<* for name, value in colors *>
@define-color {{name}} {{value.default.hex}};
<* endfor *>

Importing the colors into waybar

We need to import the matugen colors into our waybar configuration. Make a file in ~/.config/waybar/style.css

@import "colors.css";

/* Only to see that the colors actually get applied */
* {
    background-color: @primary_container;
}

Adding the template into the matugen configuration

Below is a very basic configuration file. You have to list all of your templates here by writing [templates.<name>]

Every template has an input and an output path. The input path is where your template with the keywords is.

The output path is where the generated template with already replaced keywords should be written to.

Only the input path for templates is required, you can leave the output path empty and only use the template for importing it into other templates.

# config_directory/config.toml
[config]

[templates.waybar]
input_path = '~/.config/matugen/colors.css'
output_path = '~/.config/waybar/colors.css'

More about configuration paths

Reloading waybar using a hook

Having to restart waybar to see the colors change can get annoying. There are hooks in matugen for that exact purpose.

Hooks are strings that can contain keywords inside of them just like templates.

  • pre_hook: Executes a command inside the string BEFORE the template is generated
  • post_hook: Executes a command inside the string AFTER the template is generated

Since we want to restart waybar after the template gets generated, we will use a post_hook

[config]

[templates.waybar]
input_path = '~/.config/matugen/colors.css'
output_path = '~/.config/waybar/colors.css'
post_hook = "pkill -SIGUSR2 waybar"

Automatically setting the wallpaper from the configuration

We will be using awww (swww) to set the wallpaper when all templates get generated.

[config]

[config.wallpaper]
# Whether to set the wallpaper or not
set = true

# The base command to run for applying the wallpaper.
# Keywords like  or anything that works inside of hooks works here.
# You could also set a static color if you use the color keywords and the wallpaper setter supports it.
command = "swww img --transition-type center "

# For example, killing the wallpaper daemon. Usage is like a normal hook.
# pre_hook = ""

[templates.waybar]
input_path = '~/.config/matugen/colors.css'
output_path = '~/.config/waybar/colors.css'
post_hook = "pkill -SIGUSR2 waybar"

Running matugen to generate the waybar theme

You can run matugen with either an image or a color. We will be using an image to generate the colorscheme.

Matugen will show a source color selection prompt, to skip it you can either use the --source-color-index or --prefer flags.

If you do not want to choose a scheme type or the light/dark mode yourself, you can use --type scheme-smart and --mode smart.

To see more output we will use the --verbose flag, and --show-colors to see all of the colors.

You can change the mode to be dark or light, change the lightness or contrast, choose a different scheme and more. See the Usage section for more or run matugen --help to see all of the flags with their descriptions.

matugen image /path/to/image --verbose --show-colors --type scheme-smart --mode smart

Matugen themes repository

The matugen-themes repository contains themes for most programs and websites.

You can look at the templates in the repo to learn more about making tempates.