https://github.com/townk/skim
Svalboard Keymap Image Maker is a command-line tool that generates beautiful, publication-ready images of your keyboard layouts. It takes keymap configuration files from popular keyboard firmware tools and produces SVG or PNG images that you can use for documentation, reference cards, or sharing your layouts with the community.
https://github.com/townk/skim
image keyboard keymap layout png svalboard svg typst
Last synced: about 1 month ago
JSON representation
Svalboard Keymap Image Maker is a command-line tool that generates beautiful, publication-ready images of your keyboard layouts. It takes keymap configuration files from popular keyboard firmware tools and produces SVG or PNG images that you can use for documentation, reference cards, or sharing your layouts with the community.
- Host: GitHub
- URL: https://github.com/townk/skim
- Owner: Townk
- License: mit
- Created: 2026-01-14T22:48:20.000Z (5 months ago)
- Default Branch: mainline
- Last Pushed: 2026-04-23T03:12:59.000Z (about 2 months ago)
- Last Synced: 2026-04-23T04:24:20.892Z (about 2 months ago)
- Topics: image, keyboard, keymap, layout, png, svalboard, svg, typst
- Language: Python
- Homepage: https://townk.github.io/skim/
- Size: 4.35 MB
- Stars: 3
- Watchers: 0
- Forks: 1
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# qmk-skim (Svalboard Keymap Image Maker)
[](https://github.com/Townk/skim)
[](https://www.python.org/downloads/)
[](https://github.com/Townk/skim/actions/workflows/release.yml)
[](https://badge.fury.io/py/qmk-skim)
A Python CLI tool for generating high-quality keymap layout images for the
[Svalboard](https://svalboard.com) keyboard.
## Features
- Generate individual layer keymap images with layer indicator circles
- Generate overview images showing all layers with connector lines
- Supports Tap-dance and Macro keys
- Interactive TUI configurator for editing configuration files
- System dependency checker (`skim doctor`)
- Support for multiple keymap formats:
- Keybard (`.kbi`)
- Vial (`.vil`)
- QMK c2json (`.json`)
- Configurable colors, layer names, and appearance
- High-quality output in multiple formats:
- Vector: SVG
- Raster: PNG, JPEG, WEBP, AVIF
- Stdin support for piping keymap data in scripts
## Installation
You can install `qmk-skim` using `pip`, `pipx`, or `uv`.
### Using uv (Recommended)
```bash
uv tool install 'qmk-skim[playwright,cairo,tui]'
```
You can upgrade to a new version using:
```bash
uv tool upgrade qmk-skim
```
### Using pipx
```bash
pipx install 'qmk-skim[playwright,cairo,tui]'
```
### Using pip
```bash
pip install 'qmk-skim[playwright,cairo,tui]'
```
## Usage
The package installs the `skim` command-line tool, but if you prefer to use the
tool without installing it, you can use `uvx`:
```bash
uvx --python 3.10 --from 'qmk-skim[cairo,playwright]' skim doctor
```
### Check your environment
```bash
# Verify system dependencies (render engines, etc.)
skim doctor
```
### Generate keymap images
```bash
# Generate all layers + overview from a keymap file
skim generate --keymap my-keymap.kbi --output-dir ./images
# Generate with custom configuration
skim generate --keymap my-keymap.kbi --config skim-config.yaml --output-dir ./images
# Generate specific layers only
skim generate --keymap my-keymap.kbi --layer 1 --layer 3-5 --layer overview
# Generate PNG output (requires Chromium or Cairo)
skim generate --keymap my-keymap.kbi --format png --output-dir ./images
# Read keymap from stdin
cat my-keymap.json | skim generate - --output-dir ./images
```
### Configure appearance
The easiest way to tweak your keymap image is to use our interactive
configurator where almost every configurable option is available for you to
learn and change.
```bash
# Launch the interactive TUI configurator
skim configure --interactive
# Edit an existing configuration file in the TUI
skim configure --interactive --config skim-config.yaml
# Generate a config from a Keybard keymap (extracts layer colors, names, custom keycodes)
skim configure --keymap my-keymap.kbi --output skim-config.yaml
# Import QMK named colors from color.h
skim configure --keymap my-keymap.kbi --qmk-color-header /path/to/color.h --output skim-config.yaml
```
## Development
This project uses `uv` for dependency management and `just` as a command runner.
### Setup
```bash
# Clone the repository
git clone https://github.com/Townk/skim.git
cd skim
# Install dependencies (dev + docs + extras)
just sync
```
### Testing
```bash
# Run all tests (unit + integration) with coverage
just tests
# Run only unit tests
just unit-tests
# Run only integration tests
just integration-tests
```
### Code Quality
```bash
# Run all checks (lint, format, type check)
just check
# Quick feedback loop (format + lint + typecheck)
just quick-check
# Full CI pipeline (all checks + all tests)
just ci
```
Individual checks:
```bash
just lint # Run ruff linter
just format # Format code with ruff
just format-check # Check formatting without modifying
just fix # Auto-fix lint issues
just typecheck # Run basedpyright
```
### Building
```bash
just build # Build the package
just build-docs # Build Sphinx documentation
just serve-docs # Build and open documentation in browser
just clean # Remove build artifacts and caches
```
## License
MIT License
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.