Add menu grouping in sidebar, prepare for better UI doc integration (#2198)

* Add menu grouping in sidebar, prepare for better UI doc integration

Signed-off-by: Stefan Höhn <mail@stefanhoehn.com>

* review comments

Signed-off-by: Stefan Höhn <mail@stefanhoehn.com>

* Markdown fixes

Signed-off-by: Stefan Höhn <mail@stefanhoehn.com>

---------

Signed-off-by: Stefan Höhn <mail@stefanhoehn.com>

.vuepress/docs-sidebar.js

@@ -7,29 +7,41 @@ module.exports = [
     ]
   },
   {
-    title: 'Getting Started',
-    collapsable: false,
-    children: [
-      ['tutorial/', 'Tutorial Overview'],
-      'tutorial/first_steps',
-      'tutorial/things_simple',
-      'tutorial/things_intermediate',
-      'tutorial/things_advanced',
-      'tutorial/model',
-      'tutorial/persistence',
-      'tutorial/pages_intro',
-      'tutorial/auto_overview',
-      'tutorial/item_widgets',
-      'tutorial/custom_widgets',
-      'tutorial/rules_introduction',
-      'tutorial/rules_overview',
-      'tutorial/rules_basic',
-      'tutorial/rules_blockly',
-      'tutorial/rules_advanced',
-      'tutorial/rules_scenes',
-      'tutorial/tips-and-tricks'
-    ]
-  },
+      title: 'Getting Started',
+      collapsable: false,
+      children: [
+        ['tutorial/', 'Tutorial Overview'],
+        'tutorial/first_steps',
+        { title: 'Adding Things',
+          children: [
+            'tutorial/things_simple',
+            'tutorial/things_intermediate',
+            'tutorial/things_advanced',
+          ]
+        },
+        'tutorial/model',
+        'tutorial/persistence',
+        { title: 'Pages',
+          children: [
+            'tutorial/pages_intro',
+            'tutorial/auto_overview',
+            'tutorial/item_widgets',
+            'tutorial/custom_widgets'
+          ]
+        },
+        { title: 'Rules',
+          children: [
+            'tutorial/rules_introduction',
+            'tutorial/rules_overview',
+            'tutorial/rules_basic',
+            'tutorial/rules_blockly',
+            'tutorial/rules_advanced',
+            'tutorial/rules_scenes',
+          ]
+        },
+        'tutorial/tips-and-tricks'
+      ]
+    },
   {
     title: 'Installation Guide',
     collapsable: false,
@@ -63,18 +75,38 @@ module.exports = [
     title: 'Configuration Guide',
     collapsable: false,
     children: [
-      ['configuration/', 'Configuration Overview'],
-      'configuration/editors',
-      'configuration/addons',
-      'configuration/things',
-      'configuration/items',
-      'configuration/persistence',
-      'configuration/rules-dsl',
-      ['configuration/blockly/', 'Blockly Rules'],
-      'configuration/transformations',
+      { title: 'Configuration Overview',
+        path: '/docs/configuration/',
+        children: [
+          'configuration/editors',
+          'configuration/addons',
+          'configuration/things',
+          'configuration/items',
+          'configuration/persistence',
+          'configuration/rules-dsl',
+          'configuration/transformations',
+          { title: 'Blockly Rules',
+            path: '/docs/configuration/blockly/',
+            children: [
+              ['configuration/blockly/rules-blockly-items-things', 'Items & Things'],
+              ['configuration/blockly/rules-blockly-timers-and-delays', 'Timers & Delays'],
+              ['configuration/blockly/rules-blockly-voice-and-multimedia', 'Voice & Multimedia'],
+              ['configuration/blockly/rules-blockly-uom', 'Units of Measurements'],
+              ['configuration/blockly/rules-blockly-date-handling', 'Date Handling'],
+              ['configuration/blockly/rules-blockly-ephemeris', 'Ephemeris'],
+              ['configuration/blockly/rules-blockly-notifications', 'Notifications'],
+              ['configuration/blockly/rules-blockly-persistence', 'Persistence'],
+              ['configuration/blockly/rules-blockly-value-storage', 'Value Storage'],
+              ['configuration/blockly/rules-blockly-run-and-process', 'Run & Process'],
+              ['configuration/blockly/rules-blockly-logging', 'Logging'],
+              ['configuration/blockly/rules-blockly-standard-ext', 'Standard Extensions'],
+            ]
+          },
+        ]
+      },
       'configuration/actions',
-      'configuration/iconsets/classic/',
       'configuration/jsr223',
+      'configuration/iconsets/classic/',
       'configuration/services',
       'configuration/multimedia',
       ['configuration/restdocs', 'REST API'],
@@ -83,34 +115,42 @@ module.exports = [
       ['configuration/migration/', 'Migration from openHAB 2']
     ]
   },
-    {
-      title: 'Settings',
-      collapsable: false,
-      children: [
-        ['settings/', 'Settings Overview'],
-        'settings/aboutpage',
-        'settings/configuration',
-        ['settings/automations', 'Automation'],
-        'settings/addons',
-        'settings/services_system',
-        'settings/services_other',
-      ]
-    },
+  {
+    title: 'Main UI',
+    collapsable: false,
+    children: [
+      ['ui/mainui', 'Main UI'],
+      { title: 'Settings',
+        path: '/docs/settings/',
+        children: [
+          'settings/configuration',
+          ['settings/automations', 'Automation'],
+          ['settings/system_settings', 'System'],
+          ['settings/addons', 'Add-ons'],
+        ]
+      },
+      ['ui/addons-store', 'Add-on Store'],
+      ['ui/developer-tools', 'Developer Tools'],
+      ['ui/aboutpage', 'Help & About'],
+    ]
+  },
   {
     title: 'User Interface Guide',
     collapsable: false,
     children: [
       'ui/',
       'ui/sitemaps',
-      'ui/layout-pages',
-      'ui/map-pages',
-      'ui/floorplan-pages',
-      'ui/tabbed-pages',
-      'ui/chart-pages',
-      ['ui/building-pages', 'Building Pages'],
-      'ui/personal-widgets',
-      'ui/widget-expressions-variables',
-      'ui/css-pages-widgets',
+      { title: 'Pages',
+        children: [
+          'ui/layout-pages',
+          'ui/map-pages',
+          'ui/floorplan-pages',
+          'ui/tabbed-pages',
+          'ui/chart-pages',
+          ['ui/building-pages', 'Building Pages'],
+        ]
+      },
+      ['ui/personal-widgets', 'Creating Personal Widgets'],
       ['ui/components/', 'Component Reference'],
       'ui/habpanel/habpanel',
       ['apps/android', 'Android App'],
@@ -145,7 +185,7 @@ module.exports = [
   },
   {
     title: 'Developer Guide',
-    collapsable: false,
+    collapsable: true,
     children: [
       ['developer/', 'Overview & Introduction'],
       'developer/guidelines',
@@ -160,7 +200,7 @@ module.exports = [
   },
   {
     title: 'Developer Appendix',
-    collapsable: false,
+    collapsable: true,
     children: [
       'developer/buildsystem',
       'developer/osgi/osgi',

.vuepress/styles/index.styl

@@ -29,7 +29,7 @@
         // background-color white
         background-color rgba(98%, 98%, 99%, 0.96) !important
         box-shadow rgba(10%,10%,10%,25%) 0 0 5px
-    
+
     .nav-item a
         // font-family 'Open Sans', sans-serif
         font-weight 400
@@ -51,6 +51,12 @@
 .dropdown-wrapper .nav-dropdown .dropdown-item h4
     margin-bottom .2rem
 
+.sidebar-group.is-sub-group>.sidebar-heading:not(.clickable)
+    opacity 1 !important
+
+.arrow.right
+    border-left: 6px solid #333 !important
+
 .sidebar
     background-color #f7f7f7 !important
     // background linear-gradient(90deg, #fff0e0, #fff) !important

configuration/blockly/rules-blockly-uom.md

@@ -1,6 +1,6 @@
 ---
 layout: documentation
-title: Rules Blockly - Items & Things
+title: Rules Blockly - Units of Measurements
 ---
 <!-- markdownlint-disable MD036 -->
 

configuration/multimedia.md

@@ -11,12 +11,16 @@ The framework supports some base [functions](https://openhab.org/javadoc/latest/
 
 ### Actions
 
+You can set and get the volume in DSL rules by using these functions:
+
 - `setMasterVolume(float volume)` : Sets the volume of the host machine (volume in range 0-1)
 - `setMasterVolume(PercentType percent)` : Sets the volume of the host machine
 - `increaseMasterVolume(float percent)` : Increases the volume by the given percent
 - `decreaseMasterVolume(float percent)` : Decreases the volume by the given percent
 - `float getMasterVolume()` : Returns the current volume as a float between 0 and 1
 
+Please refer to the documentation of the [Automation add-ons](/addons/#automation) on how to use these actions from the respective language, e.g. JavaScript or JRuby.
+
 ## Audio Capture
 
 openHAB is able to capture audio.
@@ -55,8 +59,16 @@ The distribution comes with these options built-in:
 | `enhancedjavasound` | System Speaker (with mp3 support) | This uses the JRE sound drivers plus an additional 3rd party library, which adds support for mp3 files.                                                                                                                                                                                                                                                      |
 | `webaudio`          | Web Audio                         | Convenient, if sounds should not be played on the server, but on the client: This sink sends the audio stream through HTTP to web clients, which then cause it to be played back by the browser. Obviously, the browser needs to be opened and have a compatible openHAB UI running. Currently, this feature is supported by Main UI, Basic UI and HABPanel. |
 
+Please refer to the [Main UI docs]({{base}}/ui/mainui.html#web-audio-sink) for setting up web audio in Main UI.
+
 Additionally, certain bindings register their supported devices as audio sinks, e.g. Sonos speakers.
 
+### Default Audio Sink
+
+You can configure a default audio sink, which will be used if no audio sink is provided in audio and voice actions.
+
+You can define the default audio sink either by textual configuration in `$OPENHAB_CONF/services/runtime.cfg` or in the UI by visitting the **Settings** page and opening **System Settings** -> **Audio**.
+
 ### Console commands
 
 To check which audio sinks are available, you can use the console:
@@ -67,8 +79,6 @@ openhab> openhab:audio sinks
   Web Audio (webaudio)
 ```
 
-You can define the default audio sink either by textual configuration in `$OPENHAB_CONF/services/runtime.cfg` or in the UI in `Settings->Audio`.
-
 In order to play a sound, you can use the following commands on the console:
 
 ```text
@@ -97,6 +107,17 @@ Alternatively the [`playSound()`](https://www.openhab.org/javadoc/latest/org/ope
 - `playStream(String url)` : plays an audio stream from an url to the default sink (set url to `null` if streaming should be stopped)
 - `playStream(String sink, String url)` : plays an audio stream from an url to the given sink(s) (set url to `null` if streaming should be stopped)
 
+If no audio sink is provided, the default audio sink will be used.
+
+Please refer to the documentation of the [Automation add-ons](/addons/#automation) on how to use these actions from the respective language, e.g. JavaScript or JRuby.
+
+UI-based rules support audio actions as well.
+Just create or edit a rule, add a new action, select "Audio & Voice" and the UI will then guide you trough the setup:
+
+![Audio action setup in the UI](images/rule-play-audio.png)
+
+Visit the [Blockly docs]({{base}}/configuration/blockly/rules-blockly-voice-and-multimedia.html) to learn how to use audio actions from Blockly.
+
 #### Examples
 
 ```java
@@ -109,12 +130,18 @@ playStream("example.com")
 playStream("sonos:PLAY5:kitchen", "example.com")
 ```
 
+You will find more examples in the documentation of the [Automation add-ons](/addons/#automation) and the [Blockly docs]({{base}}/configuration/blockly/rules-blockly-voice-and-multimedia.html).
+
 ## Voice
 
 ### Text-to-Speech
 
 In order to use text-to-speech, you need to install at least one [TTS service](/addons/#voice).
 
+#### Default TTS Service & Voice
+
+You can define a default TTS service and a default voice to use either by textual configuration in `$OPENHAB_CONF/services/runtime.cfg` or in the UI by visitting the **Settings** page and opening **System Settings** -> **Voice**.
+
 #### Console Commands
 
 To check which Text-to-Speech services are available, you can use the console:
@@ -147,8 +174,6 @@ openhab> openhab:voice voices
   VoiceRSS - vietnamien (Vietnam) - default (voicerss:viVN)
 ```
 
-You can define a default TTS service and a default voice to use either by textual configuration in `$OPENHAB_CONF/services/runtime.cfg` or in the UI in `Settings->Voice`.
-
 In order to say a text, you can enter such a command on the console (The default voice and default audio sink will be used):
 
 ```text
@@ -169,6 +194,14 @@ Alternatively you can execute such commands within DSL rules by using the [`say(
 You can select a particular voice (second parameter) and a particular audio sink (third parameter).
 If no voice or no audio sink is provided, the default voice and default audio sink will be used.
 
+Please refer to the documentation of the [Automation add-ons](/addons/#automation) on how to use these actions from the respective language, e.g. JavaScript or JRuby.
+
+UI-based rules support voice actions as well.
+Just create or edit a rule, add a new action, select "Audio & Voice" and the UI will then guide you trough the setup.
+The presented dialog will look similar to the one shown [above](#actions-2).
+
+Visit the [Blockly docs]({{base}}/configuration/blockly/rules-blockly-voice-and-multimedia.html) to learn how to use voice actions from Blockly.
+
 ##### Examples
 
 ```java
@@ -180,6 +213,8 @@ say("Hello world!", "voicerss:enUS", "sonos:PLAY5:kitchen")
 say("Hello world!", "voicerss:enUS", "sonos:PLAY5:kitchen", new PercentType(25))
 ```
 
+You will find more examples in the documentation of the [Automation add-ons](/addons/#automation) and the [Blockly docs]({{base}}/configuration/blockly/rules-blockly-voice-and-multimedia.html).
+
 ### Speech-to-Text
 
 In order to use Speech-to-Text, you need to install at least one [STT service](/addons/#voice).

configuration/rules-dsl.md

@@ -1,6 +1,6 @@
 ---
 layout: documentation
-title: Rules
+title: Textual Rules
 ---
 
 # Textual Rules

introduction.md

@@ -163,7 +163,7 @@ Once you have got a first overview, it is time to practice.
 Here a short list of the steps that you will need to consider to get openHAB up and running as your home automation system:
 
 1. Install openHAB
-1. If you already own a smart device, search the addons for the brand or technology used by that device (or simply browse the list of [add-ons](/addons/) for any technologies or services you may recognize)
+1. If you already own a smart device, search the add-ons for the brand or technology used by that device (or simply browse the list of [add-ons](/addons/) for any technologies or services you may recognize)
 1. Install a binding (in openHAB)
 1. Define a “thing”
 1. Add a “channel” to the “thing” if not created by the binding

settings/addons.md

@@ -3,113 +3,13 @@ layout: documentation
 title:  Add-ons
 ---
 
-# Settings - Add-ons
+# Add-ons
 
-This is the section that allows openHAB to be extended via add-ons.
-There is a huge variety of extension possibilities that openHAB provides:
+This section lists the installed add-ons and provides direct access to the settings that are directly related to that add-on.
 
-- **Bindings** are used to connect and control hardware and online services. This section provides
-  - **openHAB Distribution**: official bindings maintained by the openHAB project and
-  - **Community Marketplace**: bindings independently released by the community.
-- **Automation** contains scripting languages, templates and module types
-  - **languages** like Groovy, JRuby, Jython, Java Rules (JRule), JScripting (Nashorn) or
-  - **technologies** like PID Controller, PWM (pulse width modulation)
-  - **Rule Templates** shared by the community to bootstrap your automation
-  - **[Blockly](/docs/configuration/blockly/)** libraries that contain custom blocks written by the community.
-- **UI / User Interface**: Widgets for the Main UI
-- **Other...**: System Integrations, Persistence Services, Transformation Services and Voice & Speech
+This section is particular important as it allows the setting of the log-level of a particular addon:
 
-Clicking on the individual tile reveals more information about the add-on:
+![log-level.png](images/log-level.png)
 
-- A general overview what it is about
-- By clicking "more" the whole manual is provided for the add-on
-- An information section that provides
-  - Source (openHAB or Community Marketplace)
-  - Provided by (the author of the add-on)
-  - type of add-on (binding, automation...)
-  - Content type (Karaf, Template, UI Widget...)
-  - Created and Update date
-  - A link to the related community forum entry
-
-Note that there is a tabbar at the bottom that allows you to switch between the different pages:
-
-![addons-toolbar](images/addons-toolbar.png)
-
-  [[toc]]
-
-## Bindings
-
-Bindings are used to connect and control hardware and online services. This section provides bindings from openHAB Distribution, which have been thoroughly reviewed by the maintainers of openHAB and also bindings from Community Marketplace.
-If you want to know more about the marketplace, please read the following [Marketplace announcement](https://community.openhab.org/t/announcing-the-community-marketplace/127188).
-
-To learn more how to install tutorial see the  [Installation of Add-ons tutorial](/docs/configuration/addons.html).
-
-## Automation
-
-Automation provides technologies that allow you to write rules and scripts.
-
-- **Languages & Technologies**
-openHAB comes with three languages by default: Rules DSL, ECMAScript 5.1, and Blockly while this section allows to install more languages and technologies but just installing them from this place.
-To know more about them click on the respective tile.
-
-- **Rule templates** provide you with solutions already written for certain usecases t
-Rule templates can be used when you have a common use case for a rule and for instance need to bootstrap several of them, or share with others how to solve that use case in a configurable manner.
-These will appear in the Main UI when you create a new rule, and will present you with the configuration parameters - after the rule is created, the pre-configured rule modules (triggers, conditions, actions) will appear based on your choices.
-
-- Block Libraries, community extensions to the [Blockly](/docs/configuration/blockly/) toolbox
-These libraries extend the core blockly library with many useful blocks that might else be a bit too specific for the core block library or just fills the gap where a core block is still missing.
-When installed they appear in a separate section beneath the core blocks of the blockly editor.
-
-## User Interfaces
-
-Community widgets & alternative frontends
-
-- **Widgets for the Main UI**: Extend your pages with these community-designed widgets
-After adding a widget it can be used when creating UI page.
-You can the press the "+" on a cell and a popup appears with two section: _Standard Library_, which contains the standard openHAB widgets and Personal Widgets which contain the add UI widgets from here.
-They can also be found for further adapting (or analyzing) the widget under "Developer Tools ->  Widgets".
-- **Other UI Add-ons**: Alternative user interfaces and icon sets
-openHAB by default support the Basic UI as well as the HABPanel (which used to be the standard before openHAB 3).
-However, openHAB supports some more User Interfaces like
-  - the [CometVisu-Backend](https://www.cometvisu.org/)
-  - PHP support for CometVisu
-  - and [HABot](/docs/ui/habot/),
-
-## Other Add-ons
-
-- **System integrations**: Integrate openHAB with external systems
-Here you can found the
-  - openHAB Cloud Connector
-  - Homekit Integration
-  - openHAB Metric Service, an additional REST endpoint to retrieve openHAB core metrics from.
-  - and other like Hue Emulation, Imperi Integration, NEEO Integration, Log4j2 Extra and Cloud Connector Troubleshouting
-
-- **Persistence**: Backend connectors to store historical data like
-  - RRD
-  - InfluxDB
-  - mongoDB
-  - MapDB
-  - several JDBC Connectors and
-  - JPA Persistence
-
-- **Transformation Add-ons**: Extensions for a particular transformation like
-  - JSONPath
-  - RegEx
-  - Map
-  - Binary To JSON
-  - Exec (executes an external program and returns the output as a string)
-  - Jinja
-  - Scale (the Scale transformation service is an easy to handle tool that can help you with the discretization of number inputs)
-  - Xpath
-  - XSLT
-  - Multi / long press transformation profile for rocker switch
-
-- **Voice & Speech**: Convert between text and speech, interpret human language queries
-  - Google Cloud Text-to-Speech
-  - Amazon Polly
-  - VoiceRSS Text-to-Speech
-  - and many more
-
-## Search
-
-allows you to search for any of the above add-ons and then directly install it from here.
+The standard log level is "Info" but to track down an issue it might be necessary to increase the log-level upon request.
+For more information see [Logging in openHAB]({{base}}/administration/logging.html)

settings/automations.md

@@ -3,7 +3,7 @@ layout: documentation
 title:  Automation
 ---
 
-# Settings - Automation
+# Automation
 
 This is the section to automate openHAB which provides rules, script and a scheduling section.
 See [What's the Difference Between a Rule, Script, and Schedule?](/docs/tutorial/rules_introduction.html#what-s-the-difference-between-a-rule-script-and-schedule)

settings/configuration.md

@@ -3,7 +3,7 @@ layout: documentation
 title:  Configuration
 ---
 
-# Settings - Configuration
+# Configuration
 
 This section allows the configuration of things, items and user interface pages
 

settings/index.md

@@ -19,6 +19,5 @@ Some of these subpages, which are most often used, can also be accessed directly
 
 - [Configuration](/docs/settings/configuration.html)
 - [Automation](/docs/settings/automations.html)
+- [System Settings](/docs/settings/system_settings.html)
 - [Add-ons](/docs/settings/addons.html)
-- [System Services](/docs/settings/services_system.html)
-- [Other Services](/docs/settings/services_other.html)

settings/services_other.md

@@ -1,18 +0,0 @@
----
-layout: documentation
-title:  Other Services
----
-
-# Setting - other services
-
-This is the section of all other services
-
-  [[toc]]
-
-## Rule Voice Interpreter
-
-## Language Server (LSP)
-
-## openhab Cloud
-
-## Basic UI

settings/services_system.md

@@ -1,38 +0,0 @@
----
-layout: documentation
-title:  System Services
----
-
-# System Services
-
-This is the section that of the system services
-
-  [[toc]]
-
-## Regional Settings
-
-## Network Settings
-
-## Audio
-
-## Ephemeris
-
-## API Security
-
-## Add-on Management
-
-## Persistence
-
-## JSON Storage
-
-## Community Marketplace
-
-## Json 3rd Party Add-on Service
-
-## Inbox
-
-## Charts
-
-## Sitemap
-
-## Voice

settings/system_settings.md

@@ -0,0 +1,47 @@
+---
+layout: documentation
+title:  System Settings
+---
+
+# System Settings
+
+This is the section that of the system settings
+
+  [[toc]]
+
+## Regional Settings
+
+## Unit Settings
+
+## Network Settings
+
+## Audio
+
+## JSON Storage
+
+## Persistence
+
+## API Security
+
+## Rule Voice Interpreter
+
+## Add-on Management
+
+## Community Marketplace
+
+## Json 3rd Party Add-on Service
+
+## Voice
+
+## Charts
+
+## Sitemap
+
+## Inbox
+
+## Ephemeris
+
+## Language Server (LSP)
+
+**Note:** Originally it included settings for openHAB cloud, Basic UI etc.
+These can now be found in the _Add-on Settings_.

tutorials/getting_started/tips-and-tricks.md

@@ -44,33 +44,7 @@ Imagine you need to find all usages of an Item in rules or pages.
 You could open all your rules and pages to check them, or just use the developer sidebar search.
 Enter your Item name, and you will see in which rules, scenes, scripts and pages that Item is used.
 
-The developer sidebar search ignores case and searches inside the following entities:
-
-- Things
-  - UID
-  - label
-- Items
-  - name
-  - label
-  - tags (requires exact match)
-  - metadata
-- Pages
-  - uid
-  - label
-  - content (widgets, tabs, charts, etc. with their configuration)
-- Transformations
-  - uid
-  - label
-  - type
-- Rules, Scenes & Scripts
-  - Item name & Thing UID of triggers, actions & conditions
-  - script code (e.g. Rules DSL, JavaScript, and even Blockly)
-  - script MIME types (requires exact match)
-  - Blockly scripts (using 'block', 'blockly' or 'blocksource' as search string, where case is ignored)
-  - tags (requires exact match)
-- Persistence Configurations:
-  - label & service id of persistence service
-  - Items persisted by persistence service
+For more information about the search and which entities are searchable, please refer to the [Developer Sidebar docs]({{base}}/ui/mainui.html#developer-sidebar-search).
 
 ### Pinned Objects
 

ui/addons-store.md

@@ -0,0 +1,115 @@
+---
+layout: documentation
+title: Add-ons Store
+---
+
+# Add-ons Store
+
+This is the section that allows openHAB to be extended via add-ons.
+There is a huge variety of extension possibilities that openHAB provides:
+
+- **Bindings** are used to connect and control hardware and online services. This section provides
+  - **openHAB Distribution**: Official bindings maintained by the openHAB project and
+  - **Community Marketplace**: Bindings independently released by the community.
+- **Automation** contains scripting languages, templates and module types
+  - **languages** like Groovy, JRuby, Jython, JavaScript or
+  - **technologies** like PID Controller, PWM (pulse width modulation)
+  - **Rule Templates** shared by the community to bootstrap your automation
+  - **[Blockly](/docs/configuration/blockly/)** libraries that contain custom blocks written by the community.
+- **UI / User Interface**: Widgets for the Main UI
+- **Other...**: System Integrations, Persistence Services, Transformation Services and Voice & Speech
+
+Clicking on the individual tile reveals more information about the add-on:
+
+- A general overview what it is about
+- By clicking "more" the whole documentation is provided for the add-on
+- An information section that provides
+  - Source (openHAB or Community Marketplace)
+  - Provided by (the author of the add-on)
+  - Type of add-on (binding, automation...)
+  - Content type (Karaf, Template, UI Widget...)
+  - Created and Update date
+  - A link to the related community forum entry
+
+Note that there is a tab bar at the bottom that allows you to switch between the different pages:
+
+![addons-toolbar](images/addons-toolbar.png)
+
+[[toc]]
+
+## Bindings
+
+Bindings are used to connect and control hardware and online services. This section provides bindings from openHAB Distribution, which have been thoroughly reviewed by the maintainers of openHAB, as well as bindings from the Community Marketplace.
+If you want to know more about the marketplace, please read the following [Marketplace announcement](https://community.openhab.org/t/announcing-the-community-marketplace/127188).
+
+To learn more how to install tutorial see the  [Installation of Add-ons tutorial](/docs/configuration/addons.html).
+
+## Automation
+
+Automation provides technologies that allow you to write rules and scripts.
+
+- **Languages & Technologies**
+  openHAB comes with two languages by default: Rules DSL and Blockly (which requires a JavaScript Scripting automation add-on to be installed) while this section allows to install more languages and technologies.
+  To know more about them click on the respective tile.
+
+- **Rule templates** provide you with solutions already written for certain usecases.
+  Rule templates can be used when you have a common use case for a rule and for instance need to bootstrap several of them, or share with others how to solve that use case in a configurable manner.
+  These will appear in Main UI when you create a new rule, and will present you with the configuration parameters - after the rule is created, the pre-configured rule modules (triggers, conditions, actions) will appear based on your choices.
+
+- Block Libraries, community extensions to the [Blockly](/docs/configuration/blockly/) toolbox
+  These libraries extend the core blockly library with many useful blocks that might else be a bit too specific for the core block library or just fills the gap where a core block is still missing.
+  When installed they appear in a separate section beneath the core blocks of the blockly editor.
+
+## User Interfaces
+
+Community widgets & alternative frontends
+
+- **Widgets for Main UI**: Extend your pages with these community-designed widgets
+  After adding a widget it can be used when creating UI page.
+  You can the press the "+" on a cell and a popup appears with two section: _Standard Library_, which contains the standard openHAB widgets and Personal Widgets, which contain UI widgets installed from the marketplace.
+  They can also be found for further adapting (or analyzing) the widget under "Developer Tools ->  Widgets".
+- **Other UI Add-ons**: Alternative user interfaces and icon sets
+  openHAB by default support the Basic UI as well as the HABPanel (which used to be the standard before openHAB 3).
+  However, openHAB supports some more User Interfaces like
+  - the [CometVisu-Backend](https://www.cometvisu.org/)
+  - PHP support for CometVisu
+  - and [HABot](/docs/ui/habot/),
+
+## Other Add-ons
+
+- **System integrations**: Integrate openHAB with external systems
+  Here you can find the
+  - openHAB Cloud Connector
+  - Homekit Integration
+  - openHAB Metric Service, an additional REST endpoint to retrieve openHAB core metrics from.
+  - and others...
+
+- **Persistence**: Backend connectors to store historical data like
+  - RRD
+  - InfluxDB
+  - MongoDB
+  - MapDB
+  - Several JDBC Connectors and
+  - JPA Persistence
+
+- **Transformation Add-ons**: Extensions for a particular transformation like
+  - JSONPath
+  - RegEx
+  - Map
+  - Binary To JSON
+  - Exec (executes an external program and returns the output as a string)
+  - Jinja
+  - Scale (the Scale transformation service is an easy to handle tool that can help you with the discretization of number inputs)
+  - Xpath
+  - XSLT
+  - Multi / long press transformation profile for rocker switch
+
+- **Voice & Speech**: Convert between text and speech, interpret human language queries
+  - Google Cloud Text-to-Speech
+  - Amazon Polly
+  - VoiceRSS Text-to-Speech
+  - and many more
+
+## Search
+
+Search for any of the above add-ons and then directly install it from here.

ui/developer-tools.md

@@ -0,0 +1,26 @@
+---
+layout: documentation
+title: Developer Tools
+---
+
+# Developer Tools
+
+The developer tools consist of two tabs **Expert Features** and **Debug**.
+
+## Expert Features
+
+### Advanced Object Management
+
+- Widgets
+- Block Libraries
+- Add Items from Textual Definition
+
+### Maintenance Tools
+
+- Developer Sidebar
+- API Explorer
+
+## Debug
+
+- Test SSE Connection
+- Test an Icon

ui/mainui.md

@@ -0,0 +1,113 @@
+---
+layout: documentation
+title: Main UI
+---
+
+# Main UI
+
+Since openHAB 3.0, the so-called "Main UI" is the main web user interface of openHAB.
+Main UI allows the administrator (you) to set up and configure openHAB, and provides many types of pages to visualize data and control Items.
+
+This page aims at providing an overview over Main UI's "special" features, which means it does not try to document Main UI in general or provide a comprehensive overview over all its many capabilities and configuration pages.
+If you are new to openHAB, please refer to the [Getting Started guide]({{base}}/tutorial/), which is introducing you to Main UI by using it to set up openHAB.
+
+[[toc]]
+
+## Developer Sidebar
+
+Main UI provides a developer sidebar for administrator user(s), that is accessible from anywhere in the UI.
+The developer sidebar is split into a "tools" section with several useful tools including a universal search across nearly all UI-configurable entities and a widget expression tester, and a "help" section aiming at providing help and useful information regarding configuration and setup.
+
+If your device's screen is wide enough (it has to be at least 1280 pixels wide), you can open the developer side-panel by:
+
+- Opening the **Developer Tools** page from the menu and enabling the developer sidebar.
+- Clicking on the help icon displayed in the upper right corner of most pages.
+- Pressing the key combination <kbd>Alt</kbd><kbd>Shift</kbd><kbd>D</kbd> on your keyboard.
+
+### Developer Sidebar Search
+
+As already mentioned, the developer sidebar provides a universal search across nearly all UI-configurable entities.
+This means, you can search through most configuration available in Main UI, including Things, Items, pages.
+
+Imagine you need to find all usages of an Item.
+You could start to open all rules, scenes and scripts, check persistence configuration and have a look at pages and sitemaps to find usages of that Item - Or you use the developer sidebar search.
+
+The developer sidebar search ignores case (so it doesn't matter whether you search `LivingRoom_Light` or `livingroom_light`) and searches inside the following entities:
+
+- Things
+  - UID
+  - label
+- Items
+  - name
+  - label
+  - tags (requires exact match, i.e. if the Item has a tag `Lightbulb`, only the search query `Lightbulb` (case doesn't matter) will match)
+  - metadata
+- Pages (including Sitemaps)
+  - uid
+  - label
+  - content (widgets, tabs, charts, etc. with their configuration)/slots
+- Transformations
+  - uid
+  - label
+  - type
+- Rules, Scenes & Scripts
+  - Item name & Thing UID of triggers, actions & conditions
+  - script code (e.g. Rules DSL, JavaScript, and even Blockly)
+  - script MIME types (requires exact match)
+  - Blockly scripts (using `block`, `blockly` or `blocksource` as search string, where case is ignored)
+  - tags (requires exact match)
+- Persistence Configurations:
+  - label & service id of persistence service
+  - Items persisted by persistence service
+
+## Web Audio Sink
+
+Main UI implements a web audio sink which allows the openHAB server to play audio through the web browser.
+
+To enable web audio sink support for a client, open the **Help & About** page from the menu and turn on the **Enable Web Audio sink support** option.
+As it is setting specific to your browser environment, web audio support has to be enabled for every client where it should be used.
+
+Please note that due to limitations in Safari (and possibly Chrome as well), a user interaction is required after the first audio stream has been sent to actually play it.
+This means, that after opening Main UI, the first audio that should be played on the web audio sink is only player after the user interacts with Main UI in any way (i.e. touching the screen is enough).
+For subsequent audio playback, that is not required anymore and the audio is played immediately.
+
+Please also note that you cannot address a particular web audio-enabled device.
+When you play a sound on web audio, it will be played on all devices where web audio is enabled.
+
+Web audio sinks can be used for example on wall-mounted tablets to make announcements using a [text-to-speech (TTS) engine]({{base}}/configuration/multimedia.html#text-to-speech) and play notification or alarm sounds.
+
+For more information about audio sinks as well as audio and voice actions, please refer to the [multimedia configuration docs]({{base}}/configuration/multimedia.html), where you will also find examples including UI-based rules and Blockly.
+
+## UI Command Item
+
+Main UI can be controlled from the openHAB server by setting up a so-called UI command Item.
+
+Similarly to web audio support, this is a setting specific to your local browser environment, so you have to define the UI command Item for each client, which also allows you to different UI command Items for different clients.
+To set up an Item as the UI command Item on your device, first create a particular Item of type `String`, then open the **Help & About** page from the menu and select an Item for the **Listen for UI command to** option.
+
+The command Item has to be a `String` Item.
+The UI is listening for commands to that Item, and if an Item command is a valid command string, the UI executes the given command.
+
+Currently, the supported commands are:
+
+- `navigate:$path`:
+  Navigate to a given `$path`, e.g. `navigate:/locations` to navigate to the **Locations** tab of the home page or `navigate:/page/my_custom_page` to navigate to a page with the ID `my_custom_page`.
+  For example, you can use this to open a video camera page of the door automatically when the doorbell is rung.
+- `popup:$target`, `popover:$target` and `sheet:$target`:
+  Open a `$target`, which can be a page (`$target` is `page:` + a page ID), a custom widget (`$target` is `widget:` + widget ID) or any [`oh-` component]({{base}}/ui/components/) (`$target` is the component name), in a popup, popover or sheet.
+
+  For example, to open `oh-clock-card` inside a popup, send `popup:oh-clock-card` to the UI command Item.
+- `notification:$text:$title:$subtitle:$titleRight:$closeTimeout`:
+  Display a notification inside the UI:
+  The `$text` parameter is mandatory, all other parameters are optional.
+  `$closeTimeout` is in milliseconds and defaults 5000, which means by default a notification will be closed after 5 seconds.
+  To leave out a parameter, leave a colon space empty, e.g. `notification:$text:$title:::$closeTimeout`.
+
+  For example, send `notification:This is the text.:This is the title.:This is the subtitle.:This is the right title.` to the UI command Item to display the following notification:
+  <p align="center"><img style="max-width: 40%;" src="images/notification.png"/></p>
+- `close`:
+  Close all popups, popovers and sheets.
+- `back`:
+  Navigate back.
+- `reload`:
+  Reload the current page.

ui/widget-expressions-variables.md

@@ -126,31 +126,31 @@ Sometimes, however, it is helpful to add more information to a variable and for
 The widget expression system can create objects in two different ways:
 
 - JavaScript object syntax:
-  
+
   Objects can be defined within the expression system using the standard JavaScript syntax: `{'key1':'value1','key2':'value2'}`.
   If a key doesn't contain special characters such as spaces, the quotes around keys can usually be ommited:  `{key1:'value1',key2:'value2'}`.
-  
+
   ::: tip
-  
+
   Due to the special meaning of `:[space]` in yaml, it is best to have no spaces between the `:` and the value.
   If you have `:[space]` anywhere in your expression it will raise a YAML error unless you enclose the entire expression (= included) in another layer of quotes.
-  
+
   :::
-  
+
   Example:
-  
+
   ```yaml
   actionVariable: myObject
   actionVariableValue: ={'name':props.item,'selected':true}
   ```
-  
+
   In this example, a variable is set to an object with keys `name` and `selected` using JavaScript object expression syntax.
-- YAML object syntax
+- YAML object syntax:
 
   The other way to create objects is to take advantage of the relationship between YAML and JSON and place the key:value pairs as YAML keys under the initial key.
-  
+
   Here is a variable definition with the same results as the one above using the YAML syntax.
-  
+
   ```yaml
   actionVariable: myObject
   actionVariableValue:
@@ -214,5 +214,5 @@ Substract one week from the state of `DateTime` and return a relative time repre
 
 ## Debugging Expressions
 
-Expressions can be tested in the Widgets Expression Tester found in the Developer Sidebar
+Expressions can be tested in the Widgets Expression Tester found in the [Developer Sidebar](mainui.html#developer-sidebar)
 (<kbd>Shift</kbd><kbd>Alt</kbd><kbd>D</kbd>).