evcc-io · naltatis · Jul 17, 2026 · Jul 17, 2026 · Jul 17, 2026 · Jul 17, 2026
diff --git a/AGENTS.md b/AGENTS.md
@@ -202,9 +202,16 @@ Everything else is hand-written:
 ##### Link Formats
 
 - **Locale-prefixed absolute links**: `/en/features/solar-charging` or `/de/features/solar-charging`
-- Astro's router preserves the prefix, so use the locale-prefixed form for clarity
+- **Never use relative links** (`./linux`, `../meters`, `loadpoints#charger`) for pages — the production site (GitHub Pages) serves pages with a trailing slash, so relative links resolve one level too deep and 404. Local dev serves without the trailing slash, so the breakage is invisible locally.
+- Relative paths are fine (and preferred) for **co-located images/assets** — Astro bundles them at build time
 - **Anchors**: `/en/reference/configuration/site#residualpower`
 - **Never include** `.md` or `.mdx` extensions in links
+- The REST API pages are not locale-prefixed: link to `/integrations/rest-api`
+
+##### Validation
+
+- `npm run build` validates all internal links via `starlight-links-validator` and fails on broken links, missing anchors, and relative page links — CI enforces this on every PR
+- Custom routes under `src/pages/[lang]/` (device pages, `external-limit`, `notifications`, `nightly`) plus the openapi and blog index pages are excluded from validation in `astro.config.mjs`; extend that list when adding new custom routes
 
 ##### Best Practices
 

diff --git a/astro.config.mjs b/astro.config.mjs
@@ -7,6 +7,7 @@ import sitemap from "@astrojs/sitemap";
 import starlightBlog from "starlight-blog";
 import starlightLlmsTxt from "starlight-llms-txt";
 import starlightOpenAPI, { openAPISidebarGroups } from "starlight-openapi";
+import starlightLinksValidator from "starlight-links-validator";
 import mermaid from "astro-mermaid";
 import { unified } from "@astrojs/markdown-remark";
 import remarkHeadingId from "remark-heading-id";
