Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
26 commits
Select commit Hold shift + click to select a range
8b9e734
refactor: reorganize source into koalakeys package structure
rtuszik Mar 22, 2026
3128ebc
add pre-commit
rtuszik Mar 22, 2026
de1168b
refactor(generate_cheatsheet): extract separator and formatting helpers
rtuszik May 28, 2026
040bf75
refactor: simplify validation logic with validator list
rtuszik May 28, 2026
31b4b62
fix test imports
rtuszik May 28, 2026
09f9d25
exclude tests dir from pytest coverage
rtuszik May 28, 2026
308a961
remove bandit (use ruff B rules)
rtuszik May 28, 2026
68211db
update uv.lock
rtuszik May 28, 2026
3abae6c
feat: add theming support
rtuszik Jun 8, 2026
6a40aa6
refactor(theming): add assertions for theme mode existence
rtuszik Jun 8, 2026
f12d27a
ci(github): pin actions, disable checkout creds, add permissions
rtuszik Jun 8, 2026
86da727
test(browser): add Playwright browser tests and fixtures
rtuszik Jun 8, 2026
4f8d5c0
chore: workflow formatting
rtuszik Jun 9, 2026
924a323
feat(cli): add init, generate, and validate commands
rtuszik Sep 21, 2026
3d2dbb7
docs: update CLI usage, themes, and example screenshot
rtuszik Sep 21, 2026
68d1266
fix: harden validation, css paths, and failure reporting
rtuszik Oct 17, 2026
fa42d4c
chore: bump to version 1.0.0 and update quick start docs
rtuszik Oct 25, 2026
11088a5
chore: add mise configuration
rtuszik Oct 25, 2026
0f5d5e0
ci: add release-please and PyPI trusted publishing workflow
rtuszik Nov 2, 2026
e1b896d
fix(deps): regenerate uv.lock after rebase onto main
rtuszik Nov 2, 2026
aef89e4
fix: add release-please config, improve theme validation and cli
rtuszik Nov 2, 2026
872316b
docs: update images and add third-party licenses
rtuszik Nov 2, 2026
e180560
fix: keep theme default mode until toggled, quote init path per platform
rtuszik Nov 2, 2026
816c6c2
fix(cli): quote cmd metacharacters in Windows cd hint
rtuszik Nov 2, 2026
849c7b9
docs(themes): add theme token contract
rtuszik Nov 2, 2026
668a78a
refactor: use shlex.quote for init path and update theme cascade docs
rtuszik Nov 2, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 4 additions & 3 deletions .github/actions/setup-python/action.yml
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
---
name: "Setup Python and uv"
description: "Setup Python and uv with caching"
runs:
Expand All @@ -6,12 +7,12 @@ runs:
- name: Set up Python
uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7
with:
python-version-file: "pyproject.toml"
python-version-file: "pyproject.toml"
- name: Install uv
uses: astral-sh/setup-uv@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e # v10.3.2
with:
enable-cache: auto
version: 0.13.*
enable-cache: auto
version: 0.13.*
- name: Install dependencies
shell: bash
run: uv sync --locked --all-extras --dev
Expand Down
15 changes: 13 additions & 2 deletions .github/workflows/lint.yml
Original file line number Diff line number Diff line change
@@ -1,27 +1,38 @@
---
name: checks
on:
pull_request:
workflow_dispatch:

permissions:
contents: read

jobs:
lint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
with:
persist-credentials: false
- uses: ./.github/actions/setup-python
- run: |
uv run ruff check --fix
uv run ruff format
uv run ruff check --fix
uv run ruff format

typecheck:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
with:
persist-credentials: false
- uses: ./.github/actions/setup-python
- run: uv run ty check

