New documentation

docs/docs/contributor-guide/_category_.yml

@@ -0,0 +1 @@
+label: Contributor Guide

docs/docs/contributor-guide/feature-requests.md

@@ -0,0 +1,9 @@
+---
+sidebar_position: 2
+---
+
+# Feature Requests
+
+If you have an idea for a new feature, just create a new issue. Please be as descriptive as possible, this will greatly enhance your chances of not simply being ignored.
+
+Approved requests will be marked with the <span class="badge badge--info">enhancement</span> label. However this does not give any information about how soon the feature will be implemented.

docs/docs/contributor-guide/i18n.md

@@ -0,0 +1,30 @@
+---
+sidebar_position: 3
+---
+
+# Translations and I18n
+
+Kvæsitso supports a number of different languages. You can contribute translations in your language using the [project's Weblate instance](https://i18n.mm20.de/engage/kvaesitso/).
+
+![Translation status](https://i18n.mm20.de/widgets/kvaesitso/-/multi-auto.svg)
+
+Sign up with your Github account and start translating. If your language does not exist yet, you can create it.
+
+There are two components: i18n and units:
+
+- `i18n` is the main component that contains most of the strings that are used within the app.
+
+- `units` is an extra component that contains all the strings that are used by the unit converter.
+  Each unit has a `unit_[name]` and a `unit_[name]_symbol` resource. `unit_[name]_symbol` is the
+  symbol that is used in the search query. For SI units, this should typically be the SI symbol (m, s, kg and so on),
+  but other, non-SI units may need their symbols to be translated (for example, nautical miles or horse powers).
+  :::caution
+  For technical reasons, these symbols may not contain spaces.
+  :::
+  `unit_[name]` is the full name of the unit that is used in the unit converter results. It's a plural resource, for different quantities of that unit.
+
+## Icons and other resources
+
+There are currently no icons that would require localization but in case there were you could simply create a new pull request including the localized resources.
+
+`defaults.xml` contains (non-string) factory settings for different regions. At the moment this is only used to enable imperial units for US users.

docs/docs/contributor-guide/index.md

@@ -0,0 +1,7 @@
+---
+sidebar_position: 0
+---
+
+# Get Involved
+
+You want to get involved and support the development? Whether you are a developer or not – this guide is what you are looking for.

docs/docs/contributor-guide/pull-requests.md

@@ -0,0 +1,21 @@
+---
+sidebar_position: 4
+---
+
+# Pull Requests
+
+Pull requests are always welcome.
+
+## Bug fixes
+
+If you found a bug and wrote a fix for it, just create a pull request.
+
+## New features
+
+For smaller enhancements, just create a pull request.
+
+If you plan to implement any bigger new features, please create an new issue first so we can discuss if and how this feature can be implemented. If you want to work on implementing a feature from an existing issue, please leave a note there to avoid duplicate work.
+
+## License
+
+By submitting any code, you agree to make that code available under the [GNU General Public License v3.0 (and any later version)](https://www.gnu.org/licenses/gpl-3.0.html.en), and that you have the necessary rights to do so. You cannot revoke this later. However, your copyright on your own code remains unaffected by this, you can still license your own code to other parties (under the same or a different license).

docs/docs/contributor-guide/report-bugs.md

@@ -0,0 +1,24 @@
+---
+sidebar_position: 0
+---
+
+# Report Bugs
+
+The easiest way to get involved is to report bugs on the [issue tracker](https://github.com/MM2-0/Kvaesitso/issues). Before you open a new issue, please make sure you have searched for existing issues to avoid duplications and that you are running the latest release version of the launcher.
+
+Please include all relevant information such as:
+
+- The **device** you are using
+- The **Android version**
+- **Steps to reproduce**
+- Relevant settings if they seem to be relevant to the issue
+
+## Crash reports
+
+When the launcher crashes, a crash report is automatically generated. You can find these crash reports at Settings > Debug > Crash Reporter.
+
+Use the bug icon in the top right corner to open an new issue with that report. Make sure to fill in additional information before submitting, such as steps to reproduce (if possible) or what you were trying to do when the launcher crashed.
+
+## Logs
+
+Logs can be exported at Settings > Debug > Export logs. Most of the time it is not necessary to submit logs unless your asked to do so.

docs/docs/contributor-guide/sponsor.md

@@ -0,0 +1,7 @@
+---
+sidebar_position: 1000
+---
+
+# Sponsor
+
+If you like my work and you want to support the project financially, you can sponsor me on [GitHub sponsors](https://github.com/sponsors/MM2-0).

docs/docs/developer-guide/_category_.yml

@@ -0,0 +1 @@
+label: Developer Guide

docs/docs/developer-guide/external-apis/_category_.yml

@@ -0,0 +1,2 @@
+label: External APIs
+position: 2

docs/docs/developer-guide/external-apis/exchange-rates.md

@@ -0,0 +1,9 @@
+# Currency Exchange Rates
+
+Currency exchange rates are fetched from the following API endpoint:
+
+```
+https://www.ecb.europa.eu/stats/eurofxref/eurofxref-daily.xml
+```
+
+This endpoint does not require any authentication, thus no configuration is required in order to enable the currency conversion feature in the unit converter.

docs/docs/developer-guide/external-apis/google.md

@@ -0,0 +1,24 @@
+# Google Cloud Services
+
+Google Cloud Services are used for Google Drive search. To enable Google Drive integration in your builds, follow these steps:
+
+1. Go to the [Google Cloud Console](https://console.cloud.google.com)
+1. Create a new project.
+1. Enable the Drive API:
+   1. Go to APIs & Services > Library and search for the Google Drive API.
+   1. Enable this API for your project.
+1. Setup your OAuth consent screen
+   1. Go to APIs & Services > OAuth consent screen
+   1. On the Oauth consent screen page, fill out all the required fields
+   1. On the Scopes page, click add or remove scopes and add the following scopes: `userinfo.profile` and `drive.metadata.readonly`
+1. Create a new Oauth 2.0 client (you need to do this twice, for debug builds and for release builds)
+   1. Go to APIs & Services > Credentials
+   1. Click on Create Credentials > OAuth client ID
+   1. Choose application type Android
+   1. Enter the package name (`de.mm20.launcher2.debug` for debug builds or `de.mm20.launcher2.release` for release builds)
+   1. Enter the SHA-1 certificate fingerprint of your APK signing key
+   1. Click on create
+1. Download the client config file (repeat this step for both the debug and the release client)
+   1. On the APIs & Services > Credentials page, find your OAuth client in the list under OAuth 2.0 Client IDs.
+   1. Click on the download icon to download a `client_config.json`
+   1. Place this file under `g-services/src/debug/res/raw/g_services.json` or `g-services/src/release/res/raw/g_services.json`

docs/docs/developer-guide/external-apis/index.md

@@ -0,0 +1,7 @@
+# External APIs
+
+Kvæsitso integrates with a number of external APIs. Most of them require some sort of authentication, like an API key. These API keys are not part of the GitHub repository. If you want to build Kvæsitso from source with all features enabled, follow the steps in this chapter.
+
+:::info
+Kvæsitso is still buildable even without these steps, but some features will be disabled in the resulting APK. If all you need is a debug build for testing purposes, you can probably skip this chapter.
+:::

docs/docs/developer-guide/external-apis/microsoft.md

@@ -0,0 +1,30 @@
+# Microsoft Graph Services
+
+Microsoft Graph Services are used for OneDrive search. To enable OneDrive integration in your builds, follow these steps:
+
+1. Go to the [Microsoft Azure Portal](https://portal.azure.com)
+1. Create a new project.
+   1. Search for App Registrations
+   1. Add a new registration
+      1. Supported account types: Accounts in any organizational directory and personal Microsoft accounts
+1. Add an authentication platform
+   1. Go to Authentication
+   1. Add a platform > Android
+   1. Enter the debug package name (de.mm20.launcher2.debug) and the signature hash of your debug key
+      1. You can use the following command to generate the signature hash:
+         `keytool -exportcert -alias androiddebugkey -keystore ~/.android/debug.keystore | openssl sha1 -binary | openssl base64`
+   1. Click Configure > Done
+   1. In the newly created Android section, click on Add URI
+   1. Add package name (de.mm20.launcher2.release) and signature hash of your release key
+1. Download the client details
+   1. In the debug client row, click on View
+   1. Copy the JSON below MSAL Configuration to `ms-services/src/debug/res/raw/msal_auth_config.json` (you'll need to create this file first)
+1. Repeat the previous step for the release config
+1. Add the required scopes
+   1. Go to API permissions
+   1. Add a permission
+   1. Select Microsoft Graph > Delegated permissions
+   1. Tick the following scopes:
+      - Files.Read.All
+      - User.Read
+   1. Click Add permissions

docs/docs/developer-guide/external-apis/weather.md

@@ -0,0 +1,51 @@
+# Weather Services
+
+1. Copy the `weather/src/main/res/values/config_example.xml` to `weather/src/main/res/values/config.xml`
+
+#### OpenWeatherMap
+
+OpenWeatherMap offers 1 000 000 free API calls per month. However forecasts are only available for
+the next 5 days and only every 3 hours. Also note that each weather update uses two API calls (
+current weather + forecast).
+
+1. Register at [OpenWeatherMap](https://openweathermap.org/)
+1. Navigate to your user profile > API keys
+1. Create a new API key
+1. Uncomment the resource `openweather_key` in config.xml and paste your key as value.
+
+#### HERE
+
+HERE offers 250 000 free API calls per month. Each weather update uses one call.
+
+1. Sign up at the [HERE developer portal](https://developer.here.com/)
+1. Create a new project.
+1. Go to project details and under JavaScript, create a new API key.
+1. Uncomment the resource `here_key` in config.xml and paste your key as value.
+
+#### Meteorologisk institutt[^1]
+
+The Norwegian Meteorological Institute offers a free weather API. It has a rate limit of 20
+requests/s. You do not need an API key, however they require an
+identification and contact data to be present in the User Agent header in each request. Read the exact rules in their
+[Terms of Service](https://api.met.no/doc/TermsOfService).
+
+1. Uncomment `metno_contact` in config.xml. Fill in your contact data (an email address or a website
+   where your contact data can be found). This will be sent in the User Agent header, which will be
+   composed like
+   this:
+   ```
+    User-Agent: "{app package name}/signature:{app siganture hash} {@string/metno_contact}"
+   ```
+
+#### Bright Sky / Deutscher Wetterdienst[^1]
+
+Bright Sky is an API that converts data published by the Deutscher Wetterdienst to an easier
+to work with JSON format. The API is free to use and requires no additional configuration, however
+it only provides weather data for locations in Germany.
+
+[^1]:
+    These weather providers do not provide any means of geocoding or location lookup. Instead, the
+    Android Geocoder API is used to lookup locations (in fixed location mode) and location names (in
+    auto location mode). While most devices ship a Geocoder as part of the Google Play service, some
+    might not have a Geocoder installed. In these cases, this provider might not work properly (no
+    support for fixed locations and lat/lon values will be displayed instead of location names).

docs/docs/developer-guide/external-apis/wikipedia.md

@@ -0,0 +1,3 @@
+# Wikipedia
+
+Kvæsitso uses the [Mediawiki API](https://www.mediawiki.org/wiki/API:Main_page) to load data from Wikipedia. No further configuration is required. The default Mediawiki installation URL is language-dependend and can be configured with `wikipedia_url` string resource in the `:i18n` module.

docs/docs/developer-guide/index.md

@@ -0,0 +1,7 @@
+---
+sidebar_position: 0
+---
+
+# Developer Guide
+
+You want to build Kvæsitso from source? Fix some bugs, develop new features or simply explore Kvæsitso's source code? Read this guide to learn how to setup the build environment and source code and to learn about the structure and organization of the source code.

docs/docs/developer-guide/libraries.md

@@ -0,0 +1,16 @@
+---
+sidebar_position: 4
+---
+
+# Libraries
+
+The following libraries are commonly used (libraries that are only used in single modules are not listed here as they are implementation details):
+
+- **KotlinX coroutines** for asynchronous operations
+- **Jetpack Compose and Accompanist** for all user interfaces _(TODO: Owncloud and Nextcloud signin are not ported to Compose yet)_
+- **AndroidX Room** to store launcher data in an Sqlite database
+- **AndroidX Protobuf Datastore** to store additional user preferences
+- **Koin** for dependency injection
+- **Coil** to load and transform images
+- **OkHttp and Retrofit** for HTTP requests
+- Several other **AndroidX** libraries (Work, Lifecycle, AppCompat, …)

docs/docs/developer-guide/modules.md

@@ -0,0 +1,47 @@
+---
+sidebar_position: 3
+---
+
+# Modules
+
+The source code consists of a number of Gradle submodules which all depend on each other in some way or another:
+
+- `:accounts`: Common APIs to manage different account types (Google, Microsoft, Nextcloud, …)
+- `:app`: The app module. Contains almost nothing except for the `Application` class (`de.mm20.launcher2.LauncherApplication`)
+- `:applications`: Installed apps and app search
+- `:appshortcuts`: Query apps shortcuts for apps and shortcut search
+- `:backup`: Backup and restore functionality
+- `:badges`: Provide different types of badges that are displayed on app icons
+- `:base`: Commonly used data classes, helper functions and utilities. Also icon resources (if they do not need localization).
+- `:calculator`: Implements the calculator
+- `:calendar`: query calendar events for the calendar widget and calendar search
+- `:compat`: Compatibility helpers for old Android versions
+- `:contacts`: Contact search
+- `:crashreporter`: Crash reporter; based on https://github.com/MindorksOpenSource/CrashReporter
+- `:currencies`: APIs to fetch currency conversion rates, used by `:unitconverter`
+- `:customattrs`: common (low-level) APIs to store per-app customizations (custom labels, custom icons, tags)
+- `:database`: the launcher database, uses AndroidX Room
+- `:favorites`: Handles pinned, frequently used and hidden items and serialization / deserialization of items. Depends on most of the search modules (`:apps`, `:calendar`, `:contacts`, etc.)
+- `:files`: File search (local and cloud)
+- `:g-services`: Google APIs and Google sign-in; used by `:accounts` and `:files`
+- `:i18n`: All resources that require localization. Mainly strings but can also be used for icon resources if they need localization.
+- `:icons`: Used to retrieve icons for items. Handles icon packs, themed icons and also custom icons (on a higher level)
+- `:ktx`: Commonly used Kotlin extension functions
+- `:material-color-utilities`: This library: https://github.com/material-foundation/material-color-utilities (not available as Gradle package yet)
+- `:ms-services`: Microsoft APIs and Microsoft sign-in; used by `:accounts` and `:files`
+- `:music`: Manage media sessions and extract metadata
+- `:nextcloud`: Nextcloud APIs and Nextcloud sign-in; used by `:accounts` and `:files`
+- `:notifications`: APIs to read notifications. Contains the app's `NotificationListenerService`
+- `:owncloud`: Owncloud APIs and Owncloud sign-in; used by `:accounts` and `:files`
+- `:permissions`: Request and observe permission status for this app
+- `:preferences`: Store user preferences; uses AndroidX Datastore
+- `:search`: Base classes for search items and search item serialization. Also websearches. Does not contain the actual search which is split across several modules (`:applications`, `:calendar`, `:contacts`, `:files` and so on)
+- `:ui`: Contains almost the entire user interface (except for account sign-in UIs). Uses Jetpack Compose.
+- `:unitconverter`: Unit and currency converter
+- `:weather`: APIs to fetch weather data
+- `:webdav`: common APIs for WebDAV search, used by `:nextcloud` and `:owncloud`
+- `:websites`: Website search
+- `:widgets`: Manages configuration of widgets (which widgets and which order). Actual widget implementation (for built-in widgets) is in `:ui`.
+- `:wikipedia`: APIs to search Wikipedia
+
+Most of the modules have a `Module.kt` file in their root which contains Koin definitions to make the APIs accessable for other modules.

docs/docs/developer-guide/setup.md

@@ -0,0 +1,11 @@
+---
+sidebar_position: 1
+---
+
+# Setup
+
+## Setup the build environment
+
+- Download and install the latest canary version of Android Studio and the Android SDK: https://developer.android.com/studio/preview.
+- Clone the Git repository: `git clone https://github.com/MM2-0/Kvaesitso`
+- Open the project in Android Studio

docs/docs/user-guide/_category_.yml

@@ -0,0 +1,2 @@
+label: User Guide
+position: 0

docs/docs/user-guide/concepts/_category_.yml

@@ -0,0 +1,4 @@
+label: Concepts
+link:
+  type: generated-index
+  title: Concepts

docs/docs/user-guide/concepts/favorites.md

@@ -0,0 +1,39 @@
+# Favorites
+
+Favorites allow even faster access to selected items.
+
+Favorites consist of:
+
+- Manually sorted pinned items
+- Automatically sorted pinned items (sorted by how frequently you use them)
+- Frequently used items (if there is room)
+
+## Pin apps to favorites
+
+You can pin any app and any search result to favorites by long pressing it and selecting the star icon.
+Some apps allow the creation of home screen shortcuts. These shortcuts will also appear in the favorites section.
+
+## Access favorites
+
+Favorites can appear in three different places:
+
+- Above (or below) the app grid (enabled by default, can be disabled at Settings > Search > Favorites)
+- In the [favorites widget](/docs/user-guide/widgets/favorites-widget) (not enabled by default)
+- In the [clock widget](/docs/user-guide/widgets/clock#dynamic-components) (not enabled by default)
+
+:::info
+If you have the calendar widget enabled, pinned calendar events will not appear in any of the above places. Instead, they will appear in the calendar widget.
+:::
+
+## Customization
+
+Favorites can be customized at Settings > Search > Favorites > Edit favorites. The same panel can be opened by clicking the pen icon in the favorites panel.
+
+In this panel, you can
+
+- rearrange items / change their order (note that reordering items in the “automatically sorted” section will have no effect, you need to move them to the “manually sorted” section first)
+- add app shortcuts
+- manage [tags](tags)
+- configure frequently used items
+  - how many rows of frequently used items should be shown (including the last row of pinned items which will be filled first)
+  - disable non-pinned frequently used altogether

docs/docs/user-guide/concepts/tags.md

@@ -0,0 +1,20 @@
+# Tags
+
+Tags are a way to organize apps and other items.
+
+- Tags are used as keywords in the search; you can use tags to assign additional keywords.
+- Tags can be added to the [favorites](favorites) section, this allows faster access to all items that have that tag assigned.
+
+## Create and assign tags
+
+There are two ways to create tags and assign them to items:
+
+1. Long-press any search result and select “Customize” (or the pen icon) in the menu.
+2. Type a comma-separated list of tags into the tags input field.
+
+OR
+
+1. Open the [edit favorites sheet](/docs/user-guide/concepts/favorites#customization).
+2. In the tags section, press the plus icon.
+3. Select an existing tag or create a new one.
+4. Assign items to tags by dragging them onto the tags.

docs/docs/user-guide/customization/_category_.yml

@@ -0,0 +1,4 @@
+label: Customization
+link:
+  type: generated-index
+  title: Customization

docs/docs/user-guide/customization/color-schemes.md

@@ -0,0 +1,52 @@
+# Color Schemes
+
+## Default
+
+The default color scheme is different depending on the Android version:
+
+- On **Android 12+**: the default color scheme is the color scheme provided by the system, usually based on the wallpaper (“Material You”).
+- On **Android 8.1 - Android 11**: the default color scheme is based on the current wallpaper (“Material You Compat”)
+- On **Android 8.0**: the default color scheme is a blueish fallback theme because the APIs to extract wallpaper colors do not exist on this version. This is also used on Android 8.1 - Android 11 if the wallpaper color extraction fails for some reason.
+
+## Black and White
+
+A high contrast theme using only black and white.
+
+## Custom
+
+Customize the launchers color scheme to your likings. There is a simple mode and an advanced mode. You can toggle between them using the overflow menu in the top right corner.
+
+Since Kvæsitso uses Material Design 3, all colors are based on the [Material 3 color system](https://m3.material.io/styles/color/the-color-system/key-colors-tones).
+
+### Simple mode
+
+In simple mode, you specify six base colors from which a light and a dark color scheme will be generated.
+
+:::info
+You can also specify only one color, the primary color, and generate the rest using the “Generate from primary color” option in the overflow menu. This will generate a whole palette from one color, using the same method that wallpaper-based color schemes use to generate the entire color scheme from only one base color.
+:::
+
+These are the six base colors. Refer to the [Material 3 documentation](https://m3.material.io/styles/color/the-color-system/key-colors-tones) for more information.
+
+- **Primary**: mainly used for interactive key components, like buttons, switches and input fields. Also used for [themed icons](./themed-icons) and as elevation overlay color (cards, dialogs and other elevated surfaces will have a slight tint of this color)
+- **Secondary**: used for less prominent components, such as chips, badges and some (non interactive) headlines
+- **Tertiary**: not used anywhere at the moment, reserved for future use
+- **Neutral**: used as background for cards, dialogs, settings, and other surfaces. Also used for text and some icons.
+- **Neutral variant**: used for banners, switch and slider tracks and for outlines.
+- **Error**: used to indicate errors, like invalid inputs in text fields.
+
+Several color tones (brightness levels) are generated from each color. These tonal values are fixed so that the brightness of any given color doesn't actually matter that much. Surfaces and texts will always have high contrast to each other even though both are generated from the same base color.
+
+### Advanced mode
+
+In advanced mode, you have full control over every color that might or might not be used anywhere in the launcher UI. In this mode, you can customize light and dark mode color scheme seperately. Colors are used as is, without any further processing.
+
+:::info
+Since there are quite a lot of different colors and color shades, it can be tedious to customize every single color. The recommended approach is to set the base colors in simple mode and then switch to advanced mode to tweak only individual colors.
+:::
+
+:::caution
+If you switch back from advanced to simple mode at a later point, you will lose your customizations.
+:::
+
+Please refer to the [Material Design 3 documentation](https://m3.material.io/styles/color/the-color-system/color-roles) to get an understanding how each of these colors is used.

docs/docs/user-guide/customization/themed-icons.md

@@ -0,0 +1,24 @@
+# Themed Icons
+
+Themed Icons is a feature that adapt app icons to the launcher's color scheme:
+
+![Themed icons off](/img/themed-icons-off.png)
+![Themed icons on](/img/themed-icons-on.png)
+
+Themed icons can be enabled in Settings > Appearance > Themed Icons.
+
+## Themed icons on pre Android 13
+
+It was first introduced by Google on Android 12. Unfortunately, Google did not provide an official API for third party app developers to support themed icons in their apps until Android 13. Instead they hardcoded all the themed icons into the Pixel Launcher. This is the reason why only Google icons could be themed on Android 12 Pixel devices.
+
+In order to not violate any trademarks, Kvæsitso does not ship any third party icons. However, it can extract these themed icons from the Pixel launcher if it is installed on the device. The issue remains, that only Google icons are supported. Fortunately, the Lawnchair developers started a community effort to bring themed icon support to all apps for their launcher: [Lawnicons](https://github.com/LawnchairLauncher/lawnicons).
+
+Kvæsitso supports themed icons through Lawnicons natively. All you need to do is to install the latest Lawnicons APK and enable Themed icons in the launcher settings (Settings > Appearance > Themed Icons). Kvæsitso will detect that Lawnicons is installed and extract the icons automatically.
+
+## Themed icons on Android 13+
+
+In Android 13, a [new API](https://developer.android.com/develop/ui/views/launch/icon_design_adaptive#add_your_adaptive_icon_to_your_app) has been added for app developers to support themed icons in their app. It remains to be seen, how well developers adopt this API so you might still want to install Lawnicons (as described [here](#themed-icons-on-pre-android-13)).
+
+## Auto generated themed icons
+
+There is also an option to force themed icons to all icons (Settings > Appearance > Force themed icons). This scales the foreground layer of an icon down, adds a monochrome color filter and replaces the background with a solid color. Using this option is generally not recommended because icons may become illegible, but it might work well in combination with certain monochrome icon packs. You can also apply auto generated themed icons on a per-app basis by using the customize menu.

docs/docs/user-guide/index.md

@@ -0,0 +1,16 @@
+---
+sidebar_position: 0
+---
+
+# Get Started
+
+Kvæsitso is available for Android devices running Android 8.0 or higher.
+
+## Installation
+
+The latest APK can be downloaded from [GitHub](https://github.com/MM2-0/Kvaesitso/releases).
+
+To make sure that you get always notified about the latest updates, it's recommended that you add my F-Droid repo:
+https://github.com/MM2-0/fdroid
+
+You can also download it from the [IzzyOnDroid](https://apt.izzysoft.de/fdroid/index/apk/de.mm20.launcher2.release) F-Droid repo but keep in mind that updates are usually delayed for a day when using that repo.

docs/docs/user-guide/search/_category_.yml

@@ -0,0 +1,4 @@
+label: Search
+link:
+  type: generated-index
+  title: Search

docs/docs/user-guide/search/calculator.md

@@ -0,0 +1,14 @@
+# Calculator
+
+The search field can be used as a calculator. Just type any mathematical expression into the search bar and you'll get the result.
+
+Internally, the calculator is backed by an older version (the last version that is available under a FOSS license) of mXparser. Refer to the [mXparser documentation](https://mathparser.org/mxparser-tutorial/) for a full list of built-in capabilities.
+
+## Conversion between DEC, OCT, HEX and BIN
+
+The calculator can convert **positive integers** between their decimal, hexadecimal, octal and binary representation.
+
+- To convert a number from **decimal** to **hexadecimal**, **octal** or **binary**, simply type the number into the search bar.
+- To convert a number from **hexadecimal** to **decimal**, prefix the number with `0x`: `0xff`
+- To convert a number from **octal** to **decimal**, prefix the number with `0`: `077`
+- To convert a number from **binary** to **decimal**, prefix the number with `0b`: `0b11`

docs/docs/user-guide/search/unit-converter.md

@@ -0,0 +1,33 @@
+# Unit Converter
+
+The unit converter is a tool to convert units.
+
+## Usage
+
+Type number followed by a space and a unit symbol into the search bar.
+Examples:
+
+- `1 m`
+- `3600 s`
+- `12.5 kg`
+
+You can also specify a target unit like this:
+
+- `14 ft >> m`
+
+If you don't specify a target unit, all supported units in the dimension of the input unit are returned.
+
+### Unit symbols
+
+Unit symbols can differ between different languages, therefore an exhaustive list wouldn't be very useful here. You can find the unit symbol for each unit in parentheses in the unit converter result list.
+
+Units of the following dimensions are supported:
+
+- Units of time: `ms`, `s`, `min`, `h`, …
+- Units of length: `m`, `km`, `in`, `ft`, …
+- Units of mass: `kg`, `t`, `oz.`, …
+- Units of area: `m²`, `ha`, `sqyd`, …
+- Units of data: `bit`, `B`, `kB`, `MiB`, …
+- Units of speed: `km/h`, `mph`, `m/s`, …
+- Units of temperature: `°C`, `°F`, `K`
+- Currencies (if currency converter is enabled in unit converter settings): `EUR`, `USD`, `GBP`, …

docs/docs/user-guide/search/websearches.md

@@ -0,0 +1,41 @@
+# Websearch shortcuts
+
+Websearch shortcuts allow to quickly search for the entered term with a web search engine. Websearch shortcuts appear in the search bar when you type anything.
+
+## Customize websearches
+
+Websearches can be customized at Settings > Search > Websearches. To create a new shortcut, click the plus button in the bottom right corner.
+
+There are two ways of creating a websearch shortcut:
+
+### Automatically
+
+Some websearches can be imported automatically (if they support the [OpenSearch description format](https://developer.mozilla.org/en-US/docs/Web/OpenSearch)
+
+- In the create websearch dialog, click the download icon in the top left-corner
+- Enter the base URL of the website you are trying to import (for example: `github.com`)
+- Click the arrow next to the text field
+- If the website is supported, all the required fields will be filled automatically.
+- If the website is not supported, you will need to fill in the required data [manually](#manually).
+
+### Manually
+
+- **Color** the color that is used for the icon. The leftmost option adapts the color to the launcher's color scheme. You can also select a custom icon.
+- **Name** is the name that is shown in the search bar interface, you can use anything you like.
+- **URL** is a URL with a placeholder. The placeholder is later replaced with the actual search term. The placeholder is `${1}` and must be present somewhere in the URL. To find out what the correct URL is, proceed as follows:
+
+  - Open the website you wish to add in a browser
+  - Use the website's search field to search for anything
+  - Look at the browser's URL bar. Find the search term you just searched for in the URL
+    :::info
+    Spaces and special characters might be encoded. Don't worry about it, the launcher will handle the encoding for you.
+
+    If you can't the search term anywhere, try to disable Javascript and try again. If that still doesn't work, then that website cannot be used.
+    :::
+
+  - Replace the search term in the URL with `${1}`. Copy the URL and paste it into the URL field.
+
+- **Advanced > Query encoding**: You probably don't need to change this. If you later discover that search queries are encoded incorrectly, you can try to change this setting.
+  - **[Percent encoding](https://developer.mozilla.org/en-US/docs/Glossary/percent-encoding)**: encode according to the standard for URL encoding (RFC 3986). Most notably, this encodes spaces as `%20`.
+  - **application/x-www-form-urlencode**: encode according to the [application/x-www-form-urlencode](https://url.spec.whatwg.org/#application/x-www-form-urlencoded) spec. Most notably, this encodes spaces as `+`. There is no real reason to use this encoding since percent encoding should cover all cases where this encoding was appropriate.
+  - **None**: do not encode the query at all

docs/docs/user-guide/widgets/_category_.yml

@@ -0,0 +1,4 @@
+label: Widgets
+link:
+  type: generated-index
+  title: Widgets

docs/docs/user-guide/widgets/calendar-widget.md

@@ -0,0 +1,5 @@
+# Calendar Widget
+
+Display calendar events and appointments for the next seven days.
+
+Calendar apps need to use the Android calendar provider APIs to store their calendar data in order to make them accessible for this widget. Some calendar apps (notably Proton calendar) do not do this and therefore do not work with this widget.

docs/docs/user-guide/widgets/clock.md

@@ -0,0 +1,35 @@
+# Clock Widget
+
+The clock widget is always the top-most widget in the widget list. It can be customized in several ways at Settings > Widgets > Clock.
+
+## Layout
+
+The clock widget has two layouts:
+
+- **Default**: a vertical layout with a large clock and dynamic components below it
+- **Compact**: a horizontal layout that shows clock and dynamic components in a single row
+
+## Style
+
+There are five different clock styles:
+
+- Fat digital clock
+- Boring digital clock
+- [Binary clock](https://en.wikipedia.org/wiki/Binary_clock#Binary-coded_sexagesimal_clocks)
+- Analog clock
+- Empty clock; in case you want to disable the clock altogether
+
+## Dynamic components
+
+The clock widget can show one dynamic component at a time. Clock widget components can be enabled or disabled in settings.
+
+Base components, you can only enable one of them at a time:
+
+- **Date**: show the current date
+- **Favorites**: show the first row of favorites. The number of shown items depends on the grid columns setting (but in compact layout, it's 2 items less than the grid columns setting)
+
+Additionally, these conditional components are available:
+
+- **Media**: show media controls, only when there are active media sessions
+- **Alarm**: show the remaining time to the next alarm, only if there is an alarm scheduled to ring within the next 15 minutes
+- **Battery**: shows the current battery level and remaining charging time, only if battery is charging or battery level is less than 15%

docs/docs/user-guide/widgets/favorites-widget.md

@@ -0,0 +1,3 @@
+# Favorites Widget
+
+A widget that displays your [favorites](/docs/user-guide/concepts/favorites). This mirrors the favorites grid that is shown above the app grid but brings them to the widget page. This widget is not enabled by default.

docs/docs/user-guide/widgets/music-widget.md

@@ -0,0 +1,13 @@
+# Music Widget
+
+The music widget is one of the launcher's built-in widgets. It can be used to control media sessions on the device. The general usage is pretty self-explanatory: control the playback with the skip previous, skip next and toggle pause buttons. Tap on the album cover to open the current media player app. Long-press the album cover to open a player chooser.
+
+However there are a few things you might want to know:
+
+## My media playback doesn't show up!
+
+Per default, only media sessions from "music apps" are shown in the music widget. An app qualifies as "music app" if it has an activity that has either the `android.intent.action.MUSIC_PLAYER` action or the `android.intent.action.MAIN` action and the `android.intent.category.APP_MUSIC` category. Some media apps don't declare these in their manifests so the launcher won't recognize them as music apps. You can disable this filter in Settings > Widgets > Music > Restrict to music apps. With this setting disabled, the music widget will show media sessions from all apps, including non-music apps like browsers, video player apps and video streaming apps.
+
+## Why do I need to grant access to my notifications just to control some stupid media session?
+
+That's a very good question. I don't know. Ask Google, why they make so [nonsensical decisions](https://www.reddit.com/r/mAndroidDev/comments/gn6ckb/man_im_so_happy_no_malicious_app_can_get_access/). The only way for third party apps to control media sessions is to read notifications and extract the media sessions from there. Sadly, the more privacy-friendly alternative is restricted to system apps only, ["due to privacy of media consumption"](https://developer.android.com/reference/android/Manifest.permission#MEDIA_CONTENT_CONTROL). Yep, that makes sense. Thank you, Google.

docs/docs/user-guide/widgets/weather-widget.md

@@ -0,0 +1,19 @@
+# Weather Widget
+
+A widget that displays current and future weather data.
+
+## Configuration
+
+The weather widget can be configured at Settings > Widgets > Weather
+
+### Providers
+
+The service that provides the weather data. Weather data might differ in quality depending on your location so pick whataver is working best for you.
+
+### Location
+
+You can either use your current location automatically (you need to grant location permission for this) or set a fixed location manually.
+
+#### Cannot find any locations!
+
+Some weather providers rely on the Android Geocoding API to convert location names to coordinates and vice verca. This API is usually backed by the Google Play Services and Google Maps. It might not be available if you use a degoogled Android distribution. In this case, you can try one of the providers that ship their own geocoders (OpenWeatherMap or HERE), or you can specify the coordinates manually using the following format: `<lat> <lon> <name>`. For example: `-90 0 South pole`