Modularize index template and add project setup

.github/actions/setup-python/action.yml

@@ -0,0 +1,20 @@
+name: "Setup Python and uv"
+description: "Setup Python and uv with caching"
+runs:
+    using: "composite"
+    steps:
+        - name: Set up Python
+          uses: actions/setup-python@v6
+          with:
+              python-version-file: "pyproject.toml"
+        - name: Install uv
+          uses: astral-sh/setup-uv@v7
+          with:
+              enable-cache: auto
+              version: 0.9.*
+        - name: Install dependencies
+          shell: bash
+          run: uv sync --locked --all-extras --dev
+        - name: Minimize cache
+          shell: bash
+          run: uv cache prune --ci

.github/dependabot.yml

@@ -1,15 +1,18 @@
 version: 2
 updates:
-  # Update Python packages
-  - package-ecosystem: "pip"
-    directory: "/"
-    schedule:
-      interval: "weekly"
-    open-pull-requests-limit: 10
+    - package-ecosystem: "github-actions"
+      directory: "/"
+      schedule:
+          interval: "weekly"
+      open-pull-requests-limit: 10
 
-  # Update GitHub Actions
-  - package-ecosystem: "github-actions"
-    directory: "/"
-    schedule:
-      interval: "weekly"
-    open-pull-requests-limit: 10
+    - package-ecosystem: "docker"
+      directory: "/"
+      schedule:
+          interval: "weekly"
+
+    - package-ecosystem: "uv"
+
+      directory: "/"
+      schedule:
+          interval: "weekly"

.github/workflows/lint.yml

@@ -1,36 +1,27 @@
-name: Lint
+name: checks
 on:
-  push:
-    branches-ignore: ["main"]
-  pull_request:
-    branches: ["main"]
-  workflow_dispatch:
-
-permissions: {}
-
+    pull_request:
+    workflow_dispatch:
 jobs:
-  lint:
-    runs-on: ubuntu-latest
-
-    permissions:
-      contents: read
-      packages: read
-      statuses: write
+    lint:
+        runs-on: ubuntu-latest
+        steps:
+            - uses: actions/checkout@v5
+            - uses: ./.github/actions/setup-python
+            - run: |
+                  uv run ruff check --fix
+                  uv run ruff format
 
-    steps:
-      - name: Checkout Code
-        uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
+    typecheck:
+        runs-on: ubuntu-latest
+        steps:
+            - uses: actions/checkout@v5
+            - uses: ./.github/actions/setup-python
+            - run: uv run ty check
 
-      - name: Lint Code Base
-        uses: github/super-linter@v7
-        env:
-          VALIDATE_ALL_CODEBASE: true
-          FIX_PYTHON_RUFF: true
-          VALIDATE_PYTHON_RUFF: true
-          FIX_MARKDOWN_PRETTIER: true
-          VALIDATE_MARKDOWN_PRETTIER: true
-          VALIDATE_GITLEAKS: true
-          VALIDATE_GITHUB_ACTIONS: true
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+    vulture:
+        runs-on: ubuntu-latest
+        steps:
+            - uses: actions/checkout@v5
+            - uses: ./.github/actions/setup-python
+            - run: uv run vulture --min-confidence 100 --exclude ".venv" .

.python-version

@@ -0,0 +1 @@
+3.13

README.md

@@ -64,44 +64,62 @@ Explore the demo to see how KoalaKeys works and to get ideas for creating custom
 
 1. Clone the repository:
 
-   ```
-   git clone https://github.com/rtuszik/KoalaKeys
-   cd KoalaKeys
-   ```
+    ```
+    git clone https://github.com/rtuszik/KoalaKeys
+    cd KoalaKeys
+    ```
 
 2. Create and activate a virtual environment (optional):
 
-   ```
-   python -m venv .venv
-   source .venv/bin/activate  # On Windows, use `venv\Scripts\activate`
-   ```
+    ```
+    uv sync --locked
+    ```
 
-3. Install dependencies:
-
-   ```
-   pip install -r requirements.txt
-   ```
-
-4. Set up the output directory:
+3. Set up the output directory:
    Create a `.env` file in the project root with:
-   ```
-   CHEATSHEET_OUTPUT_DIR=path/to/your/output/directory
-   ```
+    ```
+    CHEATSHEET_OUTPUT_DIR=path/to/your/output/directory
+    ```
 
 ## 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).
 
 2. Generate cheat sheets:
 