vulture:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
with:
persist-credentials: false
- uses: ./.github/actions/setup-python
- run: uv run vulture --min-confidence 100 --exclude ".venv" .
31 changes: 22 additions & 9 deletions .github/workflows/pytest.yml
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
---
name: pytest
on:
pull_request:
Expand All @@ -11,20 +12,32 @@ jobs:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
with:
persist-credentials: false
- uses: ./.github/actions/setup-python
- run: |
uv run pytest

# Browser/Playwright tests are excluded by default (pytest.ini) and run
# only on pull requests, where we install Chromium for them.
- name: Install Playwright browser
if: github.event_name == 'pull_request'
run: |
uv run playwright install --with-deps chromium
- name: Run browser tests
if: github.event_name == 'pull_request'
run: |
uv run pytest -m browser

- name: Run tests (with coverage)
shell: bash # adds pipefail so test failures survive the tee
run: |
uv run pytest \
--junitxml=pytest.xml \
--cov-report=term-missing:skip-covered \
--cov=. \
| tee pytest-coverage.txt
uv run pytest \
--junitxml=pytest.xml \
--cov-report=term-missing:skip-covered \
--cov=. \
| tee pytest-coverage.txt

- name: Pytest coverage comment
uses: MishaKav/pytest-coverage-comment@9516bf7f32a9229cf18d5e1717ae387c7154f279 # main
with:
pytest-coverage-path: ./pytest-coverage.txt
junitxml-path: ./pytest.xml
pytest-coverage-path: ./pytest-coverage.txt
junitxml-path: ./pytest.xml
47 changes: 47 additions & 0 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,47 @@
---
name: release
on:
push:
branches: [main]
workflow_dispatch:

permissions: {}

jobs:
release-please:
runs-on: ubuntu-latest
permissions:
contents: write
pull-requests: write
outputs:
release_created: ${{ steps.release.outputs.release_created }}
tag_name: ${{ steps.release.outputs.tag_name }}
steps:
- id: release
uses: googleapis/release-please-action@45996ed1f6d02564a971a2fa1b5860e934307cf7 # v5.0.0
with:
config-file: release-please-config.json
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved
manifest-file: .release-please-manifest.json

publish:
needs: release-please
if: needs.release-please.outputs.release_created == 'true'
runs-on: ubuntu-latest
environment:
name: pypi
url: https://pypi.org/project/koalakeys/
permissions:
contents: read
id-token: write
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
ref: ${{ needs.release-please.outputs.tag_name }}
persist-credentials: false
- uses: astral-sh/setup-uv@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e # v10.3.2
with:
enable-cache: false
- name: Build
run: uv build
- name: Publish to PyPI
uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086 # v1.14.3
9 changes: 9 additions & 0 deletions .pre-commit-config.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
---

repos:
- repo: https://github.com/astral-sh/ruff-pre-commit
rev: v0.15.4
hooks:
- id: ruff-check
args: [--fix]
- id: ruff-format
3 changes: 3 additions & 0 deletions .release-please-manifest.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
{
".": "0.6.0"
}
85 changes: 64 additions & 21 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,19 +12,30 @@ A simple tool to create and manage portable keyboard shortcut cheat sheets.

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**: To create a cheat sheet, add a YAML file to the `cheatsheets` directory and run `python src/generate_cheatsheet.py`. For detailed YAML formatting instructions, see the [YAML Cheat Sheet Specification Guide](yaml_cheatsheet_spec.md).
> **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](yaml_cheatsheet_spec.md).

## Screenshots

<p align="center">
<img src="assets/images/KoalaKeys_Example.png">
</a>
</p>

<p align="center">
<img src="assets/images/KoalaKeys_Themes.png" alt="The built-in themes: catppuccin, dracula, gruvbox, nord, rose-pine, solarized">
</p>

## 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
Expand Down Expand Up @@ -58,42 +69,74 @@ Explore the demo to see how KoalaKeys works and to get ideas for creating custom

## Requirements

