Architecture Portfolio JBake - Vision et Use Cases
Veröffentlicht am 15 January 2026
Architektonische Vision
Leitprinzip
Die Architektur beruht auf dem Prinzip der Trennung der Anliegen :
-
Inhalt : strukturierte AsciiDoc-Dateien mit reichen Metadaten
-
Präsentation : wiederverwendbare Thymeleaf-Vorlagen
-
Daten : Modell automatisch von JBake aus den AsciiDoc-Attributen extrahiert
-
Stil : Bootstrap 5 für visuelle Konsistenz
Strategische Wahl: AsciiDoc für das Portfolio
| Kriterium | Vorteil |
|---|---|
Kohärenz |
Das gleiche Format wie bei den Blogartikeln |
Metadaten |
Strukturierte und erweiterbare Attribute`project-*`) |
Wartbarkeit |
Einfache Textbearbeitung, Git-versionierbar |
Flexibilität |
Kann reichhaltigen Inhalt (Tabellen, Code, Bilder) enthalten |
Vorlagenbildung |
JBake extrahiert automatisch die Attribute für Thymeleaf |
Datenmodell
Jedes Portfolio-Projekt ist ein AsciiDoc-Dokument mit:
-
Header-Metadaten : strukturierte Informationen (Kunde, Dauer, Technologien usw.)
-
Dokumentenkörper: narrative Beschreibung, Herausforderungen, Lösungen, Ergebnisse
-
Benutzerdefinierte Attribute : präfixiert`project-*`für die automatische Extraktion
@startuml
skinparam backgroundColor #FEFEFE
skinparam handwritten false
class ProjetAsciiDoc {
+titre: String
+jbake-type: "project"
+jbake-status: published|draft
+jbake-date: Date
+jbake-tags: List<String>
--
+project-category: String
+project-client: String
+project-duration: String
+project-role: String
+project-thumbnail: String
+project-gallery: List<String>
+project-tech-stack: String
+project-highlights: List<String>
+project-demo-url: String
+project-github-url: String
--
+body: HTML (converti)
}
class JBakeEngine {
+parse(asciidoc)
+extractMetadata()
+convertToHTML()
}
class ThymeleafTemplate {
+portfolio.html
+project.html
+partials/project-card.html
}
class PortfolioPage {
+published_projects: List
+filtres: categories
}
ProjetAsciiDoc --> JBakeEngine : parse
JBakeEngine --> ThymeleafTemplate : fournit données
ThymeleafTemplate --> PortfolioPage : génère
@enduml
Detaillierte Anwendungsfälle
UC1 : Ein Element zum Portfolio hinzufügen
Nominalfluss
@startuml skinparam backgroundColor #FEFEFE actor Développeur as dev participant "Éditeur\nTexte" as editor participant "Fichier\nAsciiDoc" as file participant "JBake\nEngine" as jbake participant "Site\nStatique" as site dev -> editor : Créer nouveau fichier activate editor editor -> file : portfolio/nouveau-projet.adoc activate file dev -> editor : Rédiger en-tête avec métadonnées\n(titre, type=project, status=published,\nattributs project-*) dev -> editor : Rédiger contenu narratif\n(contexte, défis, solutions) dev -> editor : Ajouter images dans assets/img/portfolio/ editor -> file : Sauvegarder deactivate editor dev -> jbake : Lancer build (jbake -b) activate jbake jbake -> file : Lire et parser jbake -> jbake : Extraire métadonnées jbake -> jbake : Convertir AsciiDoc → HTML jbake -> jbake : Appliquer template project.html jbake -> jbake : Ajouter à la liste portfolio.html jbake -> site : Générer pages statiques deactivate jbake dev -> site : Vérifier résultat activate site site --> dev : Afficher projet deactivate site @enduml
Vorlage der zu erstellenden Datei
Der Entwickler erstellt`content/portfolio/nom-projet.adoc`mit einer standardisierten Struktur :
-
Kopfzeile mit allen erforderlichen Attributen
-
Standardisierte Abschnitte (Kontext, Herausforderungen, Lösungen, Ergebnisse)
-
Konsistente Nomenklatur der Bilder
Validierungspunkte
-
Die verpflichtenden Attribute sind vorhanden (
jbake-type,jbake-status,project-thumbnail) -
Die referenzierten Bilder existieren in`assets/img/portfolio/`
-
Der JBake-Build läuft ohne Fehler
-
Das Projekt erscheint auf der Portfolio-Seite
-
Die individuelle Projektseite wird korrekt angezeigt.
UC2 : Lösche ein Element des Portfolios
Nominalfluss
@startuml skinparam backgroundColor #FEFEFE actor Développeur as dev participant "Système\nFichiers" as fs participant "JBake\nEngine" as jbake participant "Site\nStatique" as site database "Cache\nJBake" as cache dev -> fs : Supprimer portfolio/projet-ancien.adoc activate fs fs --> dev : Fichier supprimé deactivate fs dev -> fs : (Optionnel) Supprimer images associées\nassets/img/portfolio/projet-ancien-* activate fs fs --> dev : Images supprimées deactivate fs dev -> cache : Nettoyer cache JBake activate cache cache --> dev : Cache vidé deactivate cache dev -> jbake : Rebuild complet (jbake -b) activate jbake jbake -> jbake : Scanner content/portfolio/ jbake -> jbake : Projet absent → non généré jbake -> jbake : Régénérer portfolio.html\n(sans le projet supprimé) jbake -> site : Déployer nouveau build deactivate jbake dev -> site : Vérifier activate site site --> dev : Projet absent de la liste deactivate site @enduml
Alternative Strategie: Archivierung
Anstatt endgültig zu löschen, Möglichkeit, einen Ordner zu erstellen`content/portfolio/archive/`:
-
Die Datei verschieben anstatt sie zu löschen
-
Ermöglicht das einfache Wiederherstellen
-
Behalte den Git-Verlauf übersichtlicher
Bereinigung der Ressourcen
-
Verwaiste Bilder überprüfen in`assets/img/portfolio/`
-
Bilder löschen, die von anderen Projekten nicht referenziert werden
-
Den JBake-Cache bereinigen, um Geisterreferenzen zu vermeiden
UC3 : Als Entwurf setzen
Nominalfluss
@startuml skinparam backgroundColor #FEFEFE actor Développeur as dev participant "Fichier\nAsciiDoc" as file participant "JBake\nEngine" as jbake participant "Site\nStatique" as site dev -> file : Ouvrir portfolio/projet.adoc activate file dev -> file : Modifier attribut\n:jbake-status: published\n↓\n:jbake-status: draft file --> dev : Sauvegardé deactivate file dev -> jbake : Rebuild (jbake -b) activate jbake jbake -> file : Parser le fichier jbake -> jbake : Détecter status=draft jbake -> jbake : Exclure de published_projects jbake -> jbake : Ne pas créer page publique note right Le projet existe toujours mais n'est pas publié end note jbake -> site : Générer site (sans ce projet) deactivate jbake dev -> site : Vérifier portfolio activate site site --> dev : Projet absent de la liste publique deactivate site @enduml
Mögliche Zustände
@startuml skinparam backgroundColor #FEFEFE [*] --> Draft : Création initiale Draft --> Published : Validation et publication Published --> Draft : Retrait temporaire Draft --> Archived : Projet abandonné Published --> Archived : Projet obsolète Archived --> [*] : Suppression définitive Published --> Published : Mises à jour note right of Draft :jbake-status: draft Non visible publiquement Utile pour projets en cours end note note right of Published :jbake-status: published Visible sur le portfolio Indexé par JBake end note note right of Archived Déplacé dans archive/ ou jbake-status: archived Non publié mais conservé end note @enduml
Typische Anwendungsfälle
-
Projekt in Bearbeitung : Entwurf erstellen, veröffentlichen wenn bereit
-
Vorübergehend vertrauliches Projekt : in den Entwurf wechseln, bis die Kundenzustimmung vorliegt
-
Wichtiges Update: in den Entwurf wechseln, bearbeiten, erneut veröffentlichen
-
A/B testing : Entwurf duplizieren, testen, die beste Version veröffentlichen
Templating-Architektur
Strategie wiederverwendbarer Templates
@startuml
skinparam backgroundColor #FEFEFE
skinparam componentStyle rectangle
package "Templates Thymeleaf" {
component [index.html] as index
component [portfolio.html] as portfolio
component [project.html] as project
package "Partials" {
component [header.html] as header
component [footer.html] as footer
component [project-card.html] as card
component [tech-badge.html] as badge
component [gallery.html] as gallery
}
}
package "Données JBake" {
database "published_projects" as data
database "content (projet)" as content
}
index --> header
index --> footer
portfolio --> header
portfolio --> footer
portfolio --> card
data --> portfolio : itération
project --> header
project --> footer
project --> badge
project --> gallery
content --> project : projet individuel
note right of card
Fragment réutilisable
pour afficher une carte
de projet avec :
- thumbnail
- titre
- tags
- highlights
end note
@enduml
Muster der Datenextraktion
JBake konvertiert AsciiDoc-Attribute automatisch in Eigenschaften, die in Thymeleaf zugänglich sind :
@startuml
skinparam backgroundColor #FEFEFE
rectangle "AsciiDoc-Dokument" {
(":project-client: Acme Corp") as attr1
(":project-duration: 6 Monate") as attr2
(":project-tags: java, react") as attr3
}
rectangle "JBake-Modell" {
(content['project-client']) as prop1
(content['project-duration']) as prop2
(content.tags) as prop3
}
rectangle "Thymeleaf-Template" {
(th:text="${project['project-client']}") as tmpl1
(th:text="${project['project-duration']}") as tmpl2
(th:each="Tag : ${project.tags}") as tmpl3
}
attr1 --> prop1 : parsing
attr2 --> prop2 : parsing
attr3 --> prop3 : parsing
prop1 --> tmpl1 : binding
prop2 --> tmpl2 : binding
prop3 --> tmpl3 : binding
@enduml
Namenskonventionen
-
Projektattribute : Präfix`project-*` (ex:
project-client,project-tech-stack) -
Dateien : kebab-case (ex:`ecommerce-platform.adoc`)
-
Bilder : Projektname-Präfix (Beispiel:`ecommerce-platform-thumb.jpg`)
-
Vorlagen : funktionaler Name (z.B:`project-card.html`,
tech-badge.html)
Workflow der Veröffentlichung
Entwicklungs-Pipeline
@startuml
skinparam backgroundColor #FEFEFE
skinparam handwritten false
class ProjetAsciiDoc {
+titre: String
+jbake-type: "project"
+jbake-status: published|draft
+jbake-date: Date
+jbake-tags: List<String>
__
+project-category: String
+project-client: String
+project-duration: String
+project-role: String
+project-thumbnail: String
+project-gallery: List<String>
+project-tech-stack: String
+project-highlights: List<String>
+project-demo-url: String
+project-github-url: String
__
+body: HTML (converti)
}
class JBakeEngine {
+parse(asciidoc)
+extractMetadata()
+convertToHTML()
}
class ThymeleafTemplate {
+portfolio.html
+project.html
+partials/project-card.html
}
class PortfolioPage {
+published_projects: List
+filtres: categories
}
ProjetAsciiDoc --> JBakeEngine : parse
JBakeEngine --> ThymeleafTemplate : fournit données
ThymeleafTemplate --> PortfolioPage : génère
@enduml
Umgebungen
| Umgebung | Verwendung | Akzeptierter Status |
|---|---|---|
Lokal |
Entwicklung und Vorschau |
Entwurf, veröffentlicht |
Staging |
Vorproduktionsvalidierung |
veröffentlicht ausschließlich |
Produktion |
öffentliche Seite |
published nur |
Erweiterbarkeit
Hinzufügen neuer Attribute
Um das Datenmodell zu bereichern, einfach neue Präfix-Attribute hinzufügen`project-*`</think>
-
project-awards: Preise und Anerkennungen -
project-testimonial: Kunden-Zitat -
`project-team-size`Teamgröße
-
project-budget-range: Budgetspanne
Diese Attribute werden automatisch in den Vorlagen verfügbar, ohne dass der JBake-Motor modifiziert werden muss.
Erweiterte Kategorisierung
@startuml
skinparam backgroundColor #FEFEFE
object Projet {
project-category = "web"
project-subcategory = "ecommerce"
project-industry = "retail"
project-complexity = "high"
}
object Taxonomie {
categories : [web, mobile, data, devops]
subcategories : Map<category, List>
industries : [retail, finance, healthcare, ...]
complexities : [low, medium, high]
}
Projet --> Taxonomie : classifié selon
note right of Taxonomie
Permet filtrage multi-critères
dans le template portfolio.html
via JavaScript ou côté serveur
end note
@enduml
Gute Praktiken
Organisation der Dateien
-
Eine Datei = ein Projekt : vermeide das Vermischen mehrerer Projekte
-
Bilder im dedizierten Ordner
assets/img/portfolio/nom-projet/ -
Konsistente Nomenklatur : erleichtert Suche und Wartung
-
Versioning Git : vollständiges Tracking der Änderungen
Inhaltsverwaltung
-
Standardentwurf-Status : nur veröffentlichen, wenn bereit
-
Review vor der Veröffentlichung : Validierung von Qualität und Vertraulichkeit
-
vollständige Metadaten : alle relevanten Felder ausfüllen
-
Reicher narrativer Inhalt: nicht auf Metadaten beschränken
Leistung
-
Bilder optimieren : Komprimierung vor Commit
-
Pagination falls notwendig : wenn >20 Projekte
-
Lazy loading : Bei Bedarf geladene Bilder in den Galerien
-
Browser-Cache : geeignete Header für Assets
Fazit
Diese Architektur ermöglicht :
-
Einfache Handhabung : ein Projekt hinzufügen = eine Textdatei erstellen
-
Flexibilität : erweiterbar durch neue Attribute
-
Wartbarkeit : Trennung Inhalt/Präsentation
-
Nachverfolgbarkeit : vollständiges Git-Versioning
-
Automatisierung : build und kontinuierliche Bereitstellung möglich
Die Wahl von AsciiDoc gewährleistet die Konsistenz mit dem Rest der Website und bietet gleichzeitig den Reichtum an Metadaten, die für ein professionelles Portfolio erforderlich sind.