Configuration¶

Skim is highly configurable, allowing you to customize everything from layout dimensions and spacing to colors and keycode display.

Configuration File¶

The configuration is defined in a YAML file. You can create one using the interactive TUI or by extracting metadata from a keymap file:

# Launch the interactive TUI editor
skim configure --interactive

# Or extract from a keymap file
skim configure --keymap my-keymap.kbi --output skim-config.yaml

Structure¶

The configuration file is organized into three main sections:

keyboard: Hardware features and layer definitions.
keycodes: Custom keycode transformations and overrides.
output: Visual styling and layout dimensions.

Keyboard Section¶

This section defines the physical properties of the keyboard and the layers in your keymap.

keyboard:
  features:
    double_south: false  # Enable/disable double-south keys
  layers:
    - index: 0
      name: "Base Layer"
      id: "base"         # Optional ID for c2json layer lookup
      variant: "QWERTY"  # Optional secondary label (shown in overview)
    - index: 1
      name: "Symbols"

Keycodes Section¶

This section allows you to customize how keycodes are displayed. You can transform keycodes before processing or override their final display label.

keycodes:
  pre_process:
    - keycode: "LCTL_T(KC_A)"
      target: "MT(MOD_LCTL,KC_A)"
  overrides:
    - keycode: "KC_SPC"
      target: "Space"
    - keycode: "KC_ENT"
      target: "Enter"

Output Section¶

This section controls the visual appearance of the generated images.

output:
  keymap_title: "My Svalboard Layout"  # Optional title for overview image
  copyright: "© 2026 Your Name"        # Optional copyright notice
  layout:
    width: 1600
    spacing:
      margin: 0
      inset: 20
  style:
    use_layer_colors_on_keys: true
    hold_symbol_position: "outward"  # "inward", "outward", or "qmk"
    use_system_fonts: false           # Use system fonts instead of embedded
    show_layer_indicators: true       # Layer indicator circles on keys
    show_layer_connectors: true       # Connector lines in overview image
    border:
      width: 2
      radius: 10
    palette:
      background_color: "white"
      text_color: "black"
      key_label_color: "white"
      neutral_color: "#6F768B"
      layers:
        - base_color: "#3366CC"  # Simple color
        - base_color: "#CC6633"
          gradient:              # Custom gradient (6 colors)
            - "#CC6633"
            - "#AA5522"
            - "#884411"
            - "#663300"
            - "#442200"
            - "#221100"

Interactive TUI Configurator¶

The interactive TUI provides a visual editor for configuration files:

# Create a new configuration
skim configure --interactive

# Edit an existing configuration
skim configure --interactive --config skim-config.yaml

# Pre-populate layers from a keymap file
skim configure --interactive --keymap my-keymap.kbi

# Pre-create a specific number of layers
skim configure --interactive --layer-count 8

The TUI has three tabs:

Keyboard: Edit layer names, indices, variants, and hardware features.
Keycodes: Define keycode pre-processing rules and display overrides.
Style: Configure colors, borders, gradients, and visual options.

Key bindings:

Tab / Shift+Tab: Navigate between panels
Enter: Edit a field or select a list item
Escape: Cancel editing / go back
Ctrl+S: Save and quit
F1 or Alt+H: Show contextual help for the focused field

Doctor Command¶

Use skim doctor to check your system environment:

skim doctor

This verifies:

Whether Cairo is installed (for Cairo render engine)
Whether Playwright/Chromium is available (for Chromium render engine)

Render Engines¶

For generating non-vector images (PNG, JPEG, WEBP, AVIF), Skim requires a render engine. Two options are supported:

Chromium (Playwright): Uses a headless browser to render the SVG and capture a screenshot. This usually produces the most accurate results but requires installing Playwright browsers.
Cairo: Uses the Cairo graphics library. This is faster and lighter but requires system dependencies (libcairo) to be installed.

You can specify the render engine using the --render-engine flag or let Skim choose the first available one.

# Use Chromium
skim generate --keymap my.kbi --format png --render-engine chromium

# Use Cairo
skim generate --keymap my.kbi --format png --render-engine cairo