Getting Started

Prerequisites

Installation

Build from source using Cargo:

# Clone the repository
git clone https://github.com/WyattAu/polyfont.git
cd polyfont

# Build all crates (release mode)
cargo build --workspace --release

# The CLI binary will be at target/release/polyfont
# Optionally copy it to your PATH
cp target/release/polyfont /usr/local/bin/

To build only the CLI:

cargo build --release -p polyfont-cli

To build the LSP server:

cargo build --release -p polyfont-lsp

Your First Config

Create a .polyfont.toml file in your project root or home directory:

version = 1

[default]
family = "Fira Code"
fallbacks = ["JetBrains Mono", "monospace"]

[[rules]]
scope = "keyword"
[rules.font]
family = "Maple Mono"
weight = "bold"

[[rules]]
scope = "comment"
[rules.font]
family = "IBM Plex Mono"
style = "italic"

[[rules]]
scope = "entity.name.function"
[rules.font]
family = "Monaspace Argon"
weight = "semi-bold"

[[rules]]
scope = "string"
[rules.font]
family = "Source Code Pro"
weight = "light"

Alternatively, copy the full example config which includes all 17 rules:

cp polyfont.example.toml .polyfont.toml

Validate your configuration:

polyfont check

See the Configuration Reference for the complete schema and all available options.

VSCode Setup

VSCode 1.97+ supports native fontFamily in textMateRules, which is the cleanest integration path.

Option A: CLI-generated settings

Generate VSCode settings from your .polyfont.toml:

# Print to stdout
polyfont vscode

# Write to .vscode/settings.json
polyfont vscode -o .vscode/settings.json

The generated output is a JSON fragment that sets editor.tokenColorCustomizations.textMateRules with fontFamily, fontWeight, and fontStyle per scope.

Option B: VSCode Extension

Build and install the extension from source:

cd editors/vscode
npm install
npm run build
# Install as development extension or package as .vsix

Neovim Setup

Install the Polyfont Neovim plugin using your plugin manager:

lazy.nvim

-- lazy.nvim
{
  "WyattAu/polyfont",
  dir = "/path/to/polyfont/editors/neovim",
  config = function()
    require("polyfont").setup()
  end,
}

CLI-generated config

Generate Neovim highlight group configuration:

polyfont neovim

This outputs Lua code that sets vim.api.nvim_set_hl for each scope with font family, weight, and style. Redirect the output to a Lua file and source it from your Neovim config.

Font family changes require a GUI client (Goneovim, Neovide). Terminal Neovim is limited to bold/italic/underline styling. See the Editor Integration page for details.

CLI Tool

The polyfont CLI provides several subcommands:

Specify a custom config file path with --config PATH (applies to all subcommands):

polyfont --config /path/to/.polyfont.toml check