- Python 3.8+
- Python 3.9+
- [uv](https://docs.astral.sh/uv/)

## Installation

1. Clone the repository:
### Recommended: run as a tool (no clone)

```
git clone https://github.com/rtuszik/KoalaKeys
cd KoalaKeys
```
Run KoalaKeys directly with [uv](https://docs.astral.sh/uv/), no need to clone the repository:

```
uvx koalakeys init # scaffold ./koalakeys/cheatsheets/ with an example sheet
```
Comment thread
rtuszik marked this conversation as resolved.
Resolved

Or install it on your PATH:

2. Create and activate a virtual environment (optional):
```
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
```

3. Set up the output directory:
Create a `.env` file in the project root with:
```
CHEATSHEET_OUTPUT_DIR=path/to/your/output/directory
```
2. Run via `uv run koalakeys ...`.

## Usage

1. Create YAML files for your cheat sheets in the `cheatsheets` directory. For detailed instructions on how to format YAML files, please refer to the [YAML Cheat Sheet Specification Guide](yaml_cheatsheet_spec.md).
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.

2. Generate cheat sheets:
| 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). |

```
uv run src/generate_cheatsheet.py
```
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](yaml_cheatsheet_spec.md).

### 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:

3. Find the HTML cheat sheets in the specified output directory.
```yaml
theme: dracula
```

4. Open `index.html` to view the cheat sheet collection.
See the [YAML Cheat Sheet Specification Guide](yaml_cheatsheet_spec.md) for the built-in themes, user-theme authoring, and custom CSS.

## Schema

Expand Down
46 changes: 46 additions & 0 deletions THIRD_PARTY_LICENSES.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,46 @@
# Third-party licenses

KoalaKeys ships built-in color themes whose palettes (hex color values) are derived
from the following open-source projects. KoalaKeys reproduces only the color values
and palette names; no source files from these projects are included. The palette
names are used nominatively to identify which palette each theme reproduces and do
not imply any endorsement by their authors.

All listed palettes are distributed under the MIT License (Gruvbox as "MIT/X11").
The MIT permission notice below applies to each, with the respective copyright holders:

- **Catppuccin** — Copyright (c) 2021 Catppuccin — https://github.com/catppuccin/palette
- **Rosé Pine** — Copyright (c) mvllow — https://github.com/rose-pine/palette
- **Gruvbox** — Copyright (c) 2017 Pavel Pertsev (morhetz) — https://github.com/morhetz/gruvbox
- **Solarized** — Copyright (c) 2011 Ethan Schoonover — https://github.com/altercation/solarized
- **Nord** — Copyright (c) 2016-present Sven Greb <development@svengreb.de> — https://github.com/nordtheme/nord
- **Dracula** — Copyright (c) 2023 Dracula Theme — https://github.com/dracula/dracula-theme

## MIT License

```
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
```

## Fonts

The default `font_url` references **Iosevka** (Copyright Belleve Invis,
https://github.com/be5invis/Iosevka), licensed under the SIL Open Font License 1.1.
KoalaKeys links to a CDN-hosted webfont stylesheet and does not redistribute the
font files.
Binary file modified assets/images/KoalaKeys_Example.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added assets/images/KoalaKeys_Themes.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
14 changes: 14 additions & 0 deletions docs/schema/cheatsheet.schema.json
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,20 @@
"default": false,
"description": "When true, free-form shortcut text is allowed; requires RenderKeys=false."
},
"theme": {
"type": "string",
"minLength": 1,
"default": "catppuccin",
"description": "Theme name: a built-in (e.g. 'catppuccin') or a user theme in the project's themes/ directory. Defaults to 'catppuccin'."
},
"custom_css": {
"type": "string",
"description": "Filename of a custom CSS file (resolved from the project's styles/ directory), layered after the theme."
},
"custom_css_inline": {
"type": "string",
"description": "Inline custom CSS, emitted last in the cascade so it overrides the theme and the custom CSS file."
},
"layout": {
"type": "object",
"additionalProperties": false,
Expand Down
Loading
Loading