Configuration Reference
Polyfont is configured via a .polyfont.toml file placed in your project root or home directory. The config loader searches upward from the current directory to find the nearest config file.
Top-level Schema
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
version |
integer | required | -- | Config format version. Must be 1. |
default |
table | optional | none | Default font applied when no rule matches. Becomes the * catchall rule. |
rules |
array of tables | optional | [] |
Array of font rules mapping scopes to fonts. |
Default Font Section
The [default] section defines the fallback font for any token not matched by a rule. If specified, it becomes a catchall rule with scope *.
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
family |
string | required | -- | Primary font family name. Must not be empty. |
fallbacks |
string[] | optional | [] |
Fallback font families in priority order. |
weight |
string | optional | "regular" |
Font weight. See weight values below. |
style |
string | optional | "normal" |
Font style. One of normal, italic, oblique. |
size |
number | optional | none | Font size in points. Omit to inherit from the editor. |
Font Rule
Each entry in the [[rules]] array maps a TextMate scope to a font specification:
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
scope |
string | required | -- | TextMate scope selector. Must not be empty. Supports hierarchical matching, wildcards, and negation. |
font.family |
string | required | -- | Primary font family name. Must not be empty. |
font.fallbacks |
string[] | optional | [] |
Fallback font families in priority order. |
font.weight |
string | optional | "regular" |
Font weight. See weight values below. |
font.style |
string | optional | "normal" |
Font style. One of normal, italic, oblique. |
font.size |
number | optional | none | Font size in points. Omit to inherit from the editor. |
Font Spec Fields
Both the [default] section and each [rules.font] section share the same font specification fields. In TOML, font fields are nested under the rule:
[[rules]]
scope = "keyword"
[rules.font]
family = "Maple Mono"
weight = "bold"Font Weight Values
| TOML Value | CSS Value | Numeric |
|---|---|---|
"thin" | 100 | 100 |
"extra-light" | 200 | 200 |
"light" | 300 | 300 |
"regular" | normal | 400 |
"medium" | 500 | 500 |
"semi-bold" | 600 | 600 |
"bold" | bold | 700 |
"extra-bold" | 800 | 800 |
"black" | 900 | 900 |
Font Style Values
| TOML Value | Description |
|---|---|
"normal" | Upright (default) |
"italic" | Italic variant |
"oblique" | Oblique variant |
Scope Matching Rules
Scopes use TextMate notation with hierarchical matching. Understanding these rules is essential for writing correct configurations.
Hierarchical matching
A scope pattern matches any scope that starts with the same segments:
| Pattern | Matches | Does not match |
|---|---|---|
"keyword" | keyword, keyword.control, keyword.operator | keywordx |
"entity.name" | entity.name, entity.name.function, entity.name.type | entity.type |
"entity.name.function" | entity.name.function | entity.name.type |
Wildcard
The * pattern matches every scope. When a [default] section is defined, it becomes a catchall rule with scope *.
Segment-level wildcards are also supported: "entity.*" matches entity.name, entity.type, and any child.
Specificity
When multiple rules match a scope, the most specific rule wins. Specificity is determined by the number of literal (non-wildcard) segments in the pattern:
| Pattern | Specificity |
|---|---|
"keyword" | 1 |
"keyword.control" | 2 |
"entity.name.function" | 3 |
"*" | 1 (matches all, lowest priority) |
"entity.*" | 1 (literal segments only) |
If two rules have equal specificity, the rule that appears first in the config wins.
Negation
Prefix a scope pattern with - to exclude it from matching. Use commas to combine positive and negative patterns:
| Selector | Behavior |
|---|---|
"keyword,-keyword.operator" | Matches keyword and keyword.control but not keyword.operator. |
"entity,entity.name.function" | Matches entity or entity.name.function (comma = OR). |
All 17 Example Rules
These are the complete rules from polyfont.example.toml:
| # | Scope | Font Family | Weight | Style |
|---|---|---|---|---|
| 1 | keyword | Maple Mono | bold | -- |
| 2 | keyword.control | Maple Mono | bold | -- |
| 3 | comment | IBM Plex Mono | -- | italic |
| 4 | string | Source Code Pro | light | -- |
| 5 | string.quoted | Source Code Pro | light | -- |
| 6 | entity.name.function | Monaspace Argon | semi-bold | -- |
| 7 | entity.name.type | Monaspace Neon | semi-bold | -- |
| 8 | variable | JetBrains Mono | -- | -- |
| 9 | variable.parameter | JetBrains Mono | -- | italic |
| 10 | constant | Monaspace Radon | bold | -- |
| 11 | constant.numeric | Monaspace Radon | -- | -- |
| 12 | support.function | Monaspace Krypton | -- | -- |
| 13 | storage.type | Maple Mono | bold | italic |
| 14 | punctuation | Fira Code | -- | -- |
| 15 | operator | Fira Code | -- | -- |
| 16 | meta.tag | Monaspace Xenon | bold | -- |
| 17 | attribute | IBM Plex Mono | -- | italic |
Scope Reference
Common TextMate scopes used in programming language grammars:
| Scope | Description | Typical Tokens |
|---|---|---|
keyword | Language keywords | if, else, fn, let |
keyword.control | Control flow keywords | if, for, while, return |
keyword.operator | Operator keywords | and, or, not |
comment | Comments | // ..., /* ... */ |
comment.line | Line comments | // ... |
comment.block | Block comments | /* ... */ |
string | String literals | "hello", 'world' |
string.quoted | Quoted strings | "hello" |
string.quoted.double | Double-quoted strings | "hello" |
string.quoted.single | Single-quoted strings | 'hello' |
string.template | Template strings | `hello ${name}` |
entity.name.function | Function names | calculate_total |
entity.name.type | Type names | MyStruct, MyEnum |
entity.name.tag | HTML/XML tags | <div> |
entity.other.attribute-name | Attribute names | class, id |
variable | Variables | count, result |
variable.parameter | Function parameters | items, name |
variable.other | Other variables | local_var |
constant | Constants | MAX_SIZE, PI |
constant.numeric | Numeric literals | 42, 3.14, 0xFF |
constant.language | Language constants | true, false, null |
support.function | Built-in/library functions | println, len |
support.type | Built-in types | String, Vec |
storage.type | Type annotations/declarations | i32, String |
storage.modifier | Storage modifiers | mut, const, static |
punctuation | Punctuation characters | (, ), {, } |
punctuation.separator | Separators | ,, ;, . |
operator | Operators | +, -, ==, && |
meta.tag | Tags (HTML/XML) | <div> |
attribute | Attributes | href, class |