From d43f3c4b28825d3b5a6643330ca7a3d36e300374 Mon Sep 17 00:00:00 2001 From: Kai Moritz Date: Sat, 6 Jun 2026 13:23:46 +0000 Subject: [PATCH] =?utf8?q?CLAUDE.md:=20Fehlende=20Architektur-Entscheidung?= =?utf8?q?en=20aus=20Steps=209/10/11=20erg=C3=A4nzt?= MIME-Version: 1.0 Content-Type: text/plain; charset=utf8 Content-Transfer-Encoding: 8bit - CSS-Abschnitt: Referenz auf entferntes themes/hugo-juplo korrigiert (SCSS-Quellen liegen jetzt in src/styles/) - Standard-Entscheidungen: public/, RSS via @astrojs/rss ergänzt - Eigene Entscheidungen: RSS-Routing-Struktur, src/lib/posts.ts, SEO/OG-Tags in BaseLayout, Hugo-Cleanup-Umfang dokumentiert Co-Authored-By: Claude Sonnet 4.6 --- CLAUDE.md | 59 ++++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 58 insertions(+), 1 deletion(-) diff --git a/CLAUDE.md b/CLAUDE.md index 69a0c795..9c6797fa 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -134,6 +134,14 @@ Quelle: https://docs.astro.build/en/basics/layouts/ Alle `.astro`-Dateien nutzen TypeScript im `---`-Frontmatter. Astro kompiliert das automatisch, ohne separate Build-Konfiguration. Quelle: https://docs.astro.build/en/guides/typescript/ +**`public/` als Verzeichnis für statische Assets** +Statische Dateien (CSS, JS, Bilder, Fonts) liegen in `public/` und werden 1:1 ins Build-Verzeichnis kopiert. Hugo nannte dieses Verzeichnis `static/` — in Astro ist `public/` der Standard. Die Dateien wurden bei der Migration entsprechend verschoben. +Quelle: https://docs.astro.build/en/basics/project-structure/#public + +**RSS-Feeds via `@astrojs/rss`** +RSS-Feeds werden mit dem offiziellen Astro-Integration-Paket `@astrojs/rss` erzeugt. Jede Feed-Datei ist eine TypeScript-API-Route (`.ts`-Endung statt `.astro`), die eine `GET`-Funktion exportiert. +Quelle: https://docs.astro.build/en/guides/rss/ + --- ### Eigene Entscheidungen (nicht Astro-vorgegeben) @@ -142,7 +150,7 @@ Quelle: https://docs.astro.build/en/guides/typescript/ **Was:** SCSS wird über einen separaten `sass`-CLI-Aufruf kompiliert (`npm run build:css`), nicht über Astros eingebaute SCSS/Vite-Integration. Das kompilierte CSS landet in `public/css/` und ist im Git eingecheckt. -**Warum:** Das SCSS stammt aus dem Hugo-Theme-Repository (`themes/hugo-juplo`). Eine Integration in Astros Asset-Pipeline hätte entweder Copy-paste oder komplexe Symlink-Logik erfordert. Der separate Build-Schritt hält die SCSS-Quellen im Theme-Repo und das kompilierte Ergebnis im Website-Repo — analog zur Hugo-Situation, wo das Theme die SCSS-Quellen besitzt und der Build das CSS erzeugt. Der `prebuild`/`predev`-Hook in `package.json` stellt sicher, dass CSS immer aktuell ist. +**Warum:** Das SCSS stammt ursprünglich aus dem Hugo-Theme-Repository (`themes/hugo-juplo`), das mit der Astro-Migration entfernt wurde. Die SCSS-Quellen liegen jetzt in `src/styles/` und sind authoritative Kopie im Website-Repo. Eine Integration in Astros Asset-Pipeline (Vite/PostCSS) war möglich, wurde aber nicht gewählt, um das bewährte SCSS-Build-Setup unverändert zu übernehmen. Der separate Build-Schritt (`sass src/styles/screen.scss public/css/screen.css` etc.) ist einfacher als eine Vite-Plugin-Konfiguration. Der `prebuild`/`predev`-Hook in `package.json` stellt sicher, dass CSS immer aktuell ist. **Konsequenz:** SCSS-Änderungen erfordern `npm run build:css` oder einen Dev-Server-Neustart. HMR funktioniert für SCSS nicht automatisch. @@ -209,3 +217,52 @@ Quelle: https://docs.astro.build/en/guides/typescript/ **Warum:** Hugo zeigt auf Standalone-Seiten eine vollständige Site-Navigation (Blog-Baum + Projects-Baum + About-Baum). Die Implementierung dafür würde eine `SiteNav`-Komponente erfordern, die alle Sektionen kennt — inklusive der Projects-Seiten mit deren `current`-Flag-Logik. Das ist deutlich aufwendiger als `BlogNav` und wurde für die Migration zurückgestellt. **Zukünftige Aufgabe:** Eine `SiteNav.astro`-Komponente, die alle Hauptsektionen rendert und die `menu/tree.html`-Logik für Projects (only show `current: true` pages unless on path) repliziert. + +--- + +#### RSS-Feed-Routing: Verzeichnisstruktur für korrekte URLs + +**Was:** RSS-Feed-Routen für Taxonomie-Terms und Jahres-Archive liegen in Unterverzeichnissen: `src/pages/categories/[term]/index.xml.ts` statt `src/pages/categories/[term].xml.ts`. + +**Warum:** Astro generiert aus `[term].xml.ts` die URL `/categories/TERM.xml`, aber die erwartete URL ist `/categories/TERM/index.xml` (analog zur HTML-Route `/categories/TERM/`). Die Verzeichnisstruktur `[term]/index.xml.ts` erzeugt korrekt `/categories/TERM/index.xml`. Dasselbe gilt für `tags/[term]/index.xml.ts` und `blog/archive/[year]/index.xml.ts`. + +**Generierte Feed-Routen:** +- `/blog/index.xml` — alle Posts +- `/blog/archive/index.xml` — alle Posts (identisch) +- `/blog/archive/YYYY/index.xml` — Posts eines Jahres +- `/categories/TERM/index.xml` — Posts einer Kategorie +- `/tags/TERM/index.xml` — Posts eines Tags + +--- + +#### Shared Helpers: `src/lib/posts.ts` + +**Was:** Gemeinsam genutzte Hilfsfunktionen (`getAllPosts`, `postUrl`, `getSummary`, `wordCount`) sind in `src/lib/posts.ts` zentralisiert und werden von allen Seiten und API-Routen importiert. + +**Warum:** Ohne dieses Modul wäre `getCollection('blog')`, die Sortierlogik, `wordCount` und `getSummary` in allen Seiten-Dateien dupliziert worden (Blog-Index, Jahres-Archiv, Kategorie-Term, Tag-Term, Blog-Post, alle RSS-Feeds). Der Refactoring-Schritt wurde nach dem ersten Implementierungs-Durchlauf gemacht, als die Duplikation offensichtlich wurde. + +--- + +#### SEO: Description-Prop und OG-Tags in BaseLayout + +**Was:** `BaseLayout.astro` akzeptiert eine optionale `description`-Prop, die zu `` und `` wird. Zusätzlich werden `og:title`, `og:type` und `og:url` immer gerendert. + +**Warum:** Hugo rendert diese Meta-Tags automatisch aus dem Frontmatter. In Astro gibt es kein eingebautes SEO-System — es wurde bewusst darauf verzichtet, ein SEO-Integrations-Paket (z.B. `astro-seo`) einzuführen. Die wenigen benötigten Tags wurden direkt in `BaseLayout.astro` implementiert, da das einfacher und transparenter ist. Seiten ohne explizite `description`-Prop (z.B. Archiv-Seiten) rendern keine Description-Tags. + +--- + +#### Hugo-Dateien entfernt nach Migration + +**Was:** Nach Abschluss der Astro-Migration wurden folgende Hugo-spezifische Dateien und Verzeichnisse aus dem Repo entfernt: +- `content/` (1288 Blog-Artikel und Seiten — nun in `src/content/blog/`) +- `themes/PaperMod/` (Hugo-Theme-Submodul) +- `themes/hugo-juplo/` (das eigene Hugo-Theme-Submodul) +- `hugo.yaml` (Hugo-Konfiguration) +- `archetypes/` (Hugo-Vorlagen für neue Inhalte) +- `inventory.md` (Hilfsdatei zur Analyse während der Migration) +- `.gitmodules` (Submodul-Konfiguration, da keine Submodule mehr vorhanden) + +**Behalten:** +- `data/` (enthält echte Nutzer-Kommentardaten, kein Hugo-spezifischer Content) +- `docker-compose.yml` und `nginx.conf` (Deployment-Konfiguration, unabhängig vom SSG) +- `public/` (statische Assets, bereits im Astro-Format) -- 2.39.5