Templates: add caveats (#1083)

Author: naltatis

src/components/DeviceDetailLayout.astro

@@ -5,7 +5,7 @@ import DeviceFeatures from "@components/DeviceFeatures.astro";
 import DeviceParams from "@components/DeviceParams.astro";
 import SponsorshipBadge from "@components/SponsorshipBadge.astro";
 import NightlyIcon from "@components/NightlyIcon.astro";
-import { renderMarkdown, nightlyPageHead } from "@utils/devices";
+import { renderMarkdown, renderMarkdownInline, nightlyPageHead } from "@utils/devices";
 import type { Channel } from "@utils/devices";
 import { deviceIconSvg } from "@utils/deviceIcon";
 
@@ -70,6 +70,8 @@ const t =
         sponsorTitle: "Sponsortoken erforderlich",
         sponsorBody:
           "Dieses Gerät steht Unterstützern des Projekts zur Verfügung. Mehr zu unserem [Sponsoring-Modell](/de/sponsorship).",
+        caveatsTitle: "Bekannte Einschränkungen",
+        caveatsMore: "Mehr Details",
       }
     : {
         config: "Configuration example for evcc.yaml",
@@ -80,6 +82,8 @@ const t =
         sponsorTitle: "Sponsor token required",
         sponsorBody:
           "This device is available to sponsors of the project. Read more about our [sponsorship model](/en/sponsorship).",
+        caveatsTitle: "Known limitations",
+        caveatsMore: "More details",
       };
 
 const nightlyBannerText =
@@ -147,6 +151,29 @@ const frontmatter = {
       )
     }
 
+    {
+      entry.data.caveats?.length > 0 && (
+        <aside
+          class="starlight-aside starlight-aside--note device-caveats"
+          aria-label={t.caveatsTitle}
+        >
+          <p class="starlight-aside__title">🐜 {t.caveatsTitle}</p>
+          <div class="starlight-aside__content">
+            {entry.data.caveats.map((c: { description?: string; link?: string }) => (
+              <p
+                set:html={
+                  renderMarkdownInline(c.description) +
+                  (c.link
+                    ? ` <a href="${c.link}" target="_blank" rel="noopener noreferrer">${t.caveatsMore}</a>`
+                    : "")
+                }
+              />
+            ))}
+          </div>
+        </aside>
+      )
+    }
+
     <div class="params-block">
       <div class="params-header">
         <h2 class="params-title">{t.params}</h2>
@@ -177,6 +204,15 @@ const frontmatter = {
 </StarlightPage>
 
 <style>
+  /* Tighten spacing between individual caveats so it matches the
+     title-to-content gap rather than the default paragraph margin. */
+  .device-caveats :global(.starlight-aside__content p) {
+    margin: 0;
+  }
+  .device-caveats :global(.starlight-aside__content p + p) {
+    margin-top: 0.35rem;
+  }
+
   .params-block {
     clear: right;
   }

src/content.config.ts

@@ -59,13 +59,19 @@ const paramSchema = z
   })
   .loose();
 
+const caveatSchema = z.object({
+  description: z.string().optional(),
+  link: z.string().optional(),
+});
+
 const deviceSchema = z.object({
   template: z.string().optional(),
   product: productSchema,
   description: z.string().optional(),
   render: z.array(renderSchema),
   capabilities: z.array(z.string()).optional(),
   requirements: z.array(z.string()).optional(),
+  caveats: z.array(caveatSchema).optional(),
   countries: z.array(z.string()).optional(),
   params: z.array(paramSchema).optional(),
 });

src/utils/devices.ts

@@ -116,6 +116,7 @@ export interface DeviceEntry {
     }>;
     capabilities?: string[];
     requirements?: string[];
+    caveats?: Array<{ description?: string; link?: string }>;
     countries?: string[];
   };
 }

templates/nightly/de/charger/alfen-eve.yaml

@@ -7,6 +7,9 @@ capabilities: ["mA", "1p3p", "meter", "dim"]
 requirements: ["sponsorship"]
 description: |
   Die "Active load balancing" Lizenz wird benötigt um die Wallbox via Modbus extern zu steuern. In den Einstellungen muss "Active Load Balancing" aktiviert und "Energy Management System" als Data Source ausgewählt werden. Es wird empfohlen "ValidityTime" (Menu "TCP/IP EMS") auf 300s einzustellen. Falls die "Double"-Box verwendet wird müssen beide Ladepunkte getrennt voneinander hinzugefügt werden. Der erste Port (oder einzelne Port) ist unter ID 1 zugänglich, der zweite unter ID 2.
