15 个稳定版本
2.4.0 | 2024年6月14日 |
---|---|
2.3.0 | 2024年5月27日 |
2.1.0 | 2024年4月27日 |
2.0.0 | 2024年3月31日 |
1.1.1 | 2023年10月28日 |
在 模板引擎 中排名第24
92KB
2K SLoC

Catppuccin Whiskers 
Whiskers 是一个专门为 Catppuccin 定制的端口创建辅助工具,允许开发者定义可以注入调色板的模板文件。
[!重要] 此仓库已从 catppuccin/toolbox 迁移。要查看 v2.3.0 之前的版本,请参阅 catppuccin/toolbox 的版本。
安装
您可以使用以下方法之一安装 Whiskers
安装方法 | 说明 |
---|---|
crates.io | cargo安装 catppuccin-whiskers |
源 | cargo安装 --githttps://github.com/catppuccin/whiskers catppuccin-whiskers |
Homebrew | brew安装 catppuccin/tap/whiskers |
Nix | nix profile install github:catppuccin/whiskers nix run github:catppuccin/whiskers-- <参数> |
二进制文件 (Windows, MacOS & Linux) |
可在 最新 GitHub 版本 中获取。 |
用法
$ whiskers --help
Soothing port creation tool for the high-spirited!
Usage: whiskers [OPTIONS] [TEMPLATE]
Arguments:
[TEMPLATE]
Path to the template file, or - for stdin
Options:
-f, --flavor <FLAVOR>
Render a single flavor instead of all four
[possible values: latte, frappe, macchiato, mocha]
--color-overrides <COLOR_OVERRIDES>
Set color overrides
--overrides <OVERRIDES>
Set frontmatter overrides
--check [<EXAMPLE_PATH>]
Instead of creating an output, check it against an example
In single-output mode, a path to the example file must be provided. In multi-output mode, no path is required and, if one is provided, it will be ignored.
--dry-run
Dry run, don't write anything to disk
--list-functions
List all Tera filters and functions
--list-flavors
List the Catppuccin flavors
--list-accents
List the Catppuccin accent colors
-o, --output-format <OUTPUT_FORMAT>
Output format of --list-functions
[default: json]
[possible values: json, yaml, markdown, markdown-table, plain]
-h, --help
Print help (see a summary with '-h')
-V, --version
Print version
模板
请熟悉 Whiskers 使用的模板引擎 Tera。
命名约定
Whiskers 对模板名称没有限制。然而,我们建议您使用以下选项之一
<端口号>.tera
存放在仓库根目录,用于只需要一个模板的端口。- 例如,lazygit 端口使用
lazygit.tera
- 例如,lazygit 端口使用
templates/<文件名>.tera
尤其适用于有多个模板的端口。- 例如,一个生成名为
ui.cfg
和palette.cfg
文件的端口可以分别使用templates/ui.tera
和templates/palette.tera
。
- 例如,一个生成名为
这些约定旨在使贡献者更容易找到模板,并为代码编辑器提供有关正确文件类型的提示。
上下文变量
以下变量可用于您的模板中
单口味模式
变量 | 描述 |
---|---|
flavor (Flavor ) |
正在模板化的口味。 |
rosewater ,flamingo ,pink ,等。(Color ) |
正在模板化的口味的所有颜色。 |
任何前置内容 | 如前置内容部分所述的所有前置内容变量。 |
多口味模式
变量 | 描述 |
---|---|
flavors (Map<String, Flavor >) |
包含所有命名口味的数组,包括所有其他上下文变量。 |
任何前置内容 | 如前置内容部分所述的所有前置内容变量。 |
类型
这些类型设计得与 palette.json 非常接近。
口味
字段 | 类型 | 描述 | 示例 |
---|---|---|---|
name |
String |
口味的名称。 | "Latte" ,"Frappé" ,"Macchiato" ,"Mocha" |
identifier |
String |
口味的标识符。 | "latte" ,"frappe" ,"macchiato" ,"mocha" |
emoji |
char |
与口味相关的表情符号。 | '🌻' ,'🪴' ,'🌺' ,'🌿' |
order |
u32 |
口味在调色板规范中的顺序。 | 0 到 3 |
dark |
bool |
口味是否为深色。 | false 对 Latte,true 对其他 |
light |
bool |
是否是浅色。 | true 对 Latte,false 对其他 |
colors |
Map<String,颜色> |
颜色标识符与其相应值的映射。 |
颜色
字段 | 类型 | 描述 | 示例 |
---|---|---|---|
name |
String |
颜色的名称。 | "Rosewater" ,"Surface 0" ,"Base" |
identifier |
String |
颜色的标识符。 | "rosewater" ,"surface0" ,"base" |
order |
u32 |
颜色在调色板规范中的顺序。 | 0 到 25 |
accent |
bool |
颜色是否为强调色。 | |
hex |
String |
颜色以十六进制格式表示。 | "1e1e2e" |
rgb |
RGB |
颜色以 RGB 格式表示。 | |
hsl |
HSL |
颜色以 HSL 格式表示。 | |
opacity |
u8 |
颜色的不透明度。 | 0 到 255 |
RGB
字段 | 类型 | 描述 |
---|---|---|
r |
u8 |
颜色的红色通道。 |
g |
u8 |
颜色的绿色通道。 |
b |
u8 |
颜色的蓝色通道。 |
HSL
字段 | 类型 | 描述 |
---|---|---|
h |
u16 |
颜色的色调。 |
s |
u8 |
颜色的饱和度。 |
l |
u8 |
颜色的亮度。 |
函数
描述 | 示例 | |
---|---|---|
if |
如果条件为真,则返回一个值,如果为假则返回另一个值 | if(cond=true, t=1, f=0) ⇒ 1 |
object |
从输入创建一个对象 | object(a=1, b=2) ⇒ {a: 1, b: 2} |
css_rgb |
将颜色转换为 RGB CSS 字符串 | css_rgb(color=red) ⇒ rgb(210, 15, 57) |
css_rgba |
将颜色转换为 RGBA CSS 字符串 | css_rgba(color=red) ⇒ rgba(210, 15, 57, 1.00) |
css_hsl |
将颜色转换为 HSL CSS 字符串 | css_hsl(color=red) ⇒ hsl(347, 87%, 44%) |
css_hsla |
将颜色转换为 HSLA CSS 字符串 | css_hsla(color=red) ⇒ hsla(347, 87%, 44%, 1.00) |
read_file |
读取并包含文件的正文,路径相对于模板文件 | read_file(path="abc.txt") ⇒ abc |
过滤器
描述 | 示例 | |
---|---|---|
add |
向颜色添加值 | red | add(hue=30) ⇒ #ff6666 |
sub |
从颜色中减去值 | red | sub(hue=30) ⇒ #d30f9b |
mod |
修改颜色 | red | mod(lightness=80) ⇒ #f8a0b3 |
mix |
混合两种颜色 | red | mix(color=base, amount=0.5) ⇒ #e08097 |
urlencode_lzma |
使用 LZMA 压缩将对象序列化为 URL 安全字符串 | red | urlencode_lzma ⇒ #ff6666 |
trunc |
将数字截断到指定的小数位数 | 1.123456 | trunc(places=3) ⇒ 1.123 |
css_rgb |
将颜色转换为 RGB CSS 字符串 | red | css_rgb ⇒ rgb(210, 15, 57) |
css_rgba |
将颜色转换为 RGBA CSS 字符串 | red | css_rgba ⇒ rgba(210, 15, 57, 1.00) |
css_hsl |
将颜色转换为 HSL CSS 字符串 | red | css_hsl ⇒ hsl(347, 87%, 44%) |
css_hsla |
将颜色转换为 HSLA CSS 字符串 | red | css_hsla ⇒ hsla(347, 87%, 44%, 1.00) |
[!注意] 您还可以访问所有Tera的内置过滤器和函数。有关更多信息,请参阅Tera文档。
前端信息
Whiskers模板可以在文件顶部包含一个前端信息部分。
前端信息是一个包含模板元数据的YAML块。如果存在,前端信息部分必须是文件中的第一个内容,并且必须以三横线之间的有效YAML形式出现。
模板版本
最重要的前端信息键是Whiskers版本。此键允许Whiskers确保它正在渲染一个它可以理解的模板。
示例
---
whiskers:
version: "2.0.0"
---
... standard template content goes here ...
如果版本键不存在,Whiskers将显示警告并尝试渲染模板。然而,建议始终包含版本键以确保与Whiskers未来版本的兼容性。
十六进制格式
用于渲染十六进制颜色的格式可以使用hex_format
前端变量进行自定义。
此字符串作为以下上下文变量下的Tera模板进行渲染
r
、g
、b
、a
:颜色的红色、绿色、蓝色和alpha通道,作为小写两位十六进制字符串。R
、G
、B
、A
:如上所述,但为大写。z
:如果颜色不是完全不透明,则与a
相同,否则为空字符串。Z
:如上所述,但为大写。
hex_format
的默认值为{{r}}{{g}}{{b}}{{z}}
。
示例
---
whiskers:
version: "2.0.0"
hex_format: "0x{{B}}{{G}}{{R}}{{A}}"
---
{{red.hex}}
运行 whiskers example.tera -f mocha
会产生以下输出: 0xA88BF3FF
页眉变量
您还可以通过将它们添加到模板的页眉中,在模板过程中包含额外的上下文变量。
例如,给定以下模板 (example.tera
)
---
app: "Pepperjack"
author: "winston"
---
# Catppuccin for {{app}}
# by {{author}}
bg = '{{base.hex}}'
fg = '{{text.hex}}'
运行 whiskers example.tera -f mocha
产生以下输出
# Catppuccin for Pepperjack
# by winston
bg = '1e1e2e'
fg = 'cdd6f4'
页眉的一个常见用途是设置主题的强调色
---
accent: "mauve"
---
{% set darkGreen = green | sub(lightness=30) %}
bg = "#{{base.hex}}"
fg = "#{{text.hex}}"
border = "#{{flavor.colors[accent].hex}}"
diffAddFg = "#{{green.hex}}"
diffAddBg = "#{{darkGreen.hex}}"
渲染上述模板产生以下输出
bg = "#1e1e2e"
fg = "#cdd6f4"
border = "#cba6f7"
diffaddfg = "#a6e3a1"
diffaddbg = "#40b436"
覆盖
页眉覆盖也可以通过命令行工具使用 --overrides
标志来指定,接受类似于页眉的 JSON 字符串。这对于构建脚本来说特别有用,可以自动为每个强调色生成文件
示例.tera
---
accent: "mauve"
---
theme:
accent: "{{flavor.colors[accent].hex}}"
当运行 whiskers example.tera -f latte --overrides '{"accent": "pink"}'
时,accent
将被覆盖为粉色。
颜色覆盖
可以通过命令行工具使用 --color-overrides
标志来指定颜色覆盖。此标志接受如下 JSON 字符串
{
"all": {
"text": "ff0000"
},
"mocha": {
"base": "000000",
"mantle": "010101",
"crust": "020202"
}
}
传递这些覆盖将设置所有口味的文本颜色为亮红色,并将 Mocha 的 base
、mantle
和 crust
颜色设置为黑色/接近黑色。
单口味模式
使用 --flavor/-f
标志运行 Whiskers 将使其进入单口味模式。这意味着所选口味被放置到模板上下文中作为 flavor
,并且为了方便起见,它的所有颜色也被放置到上下文中作为相应的标识符(red
、surface0
等。)
多口味模式
不使用 --flavor/-f
标志运行 Whiskers 将使其进入多口味模式。在这种模式下,所有口味都被放置到模板上下文中,作为口味标识符到相应 Flavor
对象的映射。
此映射可以像这样迭代
{% for id, flavor in flavors %}
{{id}} is one of "latte", "frappe", "macchiato", or "mocha".
{{flavor}} is an object containing the flavor's properties and colors.
{% endfor %}
请参阅 examples/single-file 目录,了解如何使用它的更多具体示例。
模板矩阵
Whiskers 可以使用在页眉中设置的矩阵从单个模板渲染多个输出。例如,这可以用于为每种口味和强调色生成一个输出。
在此模式下,Whiskers 将直接渲染到页眉中指定的 filename
键所指定的文件集中。这可以通过 --dry-run
标志禁用,在这种情况下,Whiskers 将渲染模板但不会将它们写入任何地方。
矩阵定义为一个可迭代对象的列表。Whiskers 将为矩阵中可迭代对象的每个组合生成一个文件。
矩阵中的一些可迭代对象可以是没有任何值提供的字符串。在这种情况下,Whiskers 将将其视为“魔法可迭代对象”,这是一个在渲染模板之前 Whiskers 可以自动生成值的可迭代对象。
以下支持以下魔法可迭代对象
flavor
:latte、frappe、macchiato、mochaaccent
:玫瑰水、火烈鸟、粉色、淡紫色、红色、栗色、桃色、黄色、绿色、蓝绿色、天空色、蓝宝石色、蓝色、薰衣草色
示例
---
whiskers:
version: 2.0.0
matrix:
- variant: ["normal", "no-italics"]
- flavor
- accent
filename: "catppuccin-{{flavor.identifier}}-{{accent}}-{{variant}}.ini"
---
# Catppuccin {{flavor.name}}{% if variant == "no-italics" %} (no italics){% endif %}
[theme]
{{accent}}: #{{flavor.colors[accent].hex}}
运行 whiskers template.tera
将生成以下文件
catppuccin-latte-rosewater-normal.ini
catppuccin-latte-rosewater-no-italics.ini
catppuccin-latte-flamingo-normal.ini
catppuccin-latte-flamingo-no-italics.ini
...
catppuccin-frappe-rosewater-normal.ini
catppuccin-frappe-rosewater-no-italics.ini
... 以及 flavor、accent 和 variant 的每一种组合。请注意,文件名是通过渲染矩阵可迭代元素的每种组合中的 frontmatter 中的 filename
键来生成的。
检查模式
您可以使用 Whiskers 作为带有 检查模式 的 linter。要做到这一点,请设置 --check
选项。Whiskers 将像平常一样渲染模板,但然后它不会打印结果,而是将其与预期输出进行比较,如果它们不同,则会以退出代码 1 失败。
这在 CI 管道中特别有用,以确保生成的文件在没有对模板进行相应更改的情况下不会更改。
在单 flavor 模式下,您必须将预期输出文件的路径作为 --check
选项的参数提供。在多 flavor 模式下,路径是不必要的,将被忽略。
Whiskers 将使用在 DIFFTOOL
环境变量中设置的程序将输出与检查文件进行比较,如果没有设置,将回退到 diff
。命令将以以下方式调用:$DIFFTOOL <实际> <预期>
。
$ whiskers theme.tera latte --check themes/latte.cfg
(no output, exit code 0)
$ whiskers theme.tera latte --check themes/latte.cfg
Templating would result in changes.
4c4
< accent is #ea76cb
---
> accent is #40a02b
(exit code 1)
编辑器支持
Tera 的语法不是大多数编辑器原生支持的。一些编辑器有可用的扩展,可以提供 Tera 模板的语法高亮和其他功能。如果您的编辑器没有可用的扩展,您可以尝试使用 Jinja 扩展。虽然不是完全匹配,但 Tera 的语法与 Jinja 的语法足够相似,在大多数情况下可以很好地使用。
对于 Visual Studio Code 用户,我们推荐 Better Jinja 扩展。
进一步阅读
- 请参阅 示例 目录,其中进一步展示了 Whiskers 的实用性和功能。
- 请参阅 RFC,CAT-0003-Whiskers,了解创建 Whiskers 的动机。
版权 © 2023-present Catppuccin Org
依赖关系
~15–27MB
~478K SLoC