Architecture Portfolio JBake - Vision et Use Cases

Publié le 19 January 2026

1. Vision Architecturale

1.1. Principe directeur

L’architecture repose sur le principe de séparation des préoccupations :

  • Contenu : fichiers AsciiDoc structurés avec métadonnées riches

  • Présentation : templates Thymeleaf réutilisables

  • Données : modèle extrait automatiquement par JBake depuis les attributs AsciiDoc

  • Style : Bootstrap 5 pour la cohérence visuelle

1.2. Choix stratégique : AsciiDoc pour le portfolio

Table 1. Pourquoi AsciiDoc ?
Critère Avantage

Cohérence

Même format que les articles de blog

Métadonnées

Attributs structurés et extensibles (project-*)

Maintenabilité

Édition simple en texte, versionnable Git

Flexibilité

Peut contenir du contenu riche (tableaux, code, images)

Templating

JBake extrait automatiquement les attributs pour Thymeleaf

1.3. Modèle de données

Chaque projet portfolio est un document AsciiDoc avec :

  • Métadonnées d’en-tête : informations structurées (client, durée, technologies, etc.)

  • Corps du document : description narrative, défis, solutions, résultats

  • Attributs personnalisés : préfixés project-* pour l’extraction automatique

Diagram

2. Use Cases Détaillés

2.1. UC1 : Ajouter un élément au portfolio

2.1.1. Flux nominal

Diagram

2.1.2. Template du fichier à créer

Le développeur crée content/portfolio/nom-projet.adoc avec une structure standardisée :

  • En-tête avec tous les attributs requis

  • Sections normalisées (Contexte, Défis, Solutions, Résultats)

  • Nomenclature cohérente des images

2.1.3. Points de validation

  • Les attributs obligatoires sont présents (jbake-type, jbake-status, project-thumbnail)

  • Les images référencées existent dans assets/img/portfolio/

  • Le build JBake réussit sans erreur

  • Le projet apparaît sur la page portfolio

  • La page individuelle du projet s’affiche correctement

2.2. UC2 : Supprimer un élément du portfolio

2.2.1. Flux nominal

Diagram

2.2.2. Stratégie alternative : archivage

Au lieu de supprimer définitivement, possibilité de créer un dossier content/portfolio/archive/ :

  • Déplacer le fichier au lieu de le supprimer

  • Permet de restaurer facilement

  • Garde l’historique Git plus clair

2.2.3. Nettoyage des ressources

  • Vérifier les images orphelines dans assets/img/portfolio/

  • Supprimer les images non référencées par d’autres projets

  • Nettoyer le cache JBake pour éviter les références fantômes

2.3. UC3 : Mettre en non publié (draft)

2.3.1. Flux nominal

Diagram

2.3.2. États possibles

Diagram

2.3.3. Cas d’usage typiques

  • Projet en cours de rédaction : créer en draft, publier quand prêt

  • Projet confidentiel temporairement : passer en draft le temps de l’accord client

  • Mise à jour majeure : passer en draft, modifier, republier

  • A/B testing : dupliquer en draft, tester, publier la meilleure version

3. Architecture de Templating

3.1. Stratégie de templates réutilisables

Diagram

3.2. Pattern d’extraction des données

JBake transforme automatiquement les attributs AsciiDoc en propriétés accessibles dans Thymeleaf :

Diagram

3.3. Conventions de nommage

  • Attributs projet : préfixe project-* (ex: project-client, project-tech-stack)

  • Fichiers : kebab-case (ex: ecommerce-platform.adoc)

  • Images : préfixe nom-projet (ex: ecommerce-platform-thumb.jpg)

  • Templates : nom fonctionnel (ex: project-card.html, tech-badge.html)

4. Workflow de Publication

4.1. Pipeline de développement

Diagram

4.2. Environnements

Environnement Usage Statut accepté

Local

Développement et preview

draft, published

Staging

Validation pré-production

published uniquement

Production

Site public

published uniquement

5. Extensibilité

5.1. Ajout de nouveaux attributs

Pour enrichir le modèle de données, simplement ajouter de nouveaux attributs préfixés project-* :

  • project-awards: Prix et reconnaissances

  • project-testimonial: Citation client

  • project-team-size: Taille équipe

  • project-budget-range: Fourchette budgétaire

Ces attributs deviennent automatiquement disponibles dans les templates sans modification du moteur JBake.

5.2. Catégorisation avancée

Diagram

6. Bonnes Pratiques

6.1. Organisation des fichiers

  • Un fichier = un projet : éviter de mélanger plusieurs projets

  • Images dans dossier dédié : assets/img/portfolio/nom-projet/

  • Nomenclature cohérente : facilite recherche et maintenance

  • Versioning Git : tracking complet des modifications

6.2. Gestion du contenu

  • Statut draft par défaut : publier seulement quand prêt

  • Review avant publication : validation qualité et confidentialité

  • Métadonnées complètes : remplir tous les champs pertinents

  • Contenu narratif riche : ne pas se limiter aux métadonnées

6.3. Performance

  • Optimiser images : compression avant commit

  • Pagination si nécessaire : si >20 projets

  • Lazy loading : images des galeries chargées à la demande

  • Cache navigateur : headers appropriés pour assets

7. Conclusion

Cette architecture permet :

  • Simplicité d’usage : ajouter un projet = créer un fichier texte

  • Flexibilité : extensible via nouveaux attributs

  • Maintenabilité : séparation contenu/présentation

  • Traçabilité : versioning Git complet

  • Automatisation : build et déploiement continus possibles

Le choix d’AsciiDoc assure la cohérence avec le reste du site tout en offrant la richesse des métadonnées nécessaires à un portfolio professionnel.