📝 Restructure documentation a bit

README.md

@@ -67,7 +67,7 @@ For both approaches there are instructions available in the [:memo: Installation
 
 Kando comes with an example menu which you can open by pressing <kbd>Ctrl</kbd>+<kbd>Space</kbd> on most platforms.
 This is great to get a first impression!
-To learn some basics about the interaction with Kando, you can have a look at the [:memo: Usage Guide](docs/usage.md).
+To learn some basics about the interaction with Kando, you can have a look at the [:memo: Usage Guide](docs/getting-started.md).
 
 Once you are familiar with the basics, you can start creating your own menus.
 Learn how to create your own menus in the [:memo: Configuration Guide](docs/configuring.md)!

docs/README.md

@@ -21,7 +21,7 @@ If you want to improve this documentation, please [open a pull request](https://
 ## Getting Started
 
 * [Installation](installing.md)
-* [Usage](usage.md)
+* [Getting Started](getting-started.md)
 * [Configuration](configuring.md)
 
 ## Advanced Topics

docs/changelog.md

@@ -223,8 +223,8 @@ This changelog follows the rules of [Keep a Changelog](http://keepachangelog.com
 
 - Support for HiDPI screens. Kando will now properly warp the mouse pointer to the center of a menu item even if display scaling is enabled.
 - Better example menus. When you launch Kando for the first time (or delete your `menus.json` file), you will now see a more useful example menu. This menu depends on the platform you are using. There are some hard-coded applications and keyboard shortcuts, but you can easily change them in the menu editor.
-- Some initial usage documentation. You can read it [here](usage.md).
-- Some documentation about the [format of the shortcuts and hotkeys used in Kando](configuring.md#menu-shortcuts-vs-simulated-hotkeys).
+- Some initial usage documentation. You can read it [here](getting-started.md).
+- Some documentation about the [format of the shortcuts and hotkeys used in Kando](configuring.md#keyboard-menu-shortcuts-vs-simulated-hotkeys).
 - Issue templates. If you now [open a new issue](https://github.com/kando-menu/kando/issues/new/choose), you can choose from different templates.
 - A [Code of Conduct](code-of-conduct.md). This is a set of rules which defines the behavior of contributors and users in the Kando community. It is important to read and understand this document before contributing to Kando.
 

docs/config-files.md

@@ -101,7 +101,7 @@ They are JSON objects with the following properties:
 
 Property | Default Value | Description
 -------- | ------------- | -----------
-`shortcut` | `""` | The shortcut which opens the menu. This is a string which can contain multiple keys separated by `+`. For example, `"Ctrl+Shift+K"` or `"Cmd+Shift+K"`. If empty, the menu will not have a shortcut. See [Menu Shortcuts vs. Simulated Hotkeys](configuring.md#menu-shortcuts-vs-simulated-hotkeys) for details.
+`shortcut` | `""` | The shortcut which opens the menu. This is a string which can contain multiple keys separated by `+`. For example, `"Ctrl+Shift+K"` or `"Cmd+Shift+K"`. If empty, the menu will not have a shortcut. See [Menu Shortcuts vs. Simulated Hotkeys](configuring.md#keyboard-menu-shortcuts-vs-simulated-hotkeys) for details.
 `shortcutID` | `""` | On some platforms, Kando can not bind shortcuts directly. In this case, you can use this property to assign an ID which can be used in the global shortcut configuration of your desktop environment. This should be lowercase and contain only ASCII characters and dashes. For example, `"main-trigger"`.
 `root` | _mandatory_ | The root menu item of the menu given as a Menu Item Description. See below for details.
 `centered` | `false` | Whether the menu should be centered on the screen. If this is `false`, the menu will be opened at the position of the mouse cursor.
@@ -184,7 +184,7 @@ For instance, this menu item will open GitHub in the default browser:
 This type is used to simulate simple keyboard events.
 The `data` property of the menu item must contain a `hotkey` property which contains the hotkey to simulate.
 See [Menu Shortcuts vs.
-Simulated Hotkeys](configuring.md#menu-shortcuts-vs-simulated-hotkeys) for details on the format of the `hotkey` property.
+Simulated Hotkeys](configuring.md#keyboard-menu-shortcuts-vs-simulated-hotkeys) for details on the format of the `hotkey` property.
 The optional `delayed` property will ensure that the hotkey is simulated _after_ the Kando window is closed.
 This can be used if the hotkey should be captured by another window.
 For instance, this menu item will paste the clipboard content:
@@ -204,7 +204,7 @@ For instance, this menu item will paste the clipboard content:
 #### `"macro"`
 This type is used to simulate a more comples sequence of keyboard events.
 The `data` property of the menu item must contain a `macro` property which contains the sequence of key codes to simulate.
-See [Menu Shortcuts vs. Simulated Hotkeys](configuring.md#menu-shortcuts-vs-simulated-hotkeys) for details on key code format.
+See [Menu Shortcuts vs. Simulated Hotkeys](configuring.md#keyboard-menu-shortcuts-vs-simulated-hotkeys) for details on key code format.
 The optional `delayed` property will ensure that the macro is simulated _after_ the Kando window is closed.
 This can be used if the macro should be captured by another window.
 For instance, this menu item will type "Hi" on most keyboard layouts:

docs/configuring.md

@@ -24,14 +24,14 @@ Drag new items from the toolbar to the menu preview, reorder them, and change th
 > [!TIP]
 > There are several advanced options which are not yet exposed in the editor UI. See the [Config-File Documentation](config-files.md) for all advanced options.
 
-## Tips for Creating Efficient Menu Layouts :rocket:
+## 🚀 Tips for Creating Efficient Menu Layouts
 
 When designing your own menus, keep the following tips in mind:
 * **Avoid too many items in a single menu.** Instead, create submenus. Eight items per menu is a good rule of thumb, and you should never have more than twelve items in a single menu.
 * **Deeply nested menus are not a problem.** Kando is designed to handle deeply nested menus. You can use the marking mode to quickly select items which are in subsubsubmenus.
 * **Use the fixed-angle locks to create a clean layout.** Even if you have an odd number of items, you can use fixed angles to lock items to the top, bottom, left, or right side of the menu.
 
-## Adding Custom Icon Themes :sparkles:
+## ✨ Adding Custom Icon Themes
 
 To add your own icons to Kando, follow these steps:
 1. Create a new `icon-themes` directory in Kando's configuration directory if it does not yet exist. Depending on your OS, this will be the following locations:
@@ -54,8 +54,40 @@ To add your own icons to Kando, follow these steps:
   * [Papirus](https://github.com/PapirusDevelopmentTeam/papirus-icon-theme): Here you could use the content from the `Papirus/64x64` directory.
   * [Tela](https://github.com/vinceliuice/Tela-icon-theme): Here you find the icons in the `src/scalable` directory.
 
+## 🖱️ Opening Menus without the Keyboard
 
-## Menu Shortcuts vs. Simulated Hotkeys :keyboard:
+While Kando does not have a cross-platform way to open menus with a mouse button, there are many platform-dependent third-party tools which can help you with this.
+With some creativity, you can open menus not only with mouse buttons but also with gestures, desktop widgets, or in many other ways.
+
+You can either make the third-party tool open the menu by simulation the shortcut for the menu, or it can directly call the Kando executable with the `--menu "menu name"` argument.
+
+* <img height="14" width="26" src="https://upload.wikimedia.org/wikipedia/commons/c/c4/Windows_logo_-_2021_%28Black%29.svg" /> Windows: `%localappdata%\Kando\app-<version number>\Kando.exe --menu "Menu Name"`
+* <img height="14" width="26" src="https://cdn.simpleicons.org/apple" /> macOS: `/Applications/Kando.app/Contents/MacOS/Kando --menu "Menu Name"`
+* <img height="14" width="26" src="https://cdn.simpleicons.org/linux/black" /> Linux: `/usr/bin/kando --menu "Menu Name"`
+
+Below are some applications which can help you to open menus in various ways.
+If you discovered a cool new way to open menus, please let us know! You can either open an issue, open a pull request, or join the [Discord server](https://discord.gg/hZwbVSDkhy) to discuss your idea!
+
+### <img height="14" width="26" src="https://upload.wikimedia.org/wikipedia/commons/c/c4/Windows_logo_-_2021_%28Black%29.svg" /> Windows
+
+* [AutoHotkey](https://www.autohotkey.com/) is a powerful scripting language for Windows. You can use it to run the kando command when you press a mouse button or to remap a mouse button to a keyboard shortcut which opens a Kando menu.
+* [GestureSign](https://www.microsoft.com/store/productId/9N45WQVK2QQW?ocid=pdpshare) allows opening a Kando menu with multi-touch taps and gestures on both touchpad and touchscreen.
+
+### <img height="14" width="26" src="https://cdn.simpleicons.org/apple" /> macOS
+
+* [Karabiner-Elements](https://karabiner-elements.pqrs.org/) can be used to remap mouse buttons to keyboard shortcuts.
+* [BetterTouchTool](https://folivora.ai/) allows opening a Kando menu via touchpad gestures.
+* [BetterMouse](https://better-mouse.com/) is a tool which allows you to remap mouse buttons to keyboard shortcuts.
+
+### <img height="14" width="26" src="https://cdn.simpleicons.org/linux/black" /> Linux
+
+* [Input Remapper](https://github.com/sezanzeb/input-remapper) is a tool which allows you to remap mouse buttons to keyboard shortcuts. It works both on **X11 and Wayland**.
+* [Touchegg](https://github.com/JoseExposito/touchegg#readme) is a multitouch gesture recognizer for Linux. You can use it to open a Kando menu with touchpad gestures. It only works on **X11**.
+* **KDE Plasma** comes with built-in support for remapping mouse buttons to keyboard shortcuts. You can find [this feature](https://www.phoronix.com/news/KDE-Rebind-Extra-Mouse-Buttons) in the system settings under "System Settings" / "Mouse & Touchpad" / "Add Binding".
+* There's a [Configurable Button](https://store.kde.org/p/1297839/) widget for **KDE Plasma** which allows running `kando --menu "menu name"` when clicked.
+* On **GNOME Shell**, you can use the [CHC-E (Custom Hot Corners - Extended)](https://extensions.gnome.org/extension/4167/custom-hot-corners-extended/) extension to run arbitrary commands when you move your mouse to a corner of the screen.
+
+## :keyboard: Menu Shortcuts vs. Simulated Hotkeys
 
 With Kando, you can bind a menu to a keyboard shortcut and use menu items to simulate keyboard hotkeys or macros.
 This is a bit confusing as all are configured similarly, but use different formats.
@@ -273,7 +305,7 @@ Note that not all key codes are available on all platforms.
 
 <p align="center">
   <img src="img/nav-space.svg"/>
-  <a href="usage.md"><img src ="img/left-arrow.png"/> Using Kando</a>
+  <a href="getting-started.md"><img src ="img/left-arrow.png"/> Getting Started</a>
   <img src="img/nav-space.svg"/>
   <a href="README.md"><img src ="img/home.png"/> Index</a>
   <img src="img/nav-space.svg"/>

docs/getting-started.md

@@ -0,0 +1,76 @@
+<!--
+SPDX-FileCopyrightText: Simon Schneegans <code@simonschneegans.de>
+SPDX-License-Identifier: CC-BY-4.0
+-->
+
+<img src="img/banner08.png"></img>
+
+# Getting Started with Kando!
+
+Kando comes with a small example menu which you can use to get started.
+However, you should soon [configure your own menu](configuring.md) to make the most out of Kando.
+
+
+## 🚀 Starting Kando for the First Time
+
+When you launch Kando, nothing will happen at first.
+You will only see a small icon in the system tray.
+However, on most platforms, you can open an example menu by pressing <kbd>Ctrl</kbd> + <kbd>Space</kbd>.
+
+There are some exceptions where this will not work.
+See the [platform-specific installation notes](installing.md#platform-specific-notes) for details.
+It can also happen that the shortcut is already used by another application.
+In this case, you can use the tray icon to open the settings and change the shortcut of the example menu.
+
+## 💡 The Idea of Kando
+
+<a href="https://www.youtube.com/watch?v=elHUCarOiXQ">
+<img align="right" width="500px" src="img/player12.jpg"></img>
+</a>
+
+Kando uses [Fitts's Law](https://en.wikipedia.org/wiki/Fitts%27s_law) to make menu navigation as fast as possible.
+You do not have to aim at the items you want to select, but you can click anywhere in the wedge of an item.
+
+In additions, Kando is a _marking menu_ (which were [described first about 30 years ago by Gordon Kurtenbach](https://www.research.autodesk.com/app/uploads/2023/03/the-design-and-evaluation.pdf_recHpUp1v9dc1n2CJ.pdf)).
+As such it allows you to select items by drawing zig-zag lines. This is extremely powerful!
+**You can select things in subsubsubmenus in well below a second without looking at your screen!**
+
+You can watch the video on the right to get an idea of how fast you can navigate through a menu with Kando.
+
+### 🎯 The Default Navigation Modes
+
+At first, you will probably use the point-and-click method.
+Once you get more comfortable with Kando, you can try the marking mode, and even the turbo mode.
+
+| Navigation Method | Example |
+| --- | --- |
+| **Point and Click:** The most basic approach for selecting items is by clicking at them. Although you do not have to click directly at the item, anywhere in the item's wedge will do! <br><br> This can make selections very fast as you **do not have to aim carefully**. | <video src="https://github.com/kando-menu/kando/assets/829942/ccb9f5df-cc9e-4dd4-ac07-e37ebf797699"> |
+| **Marking Mode:** With Kando, you can select items by drawing gestures! To do so, simply press your left mouse button, and drag over an item. You will move the item around, until you stop the movement or make a sharp turn. Try to remember the path to an item and draw it without looking much at the menu! You will be surprised how quickly you can select items which are deeply nested in the menu. <br><br> **For successful selections, it is better to draw expressive zig-zag lines instead of shy and curvy lines :smiley:** | <video src="https://github.com/kando-menu/kando/assets/829942/bb0e0041-b599-4493-a7b1-7c39103d19cb"> |
+| **Turbo Mode:** If you opened the menu using a key combination, you can keep a key pressed. If you do so, the menu will behave as if the left mouse button is pressed, and you can easily browse through the menu without having to click anywhere. Once you release the key, the currently dragged item will be selected. **This allows you to make even faster selections!** <br><br> Turbo-Mode works best with <kbd>Ctrl</kbd>, <kbd>Shift</kbd>, <kbd>Alt</kbd>, or <kbd>Meta</kbd>. For all other keys there will be a short delay until Turbo-Mode kicks in. If this delay is too long for your liking, you can hit the key quickly twice - this way Kando will get the key-down event faster and Turbo-Mode will work right out of the box! | <video src="https://github.com/kando-menu/kando/assets/829942/8f56791e-f9ae-4af1-85a4-cf33da15af65"> |
+
+#### Alternative Navigation Modes
+
+People are different and so are their preferences.
+Therefore, Kando comes with options like the **"Centered Mode"** or the **"Anchored Mode"** which change this default behavior.
+Especially on smaller touch screens or with gamepad input, these options may be beneficial.
+
+You can watch the video linked above to get an idea of how these modes work.
+
+> [!TIP]
+> We recommend to learn the default behavior first and only change it if you are really sure that it is not working for you. It may take some time to get used to it, but it is worth it! You will be surprised how fast you _can do_ something after you mastered it! 🍰🚀
+
+## 🛠️ Next up: Configuring Kando!
+
+Once you are comfortable with the default menu, you should [configure your own menus](configuring.md).
+
+<p align="center"><img src ="img/hr.svg" /></p>
+
+<p align="center">
+  <img src="img/nav-space.svg"/>
+  <a href="installing.md"><img src ="img/left-arrow.png"/> Installing Kando</a>
+  <img src="img/nav-space.svg"/>
+  <a href="README.md"><img src ="img/home.png"/> Index</a>
+  <img src="img/nav-space.svg"/>
+  <a href="configuring.md">Configuring Kando <img src ="img/right-arrow.png"/></a>
+  <img src="img/nav-space.svg"/>
+</p>

docs/installing.md

@@ -23,7 +23,7 @@ If you chose the installer, you will find Kando in your start menu after the ins
 As the executables are not signed, Windows will show a warning when you try to run them.
 Just click on "More info" and then on "Run anyway".
 
-Continue reading the [:memo: Usage Guide](usage.md) to learn how to interact with Kando!
+Continue reading the [:memo: Usage Guide](getting-started.md) to learn how to interact with Kando!
 
 ## <img height="20" width="26" src="https://cdn.simpleicons.org/apple" /> Downloading Kando for macOS
 
@@ -42,7 +42,7 @@ If you chose the installer, you will find Kando in your launchpad after the inst
 > [!IMPORTANT]
 > After downloading and installing, make sure to read the [platform-spedific notes below](https://github.com/kando-menu/kando/blob/main/docs/installing.md#platform-specific-notes)!
 
-Continue reading the [:memo: Usage Guide](usage.md) to learn how to interact with Kando!
+Continue reading the [:memo: Usage Guide](getting-started.md) to learn how to interact with Kando!
 
 ## <img height="20" width="26" src="https://cdn.simpleicons.org/linux/black" /> Downloading Kando for Linux
 
@@ -65,7 +65,7 @@ Thereafter, you can run Kando from your main menu.
 > [!IMPORTANT]
 > After downloading and installing, make sure to read the [platform-spedific notes below](https://github.com/kando-menu/kando/blob/main/docs/installing.md#platform-specific-notes)!
 
-Continue reading the [:memo: Usage Guide](usage.md) to learn how to interact with Kando!
+Continue reading the [:memo: Usage Guide](getting-started.md) to learn how to interact with Kando!
 
 ## :gear: Building Kando Yourself
 
@@ -238,6 +238,6 @@ Depending on your platform, the `kando` executable will be located in different
   <img src="img/nav-space.svg"/>
   <a href="README.md"><img src ="img/home.png"/> Index</a>
   <img src="img/nav-space.svg"/>
-  <a href="usage.md">Using Kando <img src ="img/right-arrow.png"/></a>
+  <a href="getting-started.md">Getting Started <img src ="img/right-arrow.png"/></a>
   <img src="img/nav-space.svg"/>
 </p>