-   ```
-   python src/generate_cheatsheet.py
-   ```
+    ```
+    uv run src/generate_cheatsheet.py
+    ```
 
 3. Find the HTML cheat sheets in the specified output directory.
 
 4. Open `index.html` to view the cheat sheet collection.
 
+## 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):
+
+    ```lua
+    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.

cheatsheets/example-cheatsheet.yaml

@@ -1,17 +1,18 @@
+# yaml-language-server: $schema=https://rtuszik.github.io/KoalaKeys/schema/cheatsheet.schema.json
 title: "KoalaKeys"
 RenderKeys: true # defaults to true
 AllowText: false # defaults to false - requires RenderKeys: false
 layout:
-  keyboard: US
-  system: Darwin
+    keyboard: US
+    system: Darwin
 shortcuts:
-  General:
-    "CMD+C":
-      description: "Copy selected item"
-    "CMD+X":
-      description: "Cut selected item"
-  File and App Management:
-    "CMD+N":
-      description: "Open new window or document"
-    "CMD+O":
-      description: "Open selected item or display dialog to choose file to open"
+    General:
+        "CMD+C":
+            description: "Copy selected item"
+        "CMD+X":
+            description: "Cut selected item"
+    File and App Management:
+        "CMD+N":
+            description: "Open new window or document"
+        "CMD+O":
+            description: "Open selected item or display dialog to choose file to open"

docs/schema/cheatsheet.schema.json

@@ -0,0 +1,127 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://rtuszik.github.io/KoalaKeys/schema/cheatsheet.schema.json",
+  "title": "KoalaKeys Cheatsheet",
+  "description": "Schema for KoalaKeys YAML cheatsheets.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["title", "layout", "shortcuts"],
+  "properties": {
+    "title": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Title of the cheatsheet."
+    },
+    "RenderKeys": {
+      "type": "boolean",
+      "default": true,
+      "description": "When true (default), render keyboard layout with highlighted keys."
+    },
+    "AllowText": {
+      "type": "boolean",
+      "default": false,
+      "description": "When true, free-form shortcut text is allowed; requires RenderKeys=false."
+    },
+    "layout": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["keyboard", "system"],
+      "properties": {
+        "keyboard": {
+          "type": "string",
+          "enum": ["US", "UK", "DE", "FR", "ES", "DVORAK"],
+          "description": "Keyboard layout."
+        },
+        "system": {
+          "type": "string",
+          "enum": ["Darwin", "Windows", "Linux"],
+          "description": "Operating system."
+        }
+      }
+    },
+    "shortcuts": {
+      "type": "object",
+      "minProperties": 1,
+      "description": "Categories mapped to shortcut definitions.",
+      "additionalProperties": {
+        "type": "object",
+        "minProperties": 1
+      }
+    }
+  },
+  "allOf": [
+    {
+      "description": "AllowText=true requires RenderKeys=false.",
+      "if": {
+        "properties": { "AllowText": { "const": true } },
+        "required": ["AllowText"]
+      },
+      "then": {
+        "properties": {
+          "RenderKeys": { "const": false },
+          "shortcuts": {
+            "additionalProperties": {
+              "additionalProperties": { "$ref": "#/$defs/shortcutEntry" }
+            }
+          }
+        }
+      }
+    },
+    {
+      "description": "When AllowText is not true, restrict shortcut key syntax.",
+      "if": {
+        "not": {
+          "properties": { "AllowText": { "const": true } },
+          "required": ["AllowText"]
+        }
+      },
+      "then": {
+        "properties": {
+          "shortcuts": {
+            "additionalProperties": {
+              "type": "object",
+              "minProperties": 1,
+              "patternProperties": {
+                "^[A-Za-z0-9+⌘⌥⌃⇧←→↑↓\\s\\-\\|\\[\\],.:/`\"?<>=\\\\⌃]+$": {
+                  "$ref": "#/$defs/shortcutEntry"
+                }
+              },
+              "additionalProperties": false
+            }
+          }
+        }
+      }
+    }
+  ],
+  "$defs": {
+    "shortcutEntry": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["description"],
+      "properties": {
+        "description": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Human-readable description of the shortcut."
+        }
+      },
+      "examples": [
+        { "description": "Copy selected item" }
+      ]
+    }
+  },
+  "examples": [
+    {
+      "title": "KoalaKeys",
+      "RenderKeys": true,
+      "AllowText": false,
+      "layout": { "keyboard": "US", "system": "Darwin" },
+      "shortcuts": {
+        "General": {
+          "CMD+C": { "description": "Copy selected item" },
+          "CMD+Right": { "description": "Move cursor to end of line" }
+        }
+      }
+    }
+  ]
+}