@@ -114,6 +115,22 @@ export default defineConfig({
         starlightLlmsTxt({
           exclude: ["**/blog/**"],
         }),
+        starlightLinksValidator({
+          // German pages fall back to English, links to them are valid
+          errorOnFallbackPages: false,
+          // installation guides intentionally link to http://localhost:7070
+          errorOnLocalLinks: false,
+          // device and integration pages are custom routes (src/pages) the validator cannot see
+          exclude: [
+            "/{en,de}/{chargers,meters,vehicles,smartswitches,heating,tariffs,external-limit,notifications,nightly}",
+            "/{en,de}/{chargers,meters,vehicles,smartswitches,heating,tariffs,external-limit,notifications,nightly}/**",
+            "/{en,de}/{chargers,meters,vehicles,smartswitches,heating,tariffs,external-limit,notifications,nightly}#*",
+            // starlight-openapi and starlight-blog routes are not visible to the validator
+            "/integrations/rest-api",
+            "/integrations/rest-api/**",
+            "/{en,de}/blog",
+          ],
+        }),
       ],
       sidebar: [
         {

diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -37,6 +37,7 @@
   "devDependencies": {
     "prettier": "^3.8.1",
     "remark-heading-id": "^1.0.1",
+    "starlight-links-validator": "^0.25.2",
     "typescript": "^6.0.3"
   }
 }
diff --git a/src/content/docs/de/blog/2025/01/20/tesla-api-update.mdx b/src/content/docs/de/blog/2025/01/20/tesla-api-update.mdx
@@ -23,7 +23,7 @@ Dieser Beitrag wurde überarbeitet.
 
 ## Tesla Fleet API wird ab Februar kostenpflichtig
 
-Vor einem Jahr haben wir die [Tesla Fleet API](/de/blog/2024/02/01/v0.124-new-tesla-api) in evcc integriert.
+Vor einem Jahr haben wir die [Tesla Fleet API](/de/blog/2024/02/01/v0124-new-tesla-api) in evcc integriert.
 Tesla war damit der erste Hersteller, der eine offizielle und vor allem offene API für die Kommunikation mit seinen Fahrzeugen bereitgestellt hat.
 
 Tesla hatte bereits bei der Einführung angekündigt, dass diese Schnittstelle später kostenpflichtig werden würde.
@@ -49,6 +49,8 @@ Dort kannst du dir mit deinem Developer Account passende **Access- und Refresh-T
 
 ## Was ist zu tun?
 
+<a id="vehicle"></a>
+
 ### Für Tesla-Fahrer
 
 Für die Einrichtung in evcc benötigst du drei Informationen:

diff --git a/src/content/docs/de/blog/2025/07/30/highlights-config-ui-feedin-ai.mdx b/src/content/docs/de/blog/2025/07/30/highlights-config-ui-feedin-ai.mdx
@@ -80,6 +80,8 @@ Damit kannst du beispielsweise weiterhin den Großteil preisoptimiert laden, das
 
 Mehr Details dazu findest du in der [Dokumentation](/de/features/plans#spätes-laden).
 
+<a id="config-ui"></a>
+
 ## Konfiguration via Browser
 
 Beim Thema Ersteinrichtung via Browser geht es mit großen Schritten voran.

diff --git a/src/content/docs/de/blog/2026/01/01/highlights-browser-config-ready.mdx b/src/content/docs/de/blog/2026/01/01/highlights-browser-config-ready.mdx
@@ -109,6 +109,8 @@ Die Einstellungen werden pro Browser gespeichert und ermöglichen eine individue
 
 ![Ladepunkte sortieren](./loadpoint-sort.webp)
 
+<a id="sponsoring"></a>
+
 ## Sponsoring: Neue Preise
 
 Wir lieben Open Source und sind überzeugt davon, dass das im Projekt angesammelte, offene Wissen ein großer Boost für die Energiewende ist.

diff --git a/src/content/docs/de/faq.mdx b/src/content/docs/de/faq.mdx
@@ -18,7 +18,9 @@ Die **Konfigurationsdatei** (`evcc.yaml`) ist die traditionelle Methode und wird
 **Wichtig**: Einige neuere Features sind ausschließlich über die Weboberfläche verfügbar.
 Beide Methoden können auch parallel genutzt werden.
 
-Mehr Informationen findest du unter [Einrichtung](./installation/configuration).
+Mehr Informationen findest du unter [Einrichtung](/de/installation/configuration).
+
+<a id="ui-migration"></a>
 
 ### Ich habe eine evcc.yaml Konfiguration. Wie migriere ich zur Weboberfläche?
 
@@ -60,7 +62,7 @@ Der Netzzähler ist das Kernstück für evcc und sollte, wenn möglich, eingebun
 Es ist jedoch ebenso möglich, sonnengeführtes Laden ausschließlich auf der Grundlage der PV-Leistung zu betreiben.
 In dieser Konstellation kann nicht mit PV-Überschuss geladen werden, da der dazu notwendige Messpunkt (Zähler) fehlt.
 Stattdessen wird in den Lademodi **PV** und **Min+PV** mit der PV-Erzeugungsleistung gearbeitet.
-Als Optimierung kann über die Einstellung [`residualPower`](./reference/configuration/site#residualpower) ein typischer mittlerer Hausverbrauch angegeben werden.
+Als Optimierung kann über die Einstellung [`residualPower`](/de/reference/configuration/site#residualpower) ein typischer mittlerer Hausverbrauch angegeben werden.
 
 **Beispiel**:
 
@@ -73,7 +75,7 @@ site:
 
 Hier gibt es verschiedene Nutzungsmöglichkeiten.
 Notwendig ist auf jeden Fall ein auslesbarer Netzzähler.
-Bei einem [variablen Stromtarif](./features/dynamic-prices) (z. B. Nachtstrom, Tibber, Awattar) ist automatisches preisabhängiges Laden möglich.
+Bei einem [variablen Stromtarif](/de/features/dynamic-prices) (z. B. Nachtstrom, Tibber, Awattar) ist automatisches preisabhängiges Laden möglich.
 Ansonsten kann man evcc zur Fernsteuerung (start/stop) der Wallbox nutzen.
 Darüber hinaus kann man die Ladung einer Fahrzeugbatterie auf einen bestimmten Ladestand (SoC) begrenzen. In diesem Fall ist es aber zwingend notwendig, dass das Fahrzeug in die Konfiguration mit aufgenommen wird.
 
@@ -173,7 +175,7 @@ Es ist aber mehr ein Entwickler- und Supporttool zu Diagnosezwecken und erkennt
 evcc erwartet nach einem Intervallzyklus bereits den neuen korrekten Status.
 Wenn manche Geräte etwas zu langsam auf Anweisungen reagieren, kommt es kurzzeitig zu einem undefinierten Zustand, der mit diesen Fehlern quittiert wird.
 Sollten ansonsten keine Probleme auftreten, kann die Meldung ignoriert werden.
-Abhilfe schafft ein größeres [`interval`](./reference/configuration/interval).
+Abhilfe schafft ein größeres [`interval`](/de/reference/configuration/interval).
 
 ### connection refused
 
@@ -267,6 +269,8 @@ Das ist leider eine Einschränkung der Herstellerschnittstelle. PSA liefert vera
 
 ## Passwort
 
+<a id="password-reset"></a>
+
 ### Ich habe mein Passwort vergessen. Wie kann ich es ändern?
 
 Das Passwort wird verschlüsselt gespeichert, daher kann es nicht ausgelesen werden.

diff --git a/src/content/docs/de/features/battery.mdx b/src/content/docs/de/features/battery.mdx
@@ -139,6 +139,8 @@ Dies kann durch den Schnell-Modus, smartes Netzladen, Ladeplanung oder Mindestla
 Der Sperrzustand gilt für den Zeitraum des Schnellladens.
 In dieser Zeit wird die Hausbatterie nicht entladen.
 
+<a id="gridcharge"></a>
+
 ### Netzladen
 
 Szenario: Du hast einen dynamischen Stromtarif und möchtest deinen Hausspeicher nachts mit günstigem Strom laden.
@@ -149,7 +151,7 @@ Beispielsweise, weil der am Tag erzeugte Überschuss nicht ausreicht.
   caption="Hausbatterie Dialog für Netzladen"
 />
 
-Analog zum [CO₂-](./co2) und [preisoptimierten Laden](./dynamic-prices) beim Fahrzeug, kannst du auch die Hausbatterie mit günstigem Strom laden.
+Analog zum [CO₂-](/de/features/co2) und [preisoptimierten Laden](/de/features/dynamic-prices) beim Fahrzeug, kannst du auch die Hausbatterie mit günstigem Strom laden.
 Wenn dein Wechselrichter diese Funktion unterstützt, erscheint im "Hausbatterie" Dialog der Reiter "Netzladen".
 Hier kannst du ein Limit anlegen.
 Unterschreitet der aktuelle Strompreis dieses Limit, wird die Hausbatterie für diese Zeit aus dem Netz geladen und gleichzeitig vor Entladung gesperrt.
@@ -161,7 +163,7 @@ Nach Ende der Leistungsreduzierung wird das Netzladen automatisch fortgesetzt.
 :::
 
 :::caution[Lastmanagement]
-Netzladen der Hausbatterie wird vom [Lastmanagement](./loadmanagement) nicht berücksichtigt.
+Netzladen der Hausbatterie wird vom [Lastmanagement](/de/features/loadmanagement) nicht berücksichtigt.
 Wenn z. B. die Hausbatterie 9 kW aus dem Netz zieht, fließt dieser Verbrauch nicht in die Lastmanagement-Berechnung ein.
 Dies gilt nicht für § 14a Reduzierungssignale – dort wird das Netzladen wie oben beschrieben automatisch pausiert.
 :::

diff --git a/src/content/docs/de/features/co2.mdx b/src/content/docs/de/features/co2.mdx
@@ -40,13 +40,13 @@ Jeder Balken repräsentiert eine Stunde.
 
 Dieses Limit gilt im **PV-Modus** des aktuellen Ladepunktes.
 Mit Klick auf "überall anwenden" wird das Limit für alle Ladepunkte übernommen.
-Zusätzlich zum [PV-Überschussladen](./solar-charging) wird nun in den Stunden mit niedriger CO₂-Emission (grüne Balken) schnelles Laden aktiviert.
+Zusätzlich zum [PV-Überschussladen](/de/features/solar-charging) wird nun in den Stunden mit niedriger CO₂-Emission (grüne Balken) schnelles Laden aktiviert.
 
 Diese Einstellung ist sinnvoll, um bspw. in den Wintermonaten weiterhin einen vollgeladenen Akku zu haben, und dabei das Stromnetz zu entlasten.
 
 ## Ladeplanung
 
-Durch die Nutzung von [Ladeplänen](./plans) kannst du das CO₂-optimierte Laden noch genauer regeln.
+Durch die Nutzung von [Ladeplänen](/de/features/plans) kannst du das CO₂-optimierte Laden noch genauer regeln.
 Du musst lediglich deine Energiemenge (kWh) bzw. deinen Zielladestand (%) und die gewünschte Abfahrtszeit angeben.
 Ist eine CO₂-Datenquelle konfiguriert, wählt der Planungsalgorithmus automatisch die Stunden mit der niedrigsten CO₂-Emission aus.
 
@@ -56,7 +56,7 @@ Ist eine CO₂-Datenquelle konfiguriert, wählt der Planungsalgorithmus automati
 />
 
 :::note[Hinweis]
-Hast du einen [dynamischen Stromtarif](./dynamic-prices) konfiguriert, wird dieser bevorzugt.
-Die CO₂-Daten werden weiterhin an deinen [Ladevorgängen](./sessions) erfasst.
+Hast du einen [dynamischen Stromtarif](/de/features/dynamic-prices) konfiguriert, wird dieser bevorzugt.
+Die CO₂-Daten werden weiterhin an deinen [Ladevorgängen](/de/features/sessions) erfasst.
 Der Planungsalgorithmus und die "Günstiges Netzladen"-Funktion optimieren nun jedoch auf Preis anstatt auf CO₂.
 :::