From: Kai Moritz <kai.milan.moritz@googlemail.com>
Date: Sat, 6 Jun 2026 11:21:04 +0000 (+0000)
Subject: Add README.md with Astro dev/build quickstart and project structure
X-Git-Url: https://juplo.de/gitweb/?a=commitdiff_plain;h=9ef5d3f60fc4f26a358706324e7d0bb0a5ea4b52;p=website

Add README.md with Astro dev/build quickstart and project structure

Documents how to start the dev server, run the static build, and
explains project-specific conventions (CSS pre-compilation, .html
page routing, Content Collections glob loader).

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---

diff --git a/README.md b/README.md
new file mode 100644
index 00000000..65ef1fc5
--- /dev/null
+++ b/README.md
@@ -0,0 +1,103 @@
+# juplo.de — Astro-Website
+
+Dieses Repository enthält den Astro-Build der juplo.de-Website auf dem Branch `content--via-astro`.
+
+## Voraussetzungen
+
+- Node.js ≥ 22.12.0
+- npm
+
+## Entwicklungsserver starten
+
+```bash
+npm run dev
+```
+
+Der Entwicklungsserver läuft dann unter `http://localhost:4321/`.
+
+**Was dabei passiert:** Vor dem Start werden automatisch die CSS-Dateien aus den SCSS-Quellen gebaut (`npm run predev`). Änderungen an `.astro`- und `.ts`-Dateien werden sofort im Browser reflektiert (Hot Module Replacement). SCSS-Änderungen hingegen erfordern ein erneutes `npm run dev` oder ein manuelles `npm run build:css`.
+
+## Statischen Build erzeugen
+
+```bash
+npm run build
+```
+
+Das Ergebnis liegt in `dist/`. Vor dem Build werden ebenfalls automatisch die CSS-Dateien aktualisiert.
+
+```bash
+npm run preview
+```
+
+Startet einen lokalen Vorschau-Server für den fertigen Build unter `http://localhost:4321/`.
+
+## Nur CSS bauen (ohne Astro)
+
+```bash
+npm run build:css
+```
+
+Kompiliert `src/styles/screen.scss` und `src/styles/print.scss` nach `public/css/` und kopiert `resurrection.css`. Das ist nützlich, wenn nur SCSS-Änderungen getestet werden sollen.
+
+## Projektstruktur
+
+```
+src/
+  content/
+    blog/              ← Blog-Artikel als Markdown-Dateien
+  content.config.ts    ← Astro Content Collections Config
+  layouts/
+    BaseLayout.astro   ← Basis-HTML-Gerüst (Header, Footer, Slots)
+  components/
+    BlogNav.astro      ← Navigation für Blog-Seiten (Submenu mit Archive/Categories/Tags)
+    Breadcrumb.astro   ← Breadcrumb-Komponente
+  pages/
+    index.astro        ← Startseite (/)
+    about.html.astro   ← About-Seite (/about.html)
+    impressum.html.astro
+    datenschutz.html.astro
+    blog/
+      index.astro      ← Blog-Übersicht (/blog/)
+      archive/
+        index.astro    ← Archiv-Übersicht (/blog/archive/)
+        [year].astro   ← Jahres-Archiv (/blog/archive/YYYY/)
+      categories/
+        index.astro    ← Kategorie-Index (/blog/categories/)
+      tags/
+        index.astro    ← Tag-Index (/blog/tags/)
+    categories/
+      [term].astro     ← Kategorie-Detailseite (/categories/TERM/)
+    tags/
+      [term].astro     ← Tag-Detailseite (/tags/TERM/)
+    [slug].astro       ← Einzelne Blog-Artikel
+  styles/
+    screen.scss        ← SCSS-Hauptdatei (importiert partials)
+    print.scss
+    resurrection.css   ← Alternatives Layout (kopiert direkt)
+public/
+  css/                 ← Compiliertes CSS (git-versioniert, wird von build:css aktualisiert)
+  js/                  ← JavaScript-Dateien
+  img/, fonts/, …      ← Statische Assets
+```
+
+## Wichtige Eigenheiten
+
+### CSS wird separat kompiliert
+
+Astro verarbeitet das SCSS nicht selbst — der `sass`-Compiler läuft als separater Schritt via `build:css`. Das kompilierte CSS liegt in `public/css/` und ist **eingecheckt**. Das ist absichtlich so: Die CSS-Ausgabe gehört zur Site und soll nicht bei jedem Build neu erzeugt werden müssen.
+
+### Content Collections mit glob-Loader
+
+Blog-Artikel liegen in `src/content/blog/` und werden über Astros [Content Collections](https://docs.astro.build/en/guides/content-collections/) mit glob-Loader eingebunden. Der Loader ist in `src/content.config.ts` konfiguriert. Jeder Artikel kann im Frontmatter ein `url`-Feld setzen, um die kanonische URL zu überschreiben (Kompatibilität mit alten Hugo-URLs).
+
+### `.html`-Endungen für Standalone-Seiten
+
+Seiten wie About, Impressum und Datenschutz haben `.html`-Endungen in der URL (`/about.html`). Astro erzeugt diese korrekt, wenn die Datei als `about.html.astro` benannt ist.
+
+### Kein `astro check` im Build
+
+`astro check` (TypeScript-Typenprüfung) ist nicht im Build-Script eingebunden. Bei Bedarf manuell ausführen:
+
+```bash
+npx astro check
+```