From 5a3e8bb593b8107cc90bd46e1bff1d9c44c0de2d Mon Sep 17 00:00:00 2001 From: Alicia Sykes Date: Sun, 22 Aug 2021 13:40:52 +0100 Subject: [PATCH] :memo: Writes docs about Searching and Shortcuts --- README.md | 59 +++++++++++++++++++++++++++++------------------ docs/readme.md | 1 + docs/searching.md | 53 ++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 91 insertions(+), 22 deletions(-) create mode 100644 docs/searching.md diff --git a/README.md b/README.md index 93238799..c2291eac 100644 --- a/README.md +++ b/README.md @@ -56,22 +56,25 @@ ## Features 🌈 -- Instant search by name, domain and tags - just start typing -- Full customizable keyboard shortcuts for navigation, filtering and launching apps -- Multiple built-in color themes, with UI color editor and support for custom CSS -- Customizable layout, sizes, text, component visibility, behavior and colors etc -- Many options for icons, including Font-Awesome support, auto-fetching favicon, images and emojis -- Option to show service status for each of your apps / links, for basic availability and uptime monitoring -- Choose how to launch apps, either in your browser, a pop-up modal or workspace view -- Option for full-screen background image, custom nav-bar links, html footer, title, and more -- Optional encrypted cloud backup and restore feature available -- Optional authentication with multi-user support and configurable privileges for protecting your dashboard -- Small bundle size, fully responsive UI and PWA makes the app easy to use on any device -- Easy to setup with Docker, or on bare metal, or with 1-Click cloud deployment -- Multi-language support, with more languages being added regularly -- Easy single-file YAML-based configuration, or configure app directly through the UI -- Strong focus on privacy -- Plus lots more... +- 🔎 Instant search by name, domain and tags - just start typing + customizable keyboard shortcuts +- 🎨 Multiple built-in color themes, with UI color editor and support for custom CSS +- 🧸 Many options for icons, including Font-Awesome support, auto-fetching favicon, images and emojis +- đŸšĻ Service status feature for each of your apps / links, for basic availability and uptime monitoring +- 💂 Optional authentication with multi-user support, configurable privileges and SSO support +- ☁ Optional encrypted cloud backup and restore feature available +- đŸ’ŧ A workspace view, for easily switching between multiple apps at once +- 🛩ī¸ A minimal view, for use as a fast-loading browser startpage +- 🖱ī¸ Choose how to launch apps, either new tab, same tab, a pop-up modal or in the workspace view +- 🌎 Multi-language support, with more languages being added regularly +- 📏 Customizable layout, sizes, text, component visibility, behavior and colors etc +- đŸ–ŧī¸ Option for full-screen background image, custom nav-bar links, html footer, title, and more +- 🚀 Easy to setup with Docker, or on bare metal, or with 1-Click cloud deployment +- 🤏 Small bundle size, fully responsive UI and PWA makes the app easy to use on any device +- ⚙ī¸ Easy single-file YAML-based configuration, with option to configure app directly through the UI +- ✨ Under active development with improvements and new features added regularly +- 🆓 100% free and open source +- 🔐 Strong focus on privacy +- 🌈 Plus lots more... ## Demo ⚡ @@ -328,6 +331,17 @@ Quickly finding and launching applications is the primary aim of Dashy. To that To start filtering, just start typing. No need to select the search bar or use any special key. You can then use either the tab key or arrow keys to select and move between results, and hit enter to launch the currently selected application. You can also use `Alt + Enter` on a selected app to launch it in a popup modal, `Ctrl + Enter` to open in new tab, or right-click on it to see all opening methods. +You can also add custom tags to a given item, to make finding them based on keywords easier. For example, in the following example, searching for 'Movies' will show 'Plex' + +```yaml + items: + - title: Plex + description: Media library + icon: favicon + url: https://plex.lab.local + tags: [ movies, videos, music ] +``` + For apps that you use regularly, you can set a custom keybinding. Use the `hotkey` parameter on a certain item to specify a numeric key, between `0 - 9`. You can then launch that app, by just pressing that key, which is very useful for services you use frequently. Example: @@ -567,17 +581,18 @@ If you're new to web development, I've put together a short [list of resources]( - 🛡ī¸ [Authentication](/docs/authentication.md) - Guide to setting up authentication to protect your dashboard - đŸ§ŋ [Alternate Views](/docs/alternate-views.md) - Outline of available pages / views and item opening methods - 💾 [Backup & Restore](/docs/backup-restore.md) - Guide to Dashy's cloud sync feature -- đŸšĻ [Status Indicators](/docs/status-indicators.md) - Using Dashy to monitor uptime and status of your apps - 🧸 [Icons](/docs/icons.md) - Outline of all available icon types for sections and items - 🌐 [Language Switching](/docs/multi-language-support.md) - How to change language, add a language, or update text +- đŸšĻ [Status Indicators](/docs/status-indicators.md) - Using Dashy to monitor uptime and status of your apps +- 🔍 [Searching & Shortcuts](/docs/searching.md) - Finding and launching your apps, and using keyboard shortcuts - 🎨 [Theming](/docs/theming.md) - Complete guide to applying, writing and modifying themes and styles #### Misc -- [🔐 Privacy & Security](/docs/privacy.md) - List of requests, potential issues, and security resources -- [📄 License](/LICENSE) - Copy of the MIT License -- [⚖ī¸ Legal](/.github/LEGAL.md) - Licenses of direct dependencies -- [📏 Code of Conduct](/.github/CODE_OF_CONDUCT.md) - Contributor Covenant Code of Conduct -- [đŸŒŗ Changelog](/.github/CHANGELOG.md) - Details of recent changes, and historical versions +- 🔐 [Privacy & Security](/docs/privacy.md) - List of requests, potential issues, and security resources +- 📄 [License](/LICENSE) - Copy of the MIT License +- ⚖ī¸ [Legal](/.github/LEGAL.md) - Licenses of direct dependencies +- 📏 [Code of Conduct](/.github/CODE_OF_CONDUCT.md) - Contributor Covenant Code of Conduct +- đŸŒŗ [Changelog](/.github/CHANGELOG.md) - Details of recent changes, and historical versions **[âŦ†ī¸ Back to Top](#dashy)** diff --git a/docs/readme.md b/docs/readme.md index 94521204..922d30a6 100644 --- a/docs/readme.md +++ b/docs/readme.md @@ -21,6 +21,7 @@ - [Icons](/docs/icons.md) - Outline of all available icon types for sections and items - [Language Switching](/docs/multi-language-support.md) - Details on how to switch language, or add a new locale - [Status Indicators](/docs/status-indicators.md) - Using Dashy to monitor uptime and status of your apps +- [Searching & Shortcuts](/docs/searching.md) - Finding and launching your apps, and using keyboard shortcuts - [Theming](/docs/theming.md) - Complete guide to applying, writing and modifying themes and styles ### Misc diff --git a/docs/searching.md b/docs/searching.md new file mode 100644 index 00000000..b8540e86 --- /dev/null +++ b/docs/searching.md @@ -0,0 +1,53 @@ +# Keyboard Shortcuts + +## Searching +One of the primary purposes of Dashy is to allow you to quickly find and launch a given app. To make this as quick as possible, there is no need to touch the mouse, or press a certain key to begin searching - just start typing. Results will be filtered in real-time. No need to worry about case, special characters or small typos, these are taken care of, and your results should appear. + +## Navigating +You can navigate through your items or search results using the keyboard. You can use Tab to cycle through results, and Shift + Tab to go backwards. Or use the arrow keys, ↑, →, ↓ and ←. + +## Launching Apps +You can launch a elected app by hitting Enter. This will open the app using your default opening method, specified in `target` (either `newtab`, `sametab`, `modal` or `workspace`). You can also use Alt + Enter to open the app in a pop-up modal, or Ctrl + Enter to open it in a new tab. For all available opening methods, just right-click on an item, to bring up the context menu. + +## Tags +By default, items are filtered by the `title` attribute, as well as the hostname (extracted from `url`), the `provider` and `description`. If you need to find results based on text which isn't included in these attributes, then you can add `tags` to a given item. + +```yaml + items: + - title: Plex + description: Media library + icon: favicon + url: https://plex.lab.local + tags: [ movies, videos, music ] + - title: FreshRSS + description: RSS Reader + icon: favicon + url: https://freshrss.lab.local + tags: [ news, updates, blogs ] + +``` + +In the above example, Plex will be visible when searching for 'movies', and FreshRSS with 'news' + + +## Custom Hotkeys +For apps that you use regularly, you can set a custom keybinding. Use the `hotkey` parameter on a certain item to specify a numeric key, between `0 - 9`. You can then launch that app, by just pressing that key, which is much quicker than searching for it, if it's an app you use frequently. + +```yaml +- title: Bookstack + icon: far fa-books + url: https://bookstack.lab.local/ + hotkey: 2 +- title: Git Tea + icon: fab fa-git + url: https://git.lab.local/ + target: workspace + hotkey: 3 +``` + +In the above example, pressing 2 will launch Bookstack. Or hitting 3 will open Git in the workspace view. + + +## Clearing Search +You can clear your search term at any time, by pressing Esc. +This can also be used to close an open pop-up modal.