Website mit Astro & Starlight

Ausgangslage

Diese Website lief ursprünglich als WordPress-Installation auf einem eigenen Server. WordPress war für einen reinen Dokumentations-Blog deutlich überdimensioniert: PHP, MySQL-Datenbank, regelmäßige Plugin-Updates, Sicherheitspatches und ein wachsender Ressourcenverbrauch — alles für Seiten, die sich selten ändern.

Der Wunsch: Eine schnelle, wartungsarme, statische Website, die sich wie eine technische Dokumentation anfühlt und mit Markdown geschrieben werden kann.

Tech Stack

Astro

Astro ist ein modernes Static-Site-Framework. Im Gegensatz zu Next.js oder Nuxt liefert Astro standardmäßig kein JavaScript an den Browser aus — nur reines HTML und CSS. JavaScript wird nur dort geladen, wo es explizit benötigt wird (z.B. für interaktive Charts).

Vorteile gegenüber WordPress:

• Kein PHP, keine Datenbank, kein Admin-Backend
• Seiten sind statisches HTML — extrem schnell
• Versionierung mit Git statt Datenbank-Backups
• Markdown als Inhaltsformat — portabel und zukunftssicher

Starlight

Starlight ist das offizielle Dokumentations-Theme für Astro. Es bietet out-of-the-box:

• Sidebar-Navigation — konfigurierbar und auto-generiert aus Verzeichnisstruktur
• Suchfunktion — via Pagefind, vollständig clientseitig ohne Server
• Dark/Light Mode — automatisch oder manuell umschaltbar
• Responsive Design — optimiert für Desktop und Mobil
• i18n-Support — mehrsprachige Seiten möglich
• Komponentenbibliothek — Cards, Tabs, Admonitions, LinkCards

Starlight Blog Plugin

Für Blog-Funktionalität (chronologische Posts, Tags, RSS-Feed) wird das starlight-blog Plugin eingesetzt. Blog-Posts liegen im gleichen Content-Verzeichnis und nutzen zusätzliche Frontmatter-Felder wie date, tags und excerpt.

Chart.js

Für interaktive Diagramme (PV-Statistik) wird Chart.js verwendet. Die Charts werden clientseitig gerendert und holen Daten von einer lokalen API — funktioniert nur im Heimnetz, mit Fallback-Meldung für externe Besucher.

Projektstruktur

raunet/
├── astro.config.mjs       ← Konfiguration (Sidebar, Plugins, Locale)
├── package.json            ← Dependencies
├── src/
│   ├── content/
│   │   ├── config.ts       ← Content Schema
│   │   └── docs/           ← Alle Inhaltsseiten
│   │       ├── index.mdx   ← Homepage (Splash)
│   │       ├── energie/    ← Sektion Energie
│   │       ├── smarthome/  ← Sektion SmartHome
│   │       ├── eedc/       ← Sektion EEDC
│   │       ├── blog/       ← Blog-Posts
│   │       └── ...
│   ├── components/         ← Eigene Astro-Komponenten
│   ├── pages/              ← Standalone-Seiten (Impressum, Datenschutz)
│   └── styles/
│       └── custom.css      ← Eigene CSS-Anpassungen
├── public/
│   └── images/             ← Bilder (werden 1:1 kopiert)
├── nginx/
│   └── raunet.gernot-rau.de.conf  ← Nginx-Konfiguration
└── dist/                   ← Build-Output (statisches HTML)

Inhalte schreiben

Markdown und MDX

Normale Seiten werden als .md-Dateien geschrieben. Für Seiten mit interaktiven Komponenten (Cards, Charts) wird .mdx verwendet — Markdown mit eingebetteten Astro-Komponenten:

---
title: "Meine Seite"
sidebar:
  order: 1
---

import { Card, CardGrid } from '@astrojs/starlight/components';

Normaler Markdown-Text hier.

<CardGrid>
  <Card title="Feature A" icon="sun">
    Beschreibung
  </Card>
</CardGrid>

:::note
Admonitions funktionieren wie in GitHub Flavored Markdown.
:::

Frontmatter

Jede Seite beginnt mit YAML-Frontmatter:

---
title: "Seitentitel"          # Pflicht
date: 2026-03-01              # Optional, für Blog-Posts
sidebar:
  order: 1                    # Reihenfolge in der Sidebar
tags: [Tag1, Tag2]            # Nur für Blog-Posts
excerpt: Kurzbeschreibung     # Nur für Blog-Posts
---

Sidebar-Konfiguration

Die Navigation wird in astro.config.mjs definiert — entweder manuell mit slug-Verweisen oder automatisch aus einem Verzeichnis:

