KoalaKeys

A simple tool to create and manage portable keyboard shortcut cheat sheets.

Demo: Check out the live demo to see a small collection of cheat sheets created with this project.

Overview

KoalaKeys generates and organizes portable, interactive HTML cheat sheets for keyboard shortcuts. It's designed for developers, designers, and power users who want to keep their essential shortcuts easily accessible.

Quick Start:

1. Run uvx koalakeys init to scaffold a project.
2. Run cd koalakeys.
3. Add or edit YAML files in the cheatsheets/ directory.
4. Run uvx koalakeys generate.

For detailed YAML formatting instructions, see the YAML Cheat Sheet Specification Guide.

Screenshots

Features

• Generate HTML cheat sheets from YAML files
• Interactive keyboard layout with real-time highlighting
• Six built-in themes (catppuccin, dracula, gruvbox, nord, rose-pine, solarized) plus user themes and custom CSS
• Categorized shortcuts with descriptions
• Index page for quick access to all cheat sheets
• Search functionality
• Support for different keyboard layouts and system mappings

Demo and Examples

A live demo instance is available, showcasing a selection of cheat sheets:

• Demo Site: https://rtuszik.github.io/KoalaKeys-Collection/
• Demo Repository: https://github.com/rtuszik/KoalaKeys-Collection

Explore the demo to see how KoalaKeys works and to get ideas for creating custom cheat sheets. The demo repository also contains example YAML files that can be used as templates for new cheat sheets.

Available Systems and Keyboards

Systems

• Darwin (macOS)
• Linux
• Windows

Keyboard Layouts

• US
• UK
• DE (German)
• FR (French)
• ES (Spanish)
• DVORAK

Requirements

• Python 3.9+
• uv

Installation

Recommended: run as a tool (no clone)

Run KoalaKeys directly with uv, no need to clone the repository:

uvx koalakeys init        # scaffold ./koalakeys/cheatsheets/ with an example sheet

Or install it on your PATH:

uv tool install koalakeys     # or: pipx install koalakeys

From source (for development)

1. Clone the repository and install dependencies:

   git clone https://github.com/rtuszik/KoalaKeys
   cd KoalaKeys
   uv sync --locked
   

2. Run via uv run koalakeys ....

Usage

KoalaKeys is a multi-command CLI. generate and validate operate on the current directory: they read cheatsheets/ and generate writes to output/ (or CHEATSHEET_OUTPUT_DIR if set). init creates the project in its path argument.

Command	What it does
koalakeys init [path]	Scaffold a new project directory with an example cheat sheet. Defaults to ./koalakeys; use . for the current directory. Pass --force to overwrite existing files.
koalakeys generate	Generate HTML for every YAML file in cheatsheets/, plus an index page.
koalakeys validate [file]	Validate cheat sheet YAML. Checks all of cheatsheets/ by default, or a single file. Exits non-zero on failure (CI-friendly).

Typical first run (with koalakeys on your PATH; otherwise prefix each command with uvx):

koalakeys init
cd koalakeys
koalakeys generate

Then open output/index.html to view the cheat sheet collection. For detailed YAML formatting, see the YAML Cheat Sheet Specification Guide.

Output directory (optional)

By default cheat sheets are written to output/ in the current directory. To change this, set CHEATSHEET_OUTPUT_DIR (e.g. in a .env file):

CHEATSHEET_OUTPUT_DIR=path/to/your/output/directory

Theming

Set a theme per cheat sheet with a single key:

theme: dracula

See the YAML Cheat Sheet Specification Guide for the built-in themes, user-theme authoring, and custom CSS.

Schema

Validate your YAML with the published JSON Schema:

• Public URL: https://rtuszik.github.io/KoalaKeys/schema/cheatsheet.schema.json

• Per-file modeline (first line in each YAML):

  # yaml-language-server: $schema=https://rtuszik.github.io/KoalaKeys/schema/cheatsheet.schema.json
  

• Neovim yamlls mapping (optional):

  require('lspconfig').yamlls.setup({
    settings = {
      yaml = {
        schemas = {
          ["https://rtuszik.github.io/KoalaKeys/schema/cheatsheet.schema.json"] = "cheatsheets/*.yaml",
        },
      },
    },
  })

Contributing

Contributions are welcome! Feel free to submit issues, feature requests, or pull requests.

License

This project is licensed under the terms of the GPLv3.