diff --git a/docs/config/lua/config/font_rules.md b/docs/config/lua/config/font_rules.md index 3187b96c1..474b5f4f2 100644 --- a/docs/config/lua/config/font_rules.md +++ b/docs/config/lua/config/font_rules.md @@ -1,104 +1,169 @@ # `font_rules` -You may optionally specify rules that apply different font styling based on the -attributes of the text rendered in the terminal. Most users won't need to do -this; these rules are useful when you have some unusual fonts or mixtures of -fonts that you'd like to use. The default is to auto-generate reasonable -italic and bold styling based on the [font](font.md) configuration. +When textual output in the terminal is styled with bold, italic or other +attributes, wezterm uses `font_rules` to decide how to render that text. -If you do specify `font_rules`, they are applied in the order that they are -specified in the configuration file, stopping with the first matching rule: +By default, unstyled text will use the font specified by the [font](font.md) +configuration, and wezterm will use that as a base, and then automatically +generate appropriate `font_rules` that use heavier weight fonts for bold text, +lighter weight fonts for dim text and italic fonts for italic text. -```lua -local wezterm = require 'wezterm' -return { - font_rules = { - -- Define a rule that matches when italic text is shown - { - -- If specified, this rule matches when a cell's italic value exactly - -- matches this. If unspecified, the attribute value is irrelevant - -- with respect to matching. - italic = true, +Most users won't need to specify any explicit value for `font_rules`, as the +defaults should be sufficient. - -- Match based on intensity: "Bold", "Normal" and "Half" are supported - -- intensity = "Normal", +If you have some unusual fonts or mixtures of fonts that you'd like to use, +such as using your favourite monospace font for the base and a fancy italic +font from a different font family for italics, then `font_rules` will allow you +to do so. - -- Match based on underline: "None", "Single", and "Double" are supported - -- underline = "None", +`font_rules` is comprised of a list of rule entries with fields that are split +into *matcher* fields and *action* fields. Matcher fields specify which textual +attributes you want to match on, while action fields specify how you want to +render them. - -- Match based on the blink attribute: "None", "Slow", "Rapid" - -- blink = "None", +The following fields are matcher fields: - -- Match based on reverse video - -- reverse = false, +|Name |Associated Attribute|Possible Values| +|----------|--------------------|---------------| +|italic |italic |`true` (italic) or `false` (not italic)| +|intensity |bold/bright or dim/half-bright|`"Normal"` (neither bold nor dim), `"Bold"`, `"Half"`| +|underline |underline | `"None"` (not underlined), `"Single"` (single underline), `"Double"` (double underline)| +|blink |blinking | `"None"` (not blinking), `"Rapid"` (regular rapid blinking), `"Slow"` (slow blinking)| +|reverse |reverse/inverse | `true` (reversed) or `false` (not reversed)| +|strikethrough|strikethrough | `true` (struck-through) or `false` (not struck-through)| +|invisible |invisible | `true` (invisible) or `false` (not invisible)| - -- Match based on strikethrough - -- strikethrough = false, +If a matcher field is omitted, then the associated attribute has no impact +on the match: the rule *doesn't care about* that attribute and will match based +on the attributes that were listed. - -- Match based on the invisible attribute - -- invisible = false, +The following fields are action fields: - -- When the above attributes match, apply this font styling - font = wezterm.font('Operator Mono SSm Lig Medium', { italic = true }), - }, - }, -} -``` +|Name |Action | +|--------------|---------| +|font |Specify the font that should be used| -Here's an example from my configuration file; +The way that `font_rules` are processed is: + +1. Take the list of `font_rules` from your configuration +2. For each rule in the order listed in `font_rules`: +3. Consider each *matcher* field explicitly specified in the entry. If the associated attribute does not match the value specified in the entry, move on to the next rule. +4. If all of the *matcher* fields explicitly specified in the entry match the attributes of the text, then: + * The `font` *action* field, if specified, will override the base `font` configuration + * No further `font_rules` will be considered: the matching is complete +5. If none of the rules you specify matched, then a set of default rules based on your base `font` will be used in the same way as above. + +Here's an example from my configuration file, which I use with a variant of +`Operator Mono` that is patched to add ligatures. This particular font has +font-weights that are either too bold or too light for the default rules to +produce great results, hence this set of rules. ```lua local wezterm = require 'wezterm' --- A helper function for my fallback fonts -function font_with_fallback(name, params) - local names = { name, 'Noto Color Emoji', 'JetBrains Mono' } - return wezterm.font_with_fallback(names, params) -end - return { - font = font_with_fallback 'Operator Mono SSm Lig Medium', + font = wezterm.font_with_fallback 'Operator Mono SSm Lig Medium', font_rules = { - -- Select a fancy italic font for italic text - { - italic = true, - font = font_with_fallback 'Operator Mono SSm Lig Medium Italic', - }, - - -- Similarly, a fancy bold+italic font - { - italic = true, - intensity = 'Bold', - font = font_with_fallback 'Operator Mono SSm Lig Book Italic', - }, - - -- Make regular bold text a different color to make it stand out even more + -- For Bold-but-not-italic text, use this relatively bold font, and override + -- its color to a tomato-red color to make bold text really stand out. { intensity = 'Bold', - font = font_with_fallback( - 'Operator Mono SSm Lig Bold', + italic = false, + font = wezterm.font_with_fallback( + 'Operator Mono SSm Lig', + -- Override the color specified by the terminal output and force + -- it to be tomato-red. + -- The color value you set here can be any CSS color name or + -- RGB color string. { foreground = 'tomato' } ), }, - -- For half-intensity text, use a lighter weight font + -- Bold-and-italic + { + intensity = 'Bold', + italic = true, + font = wezterm.font_with_fallback { + family = 'Operator Mono SSm Lig', + italic = true, + }, + }, + + -- normal-intensity-and-italic + { + intensity = 'Normal', + italic = true, + font = wezterm.font_with_fallback { + family = 'Operator Mono SSm Lig', + weight = 'DemiLight', + italic = true, + }, + }, + + -- half-intensity-and-italic (half-bright or dim); use a lighter weight font { intensity = 'Half', - font = font_with_fallback 'Operator Mono SSm Lig Light', + italic = true, + font = wezterm.font_with_fallback { + family = 'Operator Mono SSm Lig', + weight = 'Light', + italic = true, + }, + }, + + -- half-intensity-and-not-italic + { + intensity = 'Half', + italic = false, + font = wezterm.font_with_fallback { + family = 'Operator Mono SSm Lig', + weight = 'Light', + }, }, }, } ``` -*Since: 20210502-130208-bff6815d* +Here's another example combining `FiraCode` with `Victor Mono`, using `Victor Mono` only for italics: -The default `font_rules` generated by wezterm are now always appended to the -rules that you've supplied (rather than used only if you didn't specify any), -and now also include rules for selecting lighter weight fonts when half-bright -text is rendered to the terminal. +```lua +local wezterm = require 'wezterm' -That means that you shouldn't need to specify as many rules as in previously -releases. +return { + font = wezterm.font { family = 'FiraCode' }, + + font_rules = { + { + intensity = 'Bold', + italic = true, + font = wezterm.font { + family = 'VictorMono', + weight = 'Bold', + style = 'Italic', + }, + }, + { + italic = true, + intensity = 'Half', + font = wezterm.font { + family = 'VictorMono', + weight = 'DemiBold', + style = 'Italic', + }, + }, + { + italic = true, + intensity = 'Normal', + font = wezterm.font { + family = 'VictorMono', + style = 'Italic', + }, + }, + }, +} +``` + +## Debugging Font Rules You can run `wezterm ls-fonts` to summarize the font rules and the fonts that match them: