From: Kai Moritz Date: Wed, 3 Jun 2026 22:17:48 +0000 (+0000) Subject: Dokumentation der Projektstruktur, Template-Architektur und Menü-Konzept X-Git-Url: https://juplo.de/gitweb/?a=commitdiff_plain;h=c0bc0fbde3bb53b2eb5fdd07c3f37e0ed252c0de;p=website Dokumentation der Projektstruktur, Template-Architektur und Menü-Konzept Ergänzt CLAUDE.md im Hauptrepo mit einem vollständigen Abschnitt zur technischen Projektstruktur, die aus der Ist-Analyse hervorgegangen ist: Template-Aufbau, Block-Override-Tabelle, Menü-Konzept (SEO-Sitemap), Content-Architektur (Zielzustand). Vorhandene Abschnitte wurden konsolidiert und gestrafft. Im Theme-Submodule wurde erstmals eine CLAUDE.md angelegt mit Verzeichnisstruktur, Menü-System-Beschreibung und Shortcode-Übersicht. Co-Authored-By: Claude Sonnet 4.6 --- diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 00000000..655609f6 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,103 @@ +# CLAUDE.md + +Diese Datei enthält Anweisungen für Claude Code (claude.ai/code) beim Arbeiten mit diesem Verzeichnis. + +## Arbeitsregeln + +- Wenn du nicht explizit anders angewiesen wirst, arbeitest du nur innerhalb dieses Repositories und des Theme-Submodules. +- Du arbeitest immer auf dem bereits ausgecheckten Branch `content--via-hugo`. +- Ab und zu bin ich ungenau oder bringe Details durcheinander. Wenn du den Eindruck hast, dass etwas nicht passt oder Details fehlen, frage immer direkt nach. +- Für alle Aufgaben gilt: du kannst und sollst Nachfragen stellen, bevor du mit der Umsetzung beginnst, wenn das sinnvoll ist. + +## Commits + +- Erstelle nach dem Abschluss einer Aufgabe jeweils einen Commit. +- Fasse in der Commit-Nachricht zusammen, was und warum geändert wurde. +- Wenn du zugehörige Änderungen im Theme-Repository gemacht hast, erstelle auch dort einen separaten Commit mit einer ebenfalls sinnvollen Beschreibung. +- Wenn du meinst, dass ein Theme-Commit besonders wichtig oder unabhängig verständlich ist, weise mich darauf hin. + +## Projektstruktur + +Das Projekt besteht aus zwei Git-Repositories: + +``` +content--via-hugo (dieses Repo) +├── content/ ← Blog-Artikel, Projects-Doku +│ ├── _index.md ← Startseite +│ ├── blog/ ← Blog-Artikel, nach Jahr organisiert unter archive/ +│ └── projects/ ← Maven-Plugin-Dokumentation (generiert, versioniert) +├── hugo.yaml ← Hugo-Konfiguration +├── data/ ← YAML-Datendateien (comments, library) +├── static/ ← Statische Assets (Maven-Site-Outputs etc.) +└── themes/hugo-juplo/ ← Git-Submodule (Branch: frontend) + ├── layouts/ ← Hugo-Templates + ├── assets/scss/ ← SCSS-Quellen (5 Breakpoints + Print) + ├── content/ ← Struktureller Site-Content (About, Impressum, Taxonomien) + └── exampleSite/ ← Standalone-Testsite für Theme-Entwicklung (hugo.dev/hugo-themes best practice) +``` + +Das Theme ist als Git-Submodule unter `themes/hugo-juplo` eingebunden (Branch `frontend` im selben Git-Server-Repo unter einem anderen Branch). Änderungen am Theme werden im Submodule-Verzeichnis committet, Änderungen am Content im Hauptrepo – immer getrennt. + +Zur CLAUDE.md im Theme-Submodule: `themes/hugo-juplo/CLAUDE.md` + +## Template-Struktur + +`baseof.html` definiert das HTML-Gerüst aller Seiten: + +``` +body + └── #page + ├── header#header Logo + Slogan + ├── #breadcrumb (block: breadcrumb – überschreibbar) + └── main.content + ├── article#content (block: article → block: title + block: content) + └── .marginal + ├── nav#nav (block: menu – Menü/Sitemap) + └── asides (block: marginalcontent – Taxonomien, Custom-Content) + └── footer#footer Copyright + Footer-Links +``` + +Spezialisierte Layouts nach Seitentyp (alle als `{{ define "block" }}` Overrides): + +| Layout | Verwendung | Besonderheit | +|---|---|---| +| `index.html` | Startseite | überschreibt `article` | +| `section.html` | Generic-Section | überschreibt `content` | +| `article.html` | Generic-Artikel | überschreibt `article` | +| `page.html` | Standalone-Seite | überschreibt `content` + `marginalcontent` (zeigt Taxonomie-Terms) | +| `blog/section.html` | `/blog/` | überschreibt `menu` + `article` | +| `blog/archive/section.html` | `/blog/archive/` | überschreibt `menu` + `content` + `title` | +| `blog/archive/year.html` | `/blog/archive/YYYY/` | überschreibt `menu` + `content` + `title` | +| `blog/archive/page.html` | Blog-Artikel | überschreibt `menu` + `content` | +| `categories/taxonomy.html` | `/categories/` | überschreibt `breadcrumb` + `menu` + `content` | +| `categories/term.html` | `/categories/X/` | überschreibt `breadcrumb` + `menu` + `content` | +| `tags/taxonomy.html` | `/tags/` | überschreibt `breadcrumb` + `menu` + `content` | +| `tags/term.html` | `/tags/X/` | überschreibt `breadcrumb` + `menu` + `content` | + +## Menü-Konzept (SEO-Sitemap) + +Das Menü unter `nav#nav` ist bewusst am **Ende des HTML** platziert (im `.marginal`-Bereich) und dient gleichzeitig als SEO-Sitemap. Es hat zwei Ebenen: + +**Ebene 1 – Section-Menu (`#menu`):** Horizontale Hauptnavigation aus `MainSections` (Blog, Projects, About). + +**Ebene 2 – Sub-Menu (`#submenu`):** Baumstruktur der gesamten Site ab Home. Zeigt immer den vollständigen Baum, wobei: +- Items mit Kindern erhalten Klasse `sub` +- Items außerhalb des aktuellen Pfads erhalten Klasse `off` +- Der aktive Link und seine Vorfahren erhalten `class="selected"` am ``-Element + +Das rekursive Partial `menu/tree.html` handhabt die Projects-Sektion mit spezieller Sichtbarkeitslogik: Von Projektversionen werden im Menü nur Seiten angezeigt, die sich im aktuellen URL-Pfad befinden oder im Frontmatter `current: true` gesetzt haben. + +Für den Blog-Ast (Archive, Categories, Tags) gibt es separate Template-Logik in den jeweiligen Layout-Dateien, da Taxonomy-Seiten nicht im normalen Hugo-Seitenbaum liegen. + +## Content-Architektur (Zielzustand) + +- **Theme** (`themes/hugo-juplo`): ausschließlich Layouts, SCSS, Partials, Archetypes, `exampleSite` +- **Dieses Repo**: ausschließlich Content (alle `.md`/`.html` Seiten inkl. About, Impressum) + +Der `exampleSite`-Ansatz im Theme dient zum isolierten Testen des Themes unabhängig vom Content-Branch. + +## Stand der Umsetzung + +Das Theme ist funktional (Menü, Breadcrumb, Taxonomien, Blog-Archiv, Syntax-Highlighting, responsive Layout). Die Template-Implementierung enthält noch Copy-paste-Duplikate, die schrittweise konsolidiert werden sollen. Größte offene Aufgabe: Den `menu`-Block aus den 7+ Einzel-Templates in ein parametrisiertes Partial konsolidieren. + +Bekannte Baustellen und ihre Priorität sind in der Analyse vom 2026-06-03 dokumentiert. diff --git a/themes/hugo-juplo b/themes/hugo-juplo index ac555cfa..4b25ec17 160000 --- a/themes/hugo-juplo +++ b/themes/hugo-juplo @@ -1 +1 @@ -Subproject commit ac555cfa5057f1050a91d4c81fe4db287d93b0f3 +Subproject commit 4b25ec17bc2c52d3ff8578247dd6f93d0dd934af