+caveats:
+  - description: |
+      Phasenumschaltung synchronisiert sich nicht immer zuverlässig.
 render:
   - default: |
       type: template

templates/nightly/de/charger/amperfied-wallbox-connect-solar.yaml

@@ -5,6 +5,9 @@ product:
   description: Wallbox connect.solar
 capabilities: ["mA", "rfid", "1p3p", "meter", "dim"]
 requirements: ["sponsorship"]
+caveats:
+  - description: |
+      Automatische Phasenumschaltung (1P/3P) ist unzuverlässig und kann fehlschlagen.
 render:
   - default: |
       type: template

templates/nightly/de/charger/ampure-unite.yaml

@@ -7,6 +7,10 @@ capabilities: ["rfid", "1p3p", "meter", "dim"]
 requirements: ["sponsorship"]
 description: |
   1P3P erfordert Firmware 3.187.0 oder neuer, RFID erfordert 3.156.0 oder neuer.
+caveats:
+  - description: |
+      Phasenumschaltung deaktiviert sich gelegentlich von selbst.
+    link: https://github.com/evcc-io/evcc/issues/21708
 render:
   - default: |
       type: template

templates/nightly/de/charger/audi-wallbox-plus.yaml

@@ -13,6 +13,10 @@ description: |
 
   Hinweis: Wenn du deiner Wallbox nachträglich einen Energiezähler hinzugefügt hast, nutze bitte die Pro bzw. Connected+ Integration.
 
+caveats:
+  - description: |
+      Viele bekannte EEBUS-Firmware-Fehler, die der Hersteller nicht behebt: Ladewerte fehlen oft oder sind veraltet und die Verbindung bricht häufig ab. Ein externer Zähler ist erforderlich.
+    link: https://github.com/evcc-io/evcc/discussions/15367
 render:
   - default: |
       type: template

templates/nightly/de/charger/audi-wallbox-pro.yaml

@@ -11,6 +11,10 @@ description: |
 
   Wichtig: Die möglichst reibungslose Funktionalität ist aufgrund von Software-Fehlern in der Wallbox nur mit einem externen Energiezähler und ohne Stromwandlerspulen möglich! Eine LAN Anbindung wird sehr empfohlen.
 
+caveats:
+  - description: |
+      Viele bekannte EEBUS-Firmware-Fehler, die der Hersteller nicht behebt: Ladewerte können unzuverlässig sein und die Verbindung bricht häufig ab.
+    link: https://github.com/evcc-io/evcc/discussions/15367
 render:
   - default: |
       type: template

templates/nightly/de/charger/cupra-charger-connect.yaml

@@ -13,6 +13,10 @@ description: |
 
   Hinweis: Wenn du deiner Wallbox nachträglich einen Energiezähler hinzugefügt hast, nutze bitte die Pro bzw. Connected+ Integration.
 
+caveats:
+  - description: |
+      Viele bekannte EEBUS-Firmware-Fehler, die der Hersteller nicht behebt: Ladewerte fehlen oft oder sind veraltet und die Verbindung bricht häufig ab. Ein externer Zähler ist erforderlich.
+    link: https://github.com/evcc-io/evcc/discussions/15367
 render:
   - default: |
       type: template

templates/nightly/de/charger/cupra-charger-pro.yaml

@@ -11,6 +11,10 @@ description: |
 
   Wichtig: Die möglichst reibungslose Funktionalität ist aufgrund von Software-Fehlern in der Wallbox nur mit einem externen Energiezähler und ohne Stromwandlerspulen möglich! Eine LAN Anbindung wird sehr empfohlen.
 
+caveats:
+  - description: |
+      Viele bekannte EEBUS-Firmware-Fehler, die der Hersteller nicht behebt: Ladewerte können unzuverlässig sein und die Verbindung bricht häufig ab.
+    link: https://github.com/evcc-io/evcc/discussions/15367
 render:
   - default: |
       type: template