refactor config schema sections

scripts/sitemap.ts

@@ -32,7 +32,11 @@ const sitemap = [
   `${baseUrl}/api/matter-errors`,
   `${baseUrl}/api/matter-devices`,
   `${baseUrl}/api/matter-clusters`,
-  `${baseUrl}/config-schema`,
+  `${baseUrl}/config-screen/overview`,
+  `${baseUrl}/config-screen/schema`,
+  `${baseUrl}/config-screen/schema-examples`,
+  `${baseUrl}/config-screen/custom-ui`,
+  `${baseUrl}/config-screen/custom-ui-examples`,
   `${baseUrl}/categories`,
 ]
 

src/app/app.routes.ts

@@ -49,6 +49,22 @@ export const routes: Routes = [
     path: 'matter-device-type',
     redirectTo: 'matter-device-type/AirQualitySensor',
   },
+  // The config screen section moved from two flat pages to /config-screen/* in
+  // 2026-08 - the old urls are linked from wikis, plugin READMEs and issues,
+  // so they redirect rather than 404.
+  {
+    path: 'config-schema',
+    redirectTo: 'config-screen/schema',
+  },
+  {
+    path: 'custom-plugin-ui',
+    redirectTo: 'config-screen/custom-ui',
+  },
+  {
+    path: 'config-screen',
+    pathMatch: 'full',
+    redirectTo: 'config-screen/overview',
+  },
   {
     path: 'api',
     loadComponent: () =>

src/app/sidebar/sidebar.component.html

@@ -180,19 +180,39 @@
       <li class="nav-item section-title mt-3">
         <a
           class="nav-link"
-          [routerLink]="['/config-schema']"
-          [class.active]="isSectionActive('/config-schema', '/custom-plugin-ui')"
+          [routerLink]="['/config-screen/overview']"
+          [class.active]="isSectionActive('/config-screen')"
         >
-          <span class="theme-icon-holder me-2"><i class="fas fa-code"></i></span>Plugin Config Schema
+          <span class="theme-icon-holder me-2"><i class="fas fa-code"></i></span>Plugin Config Screen
         </a>
       </li>
 
       <li class="nav-item">
-        <a class="nav-link pointer" routerLinkActive="active" [routerLink]="['/custom-plugin-ui']"
+        <a class="nav-link pointer" routerLinkActive="active" [routerLink]="['/config-screen/overview']">Overview</a>
+      </li>
+
+      <li class="nav-item">
+        <a class="nav-link pointer" routerLinkActive="active" [routerLink]="['/config-screen/schema']">Config Schema</a>
+      </li>
+
+      <li class="nav-item">
+        <a class="nav-link pointer" routerLinkActive="active" [routerLink]="['/config-screen/schema-examples']"
+          >Schema Examples</a
+        >
+      </li>
+
+      <li class="nav-item">
+        <a class="nav-link pointer" routerLinkActive="active" [routerLink]="['/config-screen/custom-ui']"
           >Custom User Interfaces</a
         >
       </li>
 
+      <li class="nav-item">
+        <a class="nav-link pointer" routerLinkActive="active" [routerLink]="['/config-screen/custom-ui-examples']"
+          >Custom UI Examples</a
+        >
+      </li>
+
       <li class="nav-item section-title mt-3">
         <a
           class="nav-link"

src/docs/config-screen/custom-ui-examples.md

@@ -0,0 +1,40 @@
+# Custom UI Examples
+
+Working examples and real plugins to learn from when building a [custom user interface](/#/config-screen/custom-ui).
+
+## Official Examples
+
+- [Basic Example](https://github.com/homebridge/plugin-ui-utils/blob/master/examples/basic-ui-server) - demos a minimal custom user interface, interacting with server side scripts, updating the plugin config, and using toast notifications.
+- [Push Events](https://github.com/homebridge/plugin-ui-utils/blob/master/examples/push-events) - demos how to send push events from the server, and listen for them in the custom user interface.
+
+A full list of plugins that have implemented the custom user interface can be found [here](https://www.npmjs.com/package/@homebridge/plugin-ui-utils?activeTab=dependents).
+
+## Notable Plugins
+
+### homebridge-mercedesme
+
+The [homebridge-mercedesme](https://github.com/SeydX/homebridge-mercedesme) plugin by [@SeydX](https://github.com/SeydX) allows users to pair their vehicle using a custom user interface:
+
+<p align="center">
+<img src="https://raw.githubusercontent.com/SeydX/homebridge-mercedesme/beta/images/hb_mercedesme_ui.gif" width="900">
+</p>
+
+### homebridge-bravia-tvos
+
+The [homebridge-bravia-tvos](https://github.com/SeydX/homebridge-bravia-tvos) plugin by [@SeydX](https://github.com/SeydX) allows users to pair and dynamically configure a user's TV using a custom user interface:
+
+<p align="center">
+<img src="https://user-images.githubusercontent.com/3979615/99958753-0a13ee00-2dde-11eb-95fb-69a896d37545.png" width="600">
+</p>
+
+### homebridge-electra-smart
+
+The [homebridge-electra-smart](https://github.com/nitaybz/homebridge-electra-smart) plugin by [nitaybz](https://github.com/nitaybz) allows users to request a OTP and enter it in exchange for an authentication token:
+
+<p align="center">
+<img src="https://user-images.githubusercontent.com/3979615/99959242-be157900-2dde-11eb-8114-6394da2a2e14.png" width="600">
+</p>
+
+## Development
+
+For hints and tips on how to develop your custom user interface, see [DEVELOPMENT.md](https://github.com/homebridge/plugin-ui-utils/blob/master/DEVELOPMENT.md).

src/docs/custom-plugin-ui.md → src/docs/config-screen/custom-ui.md

@@ -1,6 +1,6 @@
 # Custom User Interfaces
 
-The Homebridge UI provides the ability for developers to create fully custom user interfaces that can be used to configure and manage the plugin. This is ideal if you have more complex requirements than what the standard `config.schema.json` syntax can support.
+The Homebridge UI provides the ability for developers to create fully custom user interfaces that can be used to configure and manage the plugin. This is ideal if you have more complex requirements than what the standard [`config.schema.json`](/#/config-screen/schema) syntax can support.
 
 The [@homebridge/plugin-ui-utils](https://github.com/homebridge/plugin-ui-utils) package assists plugin developers creating fully customisable configuration user interfaces for their plugins.
 
@@ -20,8 +20,8 @@ The [@homebridge/plugin-ui-utils](https://github.com/homebridge/plugin-ui-utils)
   - [Request Error Handling](#request-error-handling)
   - [Push Events](#push-events)
   - [Server Information](#server-information)
-- [Examples](#examples)
-- [Development](#development)
+
+Working examples, notable plugins to learn from, and development tips live on the [Custom UI Examples](/#/config-screen/custom-ui-examples) page.
 
 ## Implementation
 
@@ -631,40 +631,3 @@ Returns the version of the Homebridge UI:
 ```ts
 const uiVersion = this.homebridgeUiVersion
 ```
-
-## Examples
-
-- [Basic Example](https://github.com/homebridge/plugin-ui-utils/blob/master/examples/basic-ui-server) - demos a minimal custom user interface, interacting with server side scripts, updating the plugin config, and using toast notifications.
-- [Push Events](https://github.com/homebridge/plugin-ui-utils/blob/master/examples/push-events) - demos how to send push events from the server, and listen for them in the custom user interface.
-
-A full list of plugins that have implemented the custom user interface can be found [here](https://www.npmjs.com/package/@homebridge/plugin-ui-utils?activeTab=dependents).
-
-### Notable Plugins
-
-#### homebridge-mercedesme
-
-The [homebridge-mercedesme](https://github.com/SeydX/homebridge-mercedesme) plugin by [@SeydX](https://github.com/SeydX) allows users to pair their vehicle using a custom user interface:
-
-<p align="center">
-<img src="https://raw.githubusercontent.com/SeydX/homebridge-mercedesme/beta/images/hb_mercedesme_ui.gif" width="900">
-</p>
-
-#### homebridge-bravia-tvos
-
-The [homebridge-bravia-tvos](https://github.com/SeydX/homebridge-bravia-tvos) plugin by [@SeydX](https://github.com/SeydX) allows users to pair and dynamically configure a user's TV using a custom user interface:
-
-<p align="center">
-<img src="https://user-images.githubusercontent.com/3979615/99958753-0a13ee00-2dde-11eb-95fb-69a896d37545.png" width="600">
-</p>
-
-#### homebridge-electra-smart
-
-The [homebridge-electra-smart](https://github.com/nitaybz/homebridge-electra-smart) plugin by [nitaybz](https://github.com/nitaybz) allows users to request a OTP and enter it in exchange for an authentication token:
-
-<p align="center">
-<img src="https://user-images.githubusercontent.com/3979615/99959242-be157900-2dde-11eb-8114-6394da2a2e14.png" width="600">
-</p>
-
-## Development
-
-For hints and tips on how to develop your custom user interface, see [DEVELOPMENT.md](https://github.com/homebridge/plugin-ui-utils/blob/master/DEVELOPMENT.md).

src/docs/config-screen/overview.md

@@ -0,0 +1,31 @@
+# Plugin Config Screen
+
+Every plugin installed through the Homebridge UI has a settings screen, reached from the plugin's **Settings** button. What that screen looks like depends on what your plugin ships:
+
+| Level          | What you publish                                          | What the user sees                                                                                       |
+| -------------- | --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
+| None           | Nothing extra                                             | The raw JSON config editor. Users must edit your plugin's config block by hand.                          |
+| Generated form | A [`config.schema.json`](/#/config-screen/schema) file    | A settings form generated from your schema — inputs, dropdowns, validation, help text. No code required. |
+| Custom UI      | A [`homebridge-ui`](/#/config-screen/custom-ui) directory | A fully custom HTML/CSS/JavaScript interface, with an optional server-side script.                       |
+
+## The Generated Form
+
+For most plugins, a `config.schema.json` file is all you need. Publish it in the root of your npm package and the Homebridge UI will detect it and show the **Settings** button on your plugin's page:
+
+![image](https://user-images.githubusercontent.com/3979615/58320524-29cffc00-7e5f-11e9-94e1-114cd77c18c4.png)
+
+Users then configure your plugin through a form instead of editing the Homebridge `config.json` by hand. Both **platform** and **accessory** plugin types are supported.
+
+See [Config Schema](/#/config-screen/schema) for the file format, and [Schema Examples](/#/config-screen/schema-examples) for complete real-world schemas.
+
+## Custom User Interfaces
+
+If your plugin has requirements the generated form cannot express — an OAuth2 workflow, exchanging a username and password for a token, discovering devices to pair — you can replace the form with a fully custom user interface using the [@homebridge/plugin-ui-utils](https://github.com/homebridge/plugin-ui-utils) package.
+
+See [Custom User Interfaces](/#/config-screen/custom-ui) for the API, and [Custom UI Examples](/#/config-screen/custom-ui-examples) for working examples and plugins to learn from.
+
+## Which Should I Use?
+
+- Start with a `config.schema.json`. It covers most plugins, needs no code, and users get validation for free.
+- Move to a custom UI only when the form genuinely cannot do what you need. A custom UI is more work to build and maintain, and you become responsible for updating the config yourself.
+- The two are not exclusive: a custom UI can [render your schema-generated form](/#/config-screen/custom-ui#homebridgeshowschemaform) inside itself, or build its own forms from a schema.