From 710137c63fc4907af4efcd1d74fc8b53790e7f1c Mon Sep 17 00:00:00 2001 From: Kosta Date: Sat, 2 Mar 2024 11:37:33 +0000 Subject: [PATCH] chore: readme and links updates --- README.md | 55 ++++++++++++++++++++++++++++++++++----------- assets/template.htm | 3 +-- 2 files changed, 43 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index 19b1486..852c5ce 100644 --- a/README.md +++ b/README.md @@ -2,8 +2,6 @@ > Transforms your application shortcuts into beautiful and comprehensive interactive graphics. -[Check out the demo on Zettlr's main website](https://zettlr.com/shortcuts)! - ![Apple macOS keyboard](./assets/mac-kbd.svg) * Do you develop an application but tend to lose sight over the shortcuts you already built into your app? @@ -14,26 +12,57 @@ If you answered any of the above questions with "yes," then this package is for It takes your shortcuts and creates a single-file cheatsheet which you can then either use locally, serve on your website, or even print out! -## Usage +## Differences from the original project +- Support for building multiple shortcuts profiles (only in the GitHub Actions workflow) +- GitHub Actions workflow to build cheatsheets without installing dependencies locally + +## Roadmap -First and foremost, you need to have **Node.js** installed on your computer. Optionally, make sure you got **Yarn**. Then either clone this repository, or download the ZIP file of it and extract it. Next, you need to install the dependencies (Webpack and YAML), so that building the maps works. Simply run `npm install` or `yarn install` in the directory to install them. +- [ ] Support for custom keyboard layouts ([ZMK](https://github.com/nickcoutsos/keymap-editor), [KLE](https://github.com/ijprest/keyboard-layout-editor?tab=readme-ov-file)) +- [ ] Printer friendly markup +- [ ] Language layout order customization. OS language detection -Then you can adapt the package and generate your own shortcuts. Simply copy the file `config.example.yml` to `config.yml` and add your shortcuts to it. Modify the settings if you wish. Finally, depending on whether you use NPM or Yarn, run `npm run build` or `yarn build`. The final cheatsheet will reside in `./dist`. +## Usage Need some inspiration? Then head over to the `./examples`-directory and have a look at some settings that will out of the box generate beautiful cheatsheets. -![Microsoft Surface keyboard](./assets/surface-kbd.svg) +### Building with GitHub Actions + +If you have a GitHub account, you can use the GitHub Actions to build your cheetsheets. Create a new repository using [this](https://github.com/senz/cheatsheet-config-template) template repo. + +1. Create a new repository using [the template](https://github.com/senz/cheatsheet-config-template) +2. Create a new shortcut configuration file `someapp.config.yaml` +3. Edit the `cheatsheet-build.yaml` file to include the new configuration file. Use [build-schema.json](./build-schema.json) as a reference to validate the build configuration file. +4. Commit and push the changes to the repository +5. Go to the Actions tab in the repository and click on the `cheatsheet-build` workflow. Download the artifacts from the workflow run. + +### Building locally with devcontainer + +You can use the devcontainer to build the cheatsheets locally. The devcontainer is a pre-configured development environment that runs in a Docker container. It contains all the tools and dependencies you need to build the cheatsheets. + +Setup the environment by following the [official guide](https://containers.dev/supporting). + +1. Clone the repository and open it in a devcontainer +2. Create a new shortcut configuration file `config.yml` in the root of the repository +3. Runt the `npm install` command to install the dependencies +3. Run the `npm run build` command to generate the cheatsheets + +Resulting cheatsheet will be available in the `dist` directory. -## Motivation & Caveats +NB: you can, of course, build the cheatsheets without using the devcontainer, but you will need to install the dependencies manually. Use the .devcontainer as a reference to install the required dependencies. Only GitHub Actions and devcontainer are officially supported. -While thinking of new shortcuts to add for desperately needed commands for [my app](https://github.com/Zettlr/Zettlr), I realised that I actually have no idea of the ergonomics of the app's shortcuts. Plus, I didn't know which keys were already occupied. So I began the usual process of finding a solution in the form of a visual shortcut designer: Google, Stackoverflow, Reddit. After I didn't even find any useful SVG-images of keyboards to built upon, I decided to act and spent a weekend coding two keyboards and this small tool. What it does is neither new nor revolutionary, it is inspired by the attempts of some other developers to visualise the shortcuts for their apps. Specifically, I thought of [KotOR II](https://starwars.fandom.com/wiki/Star_Wars:_Knights_of_the_Old_Republic_II:_The_Sith_Lords), which came with a decent, high-quality printed cheatsheet back in the day. -However, this means: +## Motivation & Caveats +This is a citation from the original author of the project: [Hendrik Erz](https://github.com/nathanlesage) -* This tool is not designed to be used as an on-screen keyboard. You can certainly use it that way, but then the tool around the SVG-files won’t be necessary. -* I only included two keyboards, because you don't need more, and these were already hard to code (I wrote the SVG files by hand and decided against a dedicated app to maintain readability and DRY). -* "Why a Surface keyboard?" There's a litany of different keyboards out there, and when I have to decide, I use the one from the same company which makes the software for these keyboards in the first place. It should also work for Linux, because, you know, there's no such thing as dedicated linux keyboards (at least not well-known). -* ~~Keys that are secondary on certain keyboard layouts (that is, you need to press the Shift-key to reach it) are not supported. Use `Shift+` instead.~~ Layer 2 and Layer 3 support is now available. +> While thinking of new shortcuts to add for desperately needed commands for [my app](https://github.com/Zettlr/Zettlr), I realised that I actually have no idea of the ergonomics of the app's shortcuts. Plus, I didn't know which keys were already occupied. So I began the usual process of finding a solution in the form of a visual shortcut designer: Google, Stackoverflow, Reddit. After I didn't even find any useful SVG-images of keyboards to built upon, I decided to act and spent a weekend coding two keyboards and this small tool. What it does is neither new nor revolutionary, it is inspired by the attempts of some other developers to visualise the shortcuts for their apps. Specifically, I thought of [KotOR II](https://starwars.fandom.com/wiki/Star_Wars:_Knights_of_the_Old_Republic_II:_The_Sith_Lords), which came with a decent, high-quality printed cheatsheet back in the day. +> +> However, this means: +> +> * This tool is not designed to be used as an on-screen keyboard. You can certainly use it that way, but then the tool around the SVG-files won’t be necessary. +> * I only included two keyboards, because you don't need more, and these were already hard to code (I wrote the SVG files by hand and decided against a dedicated app to maintain readability and DRY). +> * "Why a Surface keyboard?" There's a litany of different keyboards out there, and when I have to decide, I use the one from the same company which makes the software for these keyboards in the first place. It should also work for Linux, because, you know, there's no such thing as dedicated linux keyboards (at least not well-known). +> * ~~Keys that are secondary on certain keyboard layouts (that is, you need to press the Shift-key to reach it) are not supported. Use `Shift+` instead.~~ Layer 2 and Layer 3 support is now available. ## Adding shortcuts diff --git a/assets/template.htm b/assets/template.htm index b90cbac..5462a4d 100644 --- a/assets/template.htm +++ b/assets/template.htm @@ -53,8 +53,7 @@

$title$