Merge pull request #15 from rtuszik/develop

v0.4.0 - allow disabling of keyboard history, allow text in shortcut field, add dvorak

.gitignore

@@ -2,7 +2,7 @@
 output/*
 
 cheatsheets/*
-!cheatsheets/example.yaml
+!cheatsheets/example-cheatsheet.yaml
 
 ### macOS ###
 # General

README.md

@@ -4,39 +4,41 @@
 
 # KoalaKeys
 
-A simple tool to create and manage interactive keyboard shortcut cheatsheets.
+A simple tool to create and manage portable keyboard shortcut cheat sheets.
 
-> **Demo**: Check out the [live demo](https://rtuszik.github.io/KoalaKeys-Collection/) to see a small collection of cheatsheets created with this project.
+> **Demo**: Check out the [live demo](https://rtuszik.github.io/KoalaKeys-Collection/) to see a small collection of cheat sheets created with this project.
 
 ## Overview
 
-KoalaKeys helps generate and organize interactive HTML cheatsheets for keyboard shortcuts. It's designed for developers, designers, and power users who want to keep their essential shortcuts easily accessible.
+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 cheatsheet, add a YAML file to the `cheatsheets` directory and run `python src/generate_cheatsheet.py`. For detailed YAML formatting instructions, see the [YAML Cheatsheet Specification Guide](yaml_cheatsheet_spec.md).
+> **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).
 
 ## Screenshots
 
 <p align="center">
   <img src="assets/images/KoalaKeys_Example.png">
+    <a href="https://ibb.co/LZ862ZB"><img src="https://i.ibb.co/qrd9Prh/Koala-Keys-Screen-Cast.gif" alt="Koala-Keys-Screen-Cast" border="0">
+    </a>
 </p>
 
 ## Features
 
-- Generate HTML cheatsheets from YAML files
+- Generate HTML cheat sheets from YAML files
 - Interactive keyboard layout with real-time highlighting
 - Categorized shortcuts with descriptions
-- Index page for quick access to all cheatsheets
+- 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 cheatsheets:
+A live demo instance is available, showcasing a selection of cheat sheets:
 
 - **Demo Site**: [https://rtuszik.github.io/KoalaKeys-Collection/](https://rtuszik.github.io/KoalaKeys-Collection/)
 - **Demo Repository**: [https://github.com/rtuszik/KoalaKeys-Collection](https://github.com/rtuszik/KoalaKeys-Collection)
 
-Explore the demo to see how KoalaKeys works and to get ideas for creating custom cheatsheets. The demo repository also contains example YAML files that can be used as templates for new cheatsheets.
+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
 
@@ -53,6 +55,7 @@ Explore the demo to see how KoalaKeys works and to get ideas for creating custom
 - DE (German)
 - FR (French)
 - ES (Spanish)
+- DVORAK
 
 ## Requirements
 
@@ -88,17 +91,17 @@ Explore the demo to see how KoalaKeys works and to get ideas for creating custom
 
 ## Usage
 
-1. Create YAML files for your cheatsheets in the `cheatsheets` directory. For detailed instructions on how to format YAML files, please refer to the [YAML Cheatsheet Specification Guide](yaml_cheatsheet_spec.md).
+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 cheatsheets:
+2. Generate cheat sheets:
 
    ```
    python src/generate_cheatsheet.py
    ```
 
-3. Find the HTML cheatsheets in the specified output directory.
+3. Find the HTML cheat sheets in the specified output directory.
 
-4. Open `index.html` to view the cheatsheet collection.
+4. Open `index.html` to view the cheat sheet collection.
 
 ## Contributing
 

cheatsheets/example-cheatsheet.yaml

@@ -0,0 +1,17 @@
+title: "KoalaKeys"
+RenderKeys: true # defaults to true
+AllowText: false # defaults to false - requires RenderKeys: false
+layout:
+  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"

cheatsheets/example.yaml

@@ -1,4 +1,6 @@
-title: "Default macOS Keyboard Shortcuts"
+title: "KoalaKeys"
+RenderKeys: true # defaults to true
+AllowText: true # defaults to false - requires RenderKeys: false
 layout:
   keyboard: US
   system: Darwin

src/generate_cheatsheet.py

@@ -8,6 +8,8 @@
 from logger import get_logger
 from pathlib import Path
 
+load_dotenv()
+
 # Define base paths
 BASE_DIR = Path(__file__).parent
 PROJECT_ROOT = BASE_DIR.parent
@@ -24,7 +26,6 @@
 logging = get_logger()
 
 # Load environment variables
-load_dotenv()
 
 def load_yaml(file_path: Path) -> dict | None:
     try:
@@ -94,12 +95,18 @@ def replace_shortcut_names(shortcut, system_mappings):
 
 def normalize_shortcuts(data, system_mappings):
     normalized = {}
+    allow_text = data.get('AllowText', False)
     try:
         for section, shortcuts in data.get("shortcuts", {}).items():
             normalized[section] = {}
             for shortcut, details in shortcuts.items():
-                normalized_shortcut = replace_shortcut_names(shortcut, system_mappings)
-                normalized[section][normalized_shortcut] = details
+                if allow_text:
+                    # When AllowText is true, just pass through the shortcut text
+                    normalized[section][shortcut] = details
+                else:
+                    # Normal processing for keyboard shortcuts
+                    normalized_shortcut = replace_shortcut_names(shortcut, system_mappings)
+                    normalized[section][normalized_shortcut] = details
     except Exception as e:
         logging.error(f"Error normalizing shortcuts: {e}")
     return normalized
@@ -121,6 +128,8 @@ def generate_html(data, keyboard_layouts, system_mappings):
     )
     data["layout"] = layout_info
     data["keyboard_layout"] = keyboard_layouts.get(layout_info["keyboard"], {}).get("layout")
+    data["render_keys"] = data.get("RenderKeys", True)
+    data["allow_text"] = data.get("AllowText", False)
 
     return render_template(template_path, data)
 

src/layouts/keyboard_layouts.yaml

@@ -48,7 +48,19 @@ US:
         "Enter",
       ]
     - ["Shift", "Z", "X", "C", "V", "B", "N", "M", ",", ".", "/", "Shift"]
-    - ["Ctrl", "Alt", "Cmd", "Space", "Cmd", "Alt", "Ctrl", "Left", "Up", "Down", "Right"]
+    - [
+        "Ctrl",
+        "Alt",
+        "Cmd",
+        "Space",
+        "Cmd",
+        "Alt",
+        "Ctrl",
+        "Left",
+        "Up",
+        "Down",
+        "Right",
+      ]
 
 UK:
   layout:
@@ -259,3 +271,67 @@ ES:
       ]
     - ["Shift", "Ç", "Z", "X", "C", "V", "B", "N", "M", ",", ".", "-", "Shift"]
     - ["Ctrl", "Alt", "Cmd", "Space", "Cmd", "Alt", "Ctrl"]
+
+DVORAK:
+  layout:
+    - [
+        "Esc",
+        "F1",
+        "F2",
+        "F3",
+        "F4",
+        "F5",
+        "F6",
+        "F7",
+        "F8",
+        "F9",
+        "F10",
+        "F11",
+        "F12",
+      ]
+    - [
+        "`",
+        "1",
+        "2",
+        "3",
+        "4",
+        "5",
+        "6",
+        "7",
+        "8",
+        "9",
+        "0",
+        "[",
+        "]",
+        "Backspace",
+      ]
+    - ["Tab", "'", ",", ".", "P", "Y", "F", "G", "C", "R", "L", "/", "=", "\\"]
+    - [
+        "CapsLock",
+        "A",
+        "O",
+        "E",
+        "U",
+        "I",
+        "D",
+        "H",
+        "T",
+        "N",
+        "S",
+        "-",
+        "Enter",
+      ]
+    - ["Shift", ";", "Q", "J", "K", "X", "B", "M", "W", "V", "Z", "Shift"]
+    - [
+        "Ctrl",
+        "Alt",
+        "Cmd",
+        "Space",
+        "Cmd",
+        "Alt",
+        "Ctrl",
+        "Left",
+        "Up",
+        "Down",
+        "Right",
+      ]