Kitty

此时，我已经完成了从 Windows 到 macOS 的转换。

更换使用 macOS 之后，终端基本上换成了使用 iTerm2，日常使用 Neovim 写个文章，撸个代码，基本没有什么问题。这次之所以再花时间研究 WezTerm 和 Kitty，仅是想通过 snacks.nvim 插件的 Image 模块，在 Neovim 中实现图片预览和公式渲染。仅此而已。

❯ which kitty
/Applications/kitty.app/Contents/MacOS/kitty

但是事后评估，投入的时间和取得的成果，似乎回报有点低。并不值得。

• 图片预览：不必非得在 Neovim 中预览，Yazi 可以呀
• 公式渲染：不必非得在 Neovim 中渲染，Typora 效果更佳

字体

在任何终端内使用 Neovim，尤其是中文用户，首先要解决的便是字体支持：又要有图标，又要有中文，最好能有多个字重，至少可以支持斜体和粗体。

JetBrains Mono

这个不用多说，可能是最流行的编程字体。只有英文字体。

Maple Mono

Maple Mono 全套字体包含英文，Nerd Font，中文，风格统一、圆润。所以，我们选择安装包含中文的最后一种字体方案。

# Maple Mono
brew install --cask font-maple-mono
# Maple Mono NF
brew install --cask font-maple-mono-nf
# Maple Mono NF CN
brew install --cask font-maple-mono-nf-cn

JetBrains Maple Mono

JetBrains Maple Mono 算是一个嫁接字体，英文使用的是 JetBrains Mono，也包含了 Nerd Font，中文则使用了 Maple Mono 字体。

视个人偏好是否使用智能连字，可以选择下载两种字体的任意一种：

• JetBrainsMapleMono-NF-XX-NL-XX.zip：不支持连字符，大约等于 JetBrainsMonoNL Nerd Font Mono 字体，拼接了 Maple Mono 的中文部分
• JetBrainsMapleMono-NF-XX-XX-XX.zip：支持连字符，大约等于 JetBrainsMono Nerd Font Mono 字体，拼接了 Maple Mono 的中文部分

字体配置

# List all fonts Kitty can find by `kitty +list-fonts`
#
# Unavailable in the kitty font list,
# despite that I have them both in Font Book.
# But WHY?
#
# JetBrainsMono
# JetBrains Maple Mono
#
# Therefore NOT working!
# font_family          JetBrains Mono
# font_family          JetBrains Maple Mono

font_family                 JetBrainsMono Nerd Font Mono
bold_font                   auto
italic_font                 auto
bold_italic_font            auto

font_size                    13

# What are the differences between font_features and symbol_map?
#
# The following settings are copied from GitHub,
# so I need to make sure that the referencing names are correct
# and available on my macOS.
#
# How cound I verify if I have the following fonts available?
#
font_features        JetBrainsMonoNFM-Regular +cv11 +cv12 +cv18
font_features        JetBrainsMonoNFM-Light +cv11 +cv12 +cv18
font_features        JetBrainsMonoNFM-ExtraLight +cv11 +cv12 +cv18
font_features        JetBrainsMonoNFM-SemiBold +cv11 +cv12 +cv18
font_features        JetBrainsMonoNFM-Italic +cv12 +cv16 +cv18 +cv19 +cv20
font_features        JetBrainsMonoNFM-SemiBoldItalic +ss02 +cv12 +cv16 +cv18 +cv19 +cv20

# Force to use Maple Mono for CJK characters
symbol_map             U+4E00-U+9FFF,U+3400-U+4DBF Maple Mono NF CN
# Force to use Symbols Nerd Font for Nerd Font symbols
symbol_map             U+23FB-U+23FE,U+2665,U+26A1,U+2B58,U+E000-U+E00A,U+E0A0-U+E0A3,U+E0B0-U+E0D4,U+E200-U+E2A9,U+E300-U+E3E3,U+E5FA-U+E6AA,U+E700-U+E7C5,U+EA60-U+EBEB,U+F000-U+F2E0,U+F300-U+F32F,U+F400-U+F4A9,U+F500-U+F8FF,U+F0001-U+F1AF0 Symbols Nerd Font Mono


