Split plugins page in "user-definded devices" and "reference->plugins" (#1069)

Author: naltatis

AGENTS.md

@@ -83,6 +83,7 @@ Everything else is hand-written:
 - **Always write "evcc" in lowercase** — even at the beginning of sentences
 - Never use "EVCC", "Evcc", or other variations
 - Prefer "your evcc instance" over a bare "evcc" when referring to a running instance
+- Don't mention "evcc" unless necessary for context — within evcc docs the reader already knows. Drop self-referential fluff like "another strength of evcc", "evcc ships with", "the evcc UI"
 
 ### Language & Tone
 
@@ -201,9 +202,16 @@ Everything else is hand-written:
 
 - Use locale-prefixed absolute paths (`/en/...`, `/de/...`) for clarity
 - Keep anchor names (`#section`) consistent between translations
-- **Create explicit anchors** with `{#anchor-name}` on headings instead of relying on auto-generated ones
+- **Create explicit anchors** on headings instead of relying on auto-generated ones
   - Auto-generated anchors change with heading text and differ between languages
-  - Example: `### Vehicle Detection {#vehicle}` ensures stable, language-independent linking
+  - In `.md` files use the compact form: `### Vehicle Detection {#vehicle}`
+  - In `.mdx` files use a raw HTML anchor element on the line above (MDX parses `{...}` as a JSX expression, so the compact form breaks the build):
+
+    ```mdx
+    <a id="vehicle"></a>
+
+    ### Vehicle Detection
+    ```
 
 ### Documentation Best Practices
 

astro.config.mjs

@@ -6,12 +6,16 @@ import starlightBlog from "starlight-blog";
 import starlightLlmsTxt from "starlight-llms-txt";
 import starlightOpenAPI, { openAPISidebarGroups } from "starlight-openapi";
 import mermaid from "astro-mermaid";
+import remarkHeadingId from "remark-heading-id";
 export default defineConfig({
   site: "https://docs.evcc.io",
   trailingSlash: "never",
   build: {
     format: "directory",
   },
+  markdown: {
+    remarkPlugins: [remarkHeadingId],
+  },
   redirects: {
     "/": "/en",
     "/docs": "/de",
@@ -20,8 +24,6 @@ export default defineConfig({
     "/en/docs/Home": "/en",
     "/docs/reference/api": "/en/integrations/rest-api",
     "/en/docs/reference/api": "/en/integrations/rest-api",
-    "/de/reference/plugins": "/de/plugins",
-    "/en/reference/plugins": "/en/plugins",
   },
   integrations: [
     mermaid({
@@ -137,21 +139,22 @@ export default defineConfig({
               link: "/heating",
             },
             {
-              label: "Plugins",
-              link: "/plugins",
+              label: "User-defined devices",
+              translations: { de: "Benutzerdefinierte Geräte" },
+              link: "/user-defined-devices",
             },
           ],
         },
-        {
-          label: "Features",
-          translations: { de: "Funktionen" },
-          items: [{ autogenerate: { directory: "features", collapsed: true } }],
-        },
         {
           label: "Tariffs & forecasts",
           translations: { de: "Tarife & Vorhersagen" },
           link: "/tariffs",
         },
+        {
+          label: "Features",
+          translations: { de: "Funktionen" },
+          items: [{ autogenerate: { directory: "features", collapsed: true } }],
+        },
         {
           label: "Integrations",
           translations: { de: "Integrationen" },
@@ -182,6 +185,7 @@ export default defineConfig({
                 },
               ],
             },
+            { label: "Plugins", slug: "reference/plugins" },
             { label: "Modbus", slug: "reference/modbus" },
             {
               label: "CLI",

src/components/UserDefinedHint.astro

@@ -0,0 +1,36 @@
+---
+interface Props {
+  lang: "de" | "en";
+  kind?: "device" | "service";
+}
+
+const { lang, kind = "device" } = Astro.props;
+
+const issuesUrl = "https://github.com/evcc-io/evcc/issues/new/choose";
+const userDefinedUrl = `/${lang}/user-defined-devices`;
+
+const t = lang === "de"
+  ? {
+      title: "Dein Gerät nicht dabei?",
+      titleService: "Dein Dienst nicht dabei?",
+      body:
+        kind === "service"
+          ? `Eröffne einen <a href="${issuesUrl}">Feature Request</a> auf GitHub oder definiere einen <a href="${userDefinedUrl}#tariff">eigenen Dienst</a> über das Plugin-System.`
+          : `Eröffne einen <a href="${issuesUrl}">Feature Request</a> auf GitHub oder definiere ein <a href="${userDefinedUrl}">eigenes Gerät</a> über das Plugin-System.`,
+    }
+  : {
+      title: "Device not in the list?",
+      titleService: "Service not in the list?",
+      body:
+        kind === "service"
+          ? `Open a <a href="${issuesUrl}">feature request</a> on GitHub or build your own <a href="${userDefinedUrl}#tariff">user-defined service</a> via the plugin system.`
+          : `Open a <a href="${issuesUrl}">feature request</a> on GitHub or build your own <a href="${userDefinedUrl}">user-defined device</a> via the plugin system.`,
+    };
+
+const title = kind === "service" ? t.titleService : t.title;
+---
+
+<aside class="starlight-aside starlight-aside--note" aria-label={title}>
+  <p class="starlight-aside__title" aria-hidden="true">{title}</p>
+  <p set:html={t.body} />
+</aside>

src/content/docs/de/blog/2025/07/30/highlights-config-ui-feedin-ai.mdx

@@ -107,7 +107,7 @@ Zudem ist das Authentifizierungssystem gesperrt und damit auch alle geschützten
 Über die Konfigurationsoberfläche konnten bisher bereits Fahrzeuge, Zähler, PV-, Batteriesysteme, Wallboxen, Tarife, schaltbare Steckdosen und Wärmepumpen angelegt werden.
 Basis dafür ist unsere große Bibliothek an Geräte-Templates für inzwischen über 550 Produkte.
 
-Eine weitere Stärke von evcc ist das [flexible Plugin System](/de/plugins).
+Eine weitere Stärke ist das [flexible Plugin System](/de/reference/plugins).
 Damit können auch exotische Geräte und Integrationen mithilfe von HTTP, Modbus, Script, MQTT, ... verbunden werden.
 Diese benutzerdefinierten Geräte (`type: custom`) mussten bislang über die `evcc.yaml` konfiguriert werden.
 Nun ist dies auch über die UI möglich – komfortabel mit Syntax-Highlighting, Validierung und Prüfen-Funktion.

src/content/docs/de/faq.mdx

@@ -215,7 +215,7 @@ Wie du das Log aufrufst, findest du in der [Installation](/de/installation) unte
 
 ### MQTT plugin gibt `outdated` Warnung
 
-Bei der Nutzung des [MQTT plugins](devices/plugins#mqtt) kann über den `timeout` parameter gesteuert werden, wie lange ein Wert der per MQTT erhalten wurde, gültig ist.
+Bei der Nutzung des [MQTT plugins](/de/reference/plugins#mqtt) kann über den `timeout` parameter gesteuert werden, wie lange ein Wert der per MQTT erhalten wurde, gültig ist.
 Wenn kein neuer Wert innerhalb dieser Zeit kommt, ist der Wert für evcc `outdated`.
 Wichtig ist, dass hier eine Einheit mit angegeben werden muss, also z.B. `timeout: 30s`
 

src/content/docs/de/features/external-control.mdx

@@ -86,7 +86,7 @@ limit:
   # Rückgabewert: false = nicht begrenzt, true = begrenzt
 ```
 
-Weitere Details zum GPIO-Plugin findest du in der [Plugin-Dokumentation](/de/plugins#gpio).
+Weitere Details zum GPIO-Plugin findest du in der [Plugin-Dokumentation](/de/reference/plugins#gpio).
 
 </TabItem>
 <TabItem label="MQTT">
@@ -249,4 +249,4 @@ Diese Funktion wird weiter ausgebaut und entsprechende Zähler werden in der [Ge
 ## Weiterführende Informationen
 
 - [Lastmanagement](./loadmanagement) - Grundlagen der Lastverteilung
-- [Plugins](../plugins) - Erweiterte Plugin-Konfigurationen
+- [Plugins](/de/reference/plugins) - Erweiterte Plugin-Konfigurationen

src/content/docs/de/index.mdx

@@ -25,7 +25,7 @@ evcc läuft lokal auf einem Raspberry Pi oder NAS - keine Cloud erforderlich.
   - [Wallboxen und schaltbaren Steckdosen](/de/chargers)
   - [Erzeugungsanlagen, Batteriespeichern und Energiemessgeräten (Zähler)](/de/meters)
   - [Fahrzeugen](/de/vehicles)
-- [Plugins](/de/plugins) um nahezu beliebige Wallboxen / Zähler / Fahrzeuge hinzuzufügen: Modbus, HTTP, MQTT, Javascript, WebSockets und Shell Skripte
+- [Plugins](/de/reference/plugins) um nahezu beliebige Wallboxen / Zähler / Fahrzeuge hinzuzufügen: Modbus, HTTP, MQTT, Javascript, WebSockets und Shell Skripte
 - Status [Benachrichtigungen](/de/reference/configuration/messaging) über [Telegram](https://telegram.org), [PushOver](https://pushover.net) und [viele mehr](https://containrrr.dev/shoutrrr/)
 - Datenanalyse mit [InfluxDB](https://www.influxdata.com) und [Grafana](https://grafana.com/grafana/)
 - Stufenlose Regelung der Ladeströme mit unterstützten Wallboxen (z. B. bei smartWB als [OLC](https://board.evse-wifi.de/viewtopic.php?f=16&t=187) bezeichnet)

src/content/docs/de/installation/considerations.mdx

@@ -30,7 +30,7 @@ Letzteres ist meist dann der Fall, wenn die Solaranlage mit einem Speicher ausge
 
 Der Zähler muss sich elektronisch auslesen lassen.
 Schau einfach, mal unter [Geräte > PV, Batterie, Netz, Zähler](/de/meters) nach, ob du deine Geräte findest.
-Wenn nicht, kannst du über [Plugins](/de/plugins) auch selbst eine Integration vornehmen.
+Wenn nicht, kannst du selbst eine Integration als [eigenes Gerät](/de/user-defined-devices) vornehmen.
 
 Eine weitere Voraussetzung für das Automatisieren des Überschussladens ist eine steuerbare Wallbox.
 Die unterstützten Geräte sind unter [Geräte > Wallboxen](/de/chargers) gelistet.

src/content/docs/de/reference/configuration/chargers.mdx

@@ -39,7 +39,7 @@ name: wallbox1
 
 Dies ist der evcc spezifische Wallbox Typ, mit Hilfe dessen mit der Wallbox kommuniziert werden kann. Bekannte Wallboxen könne über den Typ `template` eingebunden werden. Den passenden (Template)Typ findet man unter [Geräte - Wallboxen](/de/chargers).
 
-Für unbekannte Wallboxen (oder aus anderen individuellen Gründen) kann die Standard Implementierung über [Plugins](/de/plugins) genutzt werden.
+Für unbekannte Wallboxen (oder aus anderen individuellen Gründen) kannst du eine [eigene Wallbox](/de/user-defined-devices#charger) definieren.
 
 **Beispiel**:
 

src/content/docs/de/reference/configuration/hems.md

@@ -56,12 +56,12 @@ Gesamtleistungslimit in Watt, das bei aktivem Signal gesetzt wird.
 
 #### `limit`
 
-[Plugin](../../plugins)-Konfiguration zum Auslesen des Schaltkontakts.
+[Plugin](/de/reference/plugins)-Konfiguration zum Auslesen des Schaltkontakts.
 Erwarteter Rückgabewert: `true`/`1` = begrenzt, `false`/`0` = normal.
 
 #### `passthrough`
 
-Optionale [Plugin](../../plugins)-Konfiguration zum Durchreichen des Begrenzungssignals an ein externes System.
+Optionale [Plugin](/de/reference/plugins)-Konfiguration zum Durchreichen des Begrenzungssignals an ein externes System.
 
 #### `interval`
 
@@ -101,7 +101,7 @@ Folgende optionale Parameter können für die EEBus-Kommunikation gesetzt werden
 
 #### `passthrough`
 
-Optionale [Plugin](../../plugins)-Konfiguration zum Durchreichen des Begrenzungssignals an ein externes System.
+Optionale [Plugin](/de/reference/plugins)-Konfiguration zum Durchreichen des Begrenzungssignals an ein externes System.
 
 #### `interval`