sidebar: [
  {
    label: 'SmartHome',
    autogenerate: { directory: 'smarthome' },  // Automatisch
  },
  {
    label: 'EEDC',
    items: [                                    // Manuell
      { label: 'Überblick', slug: 'eedc' },
      { label: 'Features', slug: 'eedc/features' },
    ],
  },
],

Bilder

Bilder werden in public/images/ abgelegt und mit normalem Markdown referenziert:

![Beschreibung](/images/eedc/cockpit_uebersicht_neu.png)

Build und Deployment

Lokaler Build

# Abhängigkeiten installieren (einmalig)
npm install

# Entwicklungsserver mit Hot-Reload
npx astro dev --host 0.0.0.0

# Produktions-Build
npx astro build

Der Build erzeugt statisches HTML in dist/. Ein vollständiger Build dauert ca. 4 Sekunden für ~40 Seiten.

Nginx-Konfiguration

Die Site wird direkt von nginx als statische Dateien ausgeliefert — kein Node.js-Prozess im Hintergrund nötig:

server {
  listen 80;
  server_name raunet.gernot-rau.de;

  root /home/gernot/raunet/dist;
  index index.html;

  # Astro erzeugt saubere URLs: /slug/index.html
  location / {
    try_files $uri $uri/ $uri/index.html =404;
  }

  # Hashed Assets: 1 Jahr Cache
  location /_astro/ {
    expires 365d;
    add_header Cache-Control "public, immutable";
  }
}

SSL-Terminierung übernimmt ein vorgelagerter Nginx Proxy Manager.

Deployment-Workflow

# 1. Änderungen schreiben (Markdown bearbeiten)
# 2. Lokal testen
npx astro dev --host 0.0.0.0

# 3. Bauen
npx astro build

# 4. Live — nginx liefert aus dist/ aus
# Kein Neustart nötig, da statische Dateien

# 5. Optional: Git commit + push
git add -A && git commit -m "Neue Inhalte"
git push

Da nginx direkt auf dist/ zeigt, ist jeder Build sofort live.

WordPress-Migration

Redirects

Alte WordPress-URLs werden per nginx 301-Redirect auf die neuen Astro-Pfade umgeleitet:

location = /2023/02/fhem-smarthome-einstieg/ {
  return 301 /smarthome/01-einstieg/;
}

So bleiben bestehende Links aus Suchmaschinen und Bookmarks funktionsfähig.

WordPress-Artefakte bereinigen

Beim Migrieren der Inhalte mussten folgende WordPress-spezifische Elemente entfernt werden:

• TOC-Blöcke — WordPress-generierte Inhaltsverzeichnisse mit absoluten URLs
• Shortcodes — [smartslider3 slider="X"] und ähnliche Plugin-Codes
• Alte Links — absolute URLs auf raunet.gernot-rau.de/2023/... zu relativen Pfaden
• Plugin-Seiten — Impressum und Datenschutz waren nur Shortcodes ([imprint])

WordPress abschalten

Alte WordPress-Pfade liefern 410 Gone zurück:

location ~ ^/wp-(admin|login|content|includes|json) {
  return 410;
}

Besonderheiten und Tipps

Kein JavaScript = Schnell

Standardmäßig liefert Astro/Starlight null Bytes JavaScript aus (abgesehen von der Suchfunktion). Das bedeutet: Seiten laden in unter 100ms, auch auf langsamen Verbindungen.

Lokale API-Anbindung

Für interaktive Inhalte (PV-Charts, Energiefluss) werden eigene Astro-Komponenten (.astro) erstellt, die clientseitig per fetch() Daten von lokalen APIs holen. Da diese APIs nur im Heimnetz erreichbar sind, zeigen die Komponenten externen Besuchern eine Fallback-Meldung.

Pagefind-Suche

Starlight integriert Pagefind — eine clientseitige Volltextsuche, die beim Build einen Index erzeugt. Keine Server-Komponente nötig, funktioniert komplett im Browser.

Git als Backup

Da alle Inhalte Markdown-Dateien sind, ist das Git-Repository gleichzeitig das Backup. Kein Datenbank-Dump, kein Plugin-Export — git clone reicht, um die komplette Website wiederherzustellen.

Empfohlene Software

Zweck	Tool	Anmerkung
Framework	Astro	Statisch, schnell, Markdown-first
Theme	Starlight	Doku-Theme mit Sidebar, Suche, Dark Mode
Blog	starlight-blog	Blog-Plugin für Starlight
Charts	Chart.js	Leichtgewichtige interaktive Diagramme
Webserver	nginx	Statische Auslieferung, Caching, Redirects
SSL	Nginx Proxy Manager	Let’s Encrypt mit Web-UI
Editor	VS Code	Mit Astro-Extension für Syntax-Highlighting
Versionierung	Git + GitHub	Backup und Zusammenarbeit
KI-Assistent	Claude Code	CLI-Tool für Code-Generierung und Migration