# What are the differences between these settings?
#
# modify_font                  cell_width 95%
# modify_font                  cell_height 120%
#
# adjust_line_height            110%
# adjust_column_width           100%

Here are the answers to the questions you raised in your Kitty configuration file, specifically regarding font availability, settings differences, and verification on macOS.

1. Why JetBrains Mono and JetBrains Maple Mono are not listed in kitty +list-fonts on macOS

This is a common point of confusion. The issue is not that the fonts are missing or broken, but that Kitty requires the exact, internal PostScript name of the font, not the user-friendly name you see in Font Book.

Since around August 2024, Kitty has enforced a strict rule: the primary font must be reported by macOS as a "fixed-width" (monospaced) font. While your fonts are monospaced, Kitty's +list-fonts command shows only the fonts that pass this strict internal check .

The Solution: Your configuration correctly uses the Nerd Font variant (JetBrainsMono Nerd Font Mono), which Kitty can detect. To find the exact name Kitty expects for any font, use this command in your terminal:

kitty +list-fonts --psnames | grep -i "jetbrains"

This command uses the --psnames flag to display the precise PostScript name Kitty needs . For standard (non-Nerd) JetBrains fonts, the output often shows names like JetBrainsMono-Regular. You must use this exact string.

2. The Difference Between font_features and symbol_map

This is a key distinction. They operate at completely different levels of font rendering.

• font_features (How a font renders its characters): This setting enables or disables OpenType typographic features within a font you are already using . It modifies the existing font's behavior. For example, it can enable stylistic sets (like ss02 for alternative a or g characters), change the style of the number zero (+zero), or control standard ligatures (-liga).

  • Your Use Case: Your configuration uses font_features perfectly. It targets your primary font (JetBrainsMonoNFM-Regular, etc.) and enables specific stylistic variations (cv11, cv12, etc.) to customize how your main text looks .

• symbol_map (Which font renders specific characters): This setting is a fallback or override mechanism. It tells Kitty: "For these specific Unicode characters (e.g., CJK text or Nerd Font icons), do not use your primary font. Use this other, specified font instead."

  • Your Use Case: Your use of symbol_map is also correct. You are forcing Kitty to use Maple Mono NF CN for Chinese/Japanese/Korean characters and Symbols Nerd Font Mono for icon glyphs, ensuring those special characters are rendered correctly even if your primary font lacks them .

3. How to Verify if a Font is Available on macOS

Simply having a font in Font Book is not enough for Kitty. You need to verify it programmatically. Use these two commands in your terminal:

1. List all monospace fonts Kitty can detect: This shows every font Kitty can successfully use as its primary font.

   kitty +list-fonts

2. Search for a specific font by its PostScript name: This is the most reliable method to check for a specific font variant.

   kitty +list-fonts --psnames | grep -i "Maple Mono"

   If the command returns no results, Kitty cannot use that specific font file. This often happens if the font is not correctly installed as a monospaced font from macOS's perspective .

4. The Difference Between modify_font, adjust_line_height, and adjust_column_width

These settings control character cell dimensions and text placement, but at different scopes.

• modify_font cell_width / modify_font cell_height: This is a global setting that affects how Kitty calculates the size of the character grid itself. Changing this can break the layout of terminal applications like htop or vim.

  • Your commented example: modify_font cell_width 95% would shrink the width of every character cell, potentially causing visual artifacts .

• adjust_line_height / adjust_column_width: These are perceptual adjustments that change the spacing around the text within the existing character cells. They are safer to use for fine-tuning visual spacing without breaking application layouts.

  • Your commented example: adjust_line_height 110% would increase the vertical space between lines of text, making the terminal feel more open .

Recommendation: Stick with adjust_line_height and adjust_column_width. Avoid modify_font for cell dimensions unless you have a specific reason to alter the fundamental grid.

Summary of Actions

1. To fix your font detection, run kitty +list-fonts --psnames | grep "Mono" to find the exact name Kitty expects.
2. Your font_features and symbol_map logic is correct; they serve different but complementary purposes.
3. Use kitty +list-fonts --psnames as your primary tool to verify any font before adding it to your kitty.conf.