7 stable releases

1.1.4 Dec 10, 2023
1.1.2 Nov 23, 2023
1.1.1 Oct 28, 2023
1.0.3 Oct 28, 2023
1.0.2 Oct 27, 2023

#347 in Template engine

Download history 10/week @ 2023-11-06 3/week @ 2023-11-13 43/week @ 2023-11-20 31/week @ 2023-11-27 23/week @ 2023-12-04 16/week @ 2023-12-11 14/week @ 2023-12-25 2/week @ 2024-01-01 7/week @ 2024-01-08 2/week @ 2024-01-15 2/week @ 2024-01-22 36/week @ 2024-01-29 2/week @ 2024-02-05 35/week @ 2024-02-12 195/week @ 2024-02-19

268 downloads per month

MIT license

36KB
621 lines

Logo
Catppuccin Whiskers

 

A templating tool to simplify the creation of Catppuccin ports.

Installation

Compiled binaries are available for Windows, macOS, and Linux.

Download the correct file for your system and place it somewhere in your executable path.

Alternatively, you can install with Cargo, Nix, or from source:

# latest crates.io release:
$ cargo install catppuccin-whiskers
$ whiskers <template> <flavor>

# to install from source:
$ cargo install --git https://github.com/catppuccin/toolbox whiskers

# if you're using Homebrew (or Linuxbrew):
$ brew install catppuccin/tap/whiskers

# there's also a Nix flake:
$ nix run github:catppuccin/toolbox#whiskers -- <template> <flavor>

Usage

Make a template per file type that your port requires, then use the Whiskers CLI to populate the colors for all four Catppuccin flavors:

$ whiskers --help
Soothing port creation tool for the high-spirited!

Usage: whiskers [OPTIONS] [TEMPLATE] [FLAVOR]

Arguments:
  [TEMPLATE]  Path to the template file to render, or `-` for stdin
  [FLAVOR]    Flavor to get colors from [possible values: latte, frappe, macchiato, mocha]

Options:
      --override <OVERRIDES>       The overrides to apply to the template in key=value format
  -o, --output-path <OUTPUT_PATH>  Path to write to instead of stdout
      --check <CHECK>              Instead of printing a result just check if anything would change
  -l, --list-helpers               List all template helpers in markdown format
  -h, --help                       Print help
  -V, --version                    Print version

Template Syntax

Templates are written in Handlebars syntax.

Context Variables

The following variables are available for use in your templates:

  • flavor (string): The name of the flavor being templated. Possible values: latte, frappé, macchiato, mocha.
  • isLight (bool): True if flavor is latte, false otherwise.
  • isDark (bool): True unless flavor is latte.
  • All named colors in the flavor, such as red, subtext0, and crust. A full list of named colors can be found here. Each color is formatted as hex by default.
  • All frontmatter variables as described in the Frontmatter section.

Helpers

The following custom helpers are available:

  • uppercase string : Convert a string to uppercase.
    • {{ uppercase "hello" }}HELLO
  • lowercase string : Convert a string to lowercase.
    • {{ lowercase "HELLO" }}hello
  • titlecase string : Convert a string to titlecase.
    • {{ titlecase "hello there" }}Hello There
  • trunc number places : Format a number to a string with a given number of places.
    • {{ trunc 3.14159265 2 }}3.14
  • lighten color amount : Lighten a color by a percentage.
    • {{ lighten red 0.1 }}f8bacc / hsl(343, 81%, 85%)
  • darken color amount : Darken a color by a percentage.
    • {{ darken red 0.1 }}ee5c85 / hsl(343, 81%, 65%)
  • mix color_a color_b ratio : Mix two colors together in a given ratio.
    • {{ mix red base 0.3 }}5e4054 (30% red, 70% base)
  • opacity color amount : Set the opacity of a color.
    • {{ opacity red 0.5 }}hsla(343, 81%, 75%, 0.50)
  • unquote value : Marks a value to be unquoted. Mostly useful for maintaining JSON syntax highlighting in template files when a non-string value is needed.
    • {{ unquote isLight true }}true (the surrounding quotation marks have been removed)
  • rgb color : Convert a color to CSS RGB format.
    • {{ rgb red }}rgb(243, 139, 168)
  • rgba color : Convert a color to CSS RGBA format.
    • {{ rgba (opacity red 0.6) }}rgba(243, 139, 168, 0.60)
  • hsl color : Convert a color to CSS HSL format.
    • {{ hsl red }}hsl(343, 81%, 75%)
  • hsla color : Convert a color to CSS HSLA format.
    • {{ hsla (opacity red 0.6) }}hsla(343, 81%, 75%, 0.60)
  • red_i color : Get the red channel of a color as an integer from 0 to 255.
    • {{ red_i red }}243
  • green_i color : Get the green channel of a color as an integer from 0 to 255.
    • {{ green_i red }}139
  • blue_i color : Get the blue channel of a color as an integer from 0 to 255.
    • {{ blue_i red }}168
  • alpha_i color : Get the alpha channel of a color as an integer from 0 to 255.
    • {{ alpha_i (opacity red 0.6) }}153
  • red_f color : Get the red channel of a color as a float from 0 to 1.
    • {{ red_f red }}0.95 (truncated to 2 places)
  • green_f color : Get the green channel of a color as a float from 0 to 1.
    • {{ green_f red }}0.55 (truncated to 2 places)
  • blue_f color : Get the blue channel of a color as a float from 0 to 1.
    • {{ blue_f red }}0.66 (truncated to 2 places)
  • alpha_f color : Get the alpha channel of a color as a float from 0 to 1.
    • {{ alpha_f (opacity red 0.6) }}0.60 (truncated to 2 places)
  • darklight if-dark if-light : Choose a value depending on the current flavor. Latte is light, while Frappé, Macchiato, and Mocha are all dark.
    • {{ darklight "Night" "Day" }}Day on Latte, Night on other flavors

Frontmatter

You can include additional context variables in the templating process by adding it to an optional YAML frontmatter section at the top of your template file.

As a simple example, given the following template (example.cfg):

---
app: 'Pepperjack'
author: 'winston'
---
# Catppuccin for {{app}}
# by {{author}}
bg = '{{base}}'
fg = '{{text}}'

Running whiskers example.cfg mocha produces the following output:

# Catppuccin for Pepperjack
# by winston
bg = '1e1e2e'
fg = 'cdd6f4'

Values in YAML frontmatter are rendered in the same way as the rest of the template, which means you can also make use of context variables in your frontmatter. This can be useful for things like setting an accent color:

---
accent: "{{mauve}}"
darkGreen: "{{darken green 0.3}}"
---
bg = "#{{base}}"
fg = "#{{text}}"
border = "#{{accent}}"
diffAddFg = "#{{green}}"
diffAddBg = "#{{darkGreen}}"

Rendering the above template produces the following output:

bg = "#1e1e2e"
fg = "#cdd6f4"
border = "#cba6f7"
diffaddfg = "#a6e3a1"
diffaddbg = "#40b436"

Overrides

Whiskers supports overriding individual template values without changing the underlying template source. To use this feature, pass the --override flag to the whiskers CLI. You can use the --override flag multiple times to apply multiple overrides.

We'll use the following template for this example:

---
accent: '{{mauve}}'
---
bg = "#{{base}}"
fg = "#{{accent}}"

With no overrides passed to whiskers, we get the following output:

bg = "#1e1e2e"
fg = "#cba6f7"

However, we can pass overrides through the CLI with --override accent=40b436. Then, we get:

bg = "#1e1e2e"
fg = "#40b436"

We can also override with another value from the template context, for example --override accent=sky. This gives the following result:

bg = "#1e1e2e"
fg = "#89dceb"

Finally, we can override both values by passing two overrides. If we invoke whiskers with --override accent=yellow --override base=000000 then we get this output:

bg = "#000000"
fg = "#f9e2af"

Check Mode

You can use Whiskers as a linter with check mode. To do so, set the --check option to a file containing the expected output. Whiskers will render your template as per usual, but then instead of printing the result it will check it against the expected output and fail with exit code 1 if they differ.

This is especially useful in CI pipelines to ensure that the generated files are not changed without a corresponding change to the templates.

Whiskers will diff the output against the check file using the program set in the DIFFTOOL environment variable, falling back to diff if it's not set. The command will be invoked as $DIFFTOOL <actual> <expected>.

$ whiskers theme.hbs latte --check themes/latte.cfg
(no output, exit code 0)

$ whiskers theme.hbs latte --check themes/latte.cfg
Templating would result in changes.
4c4
< accent is #ea76cb
---
> accent is #40a02b

(exit code 1)

Further Reading

 

Copyright © 2023-present Catppuccin Org

Dependencies

~13–26MB
~377K SLoC