Architecture Portfolio JBake - Vision et Use Cases
Yayınlandı: 15 January 2026
Mimari Vizyon
Yönlendirici ilke
Mimari, İlgililiklerin Ayrılması ilkesine dayanır :
-
İçerik: zengin metaveri içeren yapılandırılmış AsciiDoc dosyaları
-
Sunum : Yeniden kullanılabilir Thymeleaf şablonları
-
Veri : JBake tarafından AsciiDoc özelliklerinden otomatik olarak çıkarılan model
-
Stil : Görsel tutarlılık için Bootstrap 5
Stratejik seçenek: Portföy için AsciiDoc
| kriter | Avantaj |
|---|---|
tutarlılık |
Blog gönderileriyle aynı format. |
Meta Veri |
Yapılandırılmış ve genişletilebilir öznitelikler ( |
Bakım yapılabilirlik |
Basit metin düzenleme, Git ile sürüm takibi |
Esneklik |
Tablolar, kod ve görselleri içerebilir |
Şablonlama |
JBake, Thymeleaf için öznitelikleri otomatik olarak çıkarır |
Veri modeli
Her portföy projesi bir AsciiDoc belgesi ile :
-
Üst bilgi meta verileri : yapılandırılmış bilgiler (müşteri, süre, teknolojiler, vb.)
-
Corps du document : hikâye tarzında açıklama, zorluklar, çözümler, sonuçlar
-
Özel nitelikler : önekli`project-*`otomatik ekstraksiyon için
@startuml
skinparam backgroundColor #FEFEFE
skinparam handwritten false
class ProjetAsciiDoc {
+titre: String
+jbake-type: "proje"
+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 : veri sağlar
ThymeleafTemplate --> PortfolioPage : üretir
@enduml
Detaylı Kullanım Senaryoları
UC1 : Portfolioya bir öğe ekle
Nominal akış
@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
Oluşturulacak dosya şablonu
Geliştirici oluşturur`content/portfolio/nom-projet.adoc`standart bir yapıyla :
-
Tüm gerekli niteliklerle başlık
-
Standartlaştırılmış bölümler (Bağlam, Zorluklar, Çözümler, Sonuçlar)
-
Tutarlı görüntü adlandırımı
Validasyon puanları
-
Zorunlu öznitelikler mevcuttur (
jbake-type,jbake-status,project-thumbnail) -
Referans gösterilen görüntüler içinde mevcuttur.
assets/img/portfolio/ -
JBake derlemesi hatasız olarak başarılır
-
Proje portföyo sayfasında gösterilir.
-
Proje ayrıntılı sayfası düzgün görüntüleniyor.
UC2 : Portföyden bir öğe silin
Nominal akış
@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
Alternatif strateji: arşivleme
Temiz silmek yerine bir klasör oluşturmak mümkün.content/portfolio/archive/:
-
Dosyayı silmek yerine taşı.
-
Kolayca geri yüklemesini sağlar.
-
Git geçmişini daha açık tut
Kaynak temizliği
-
Öksüz görüntüler kontrol et`assets/img/portfolio/`
-
Başka projeler tarafından referans gösterilmemiş görüntüleri sil
-
JBake önbelleğini temizleyerek hayalet referanslardan kaçının.
UC3 : Taslak haline getir
Nominal akış
@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
Olası durumlar
@startuml skinparam backgroundColor #FEFEFE [*] --> Draft : Création initiale Draft --> Published : Doğrulama ve yayın Published --> Draft : Geçici çekim Draft --> Archived : İptal edilen proje Published --> Archived : Eski proje Archived --> [*] : Kalıcı silme Published --> Published : Güncellemeler note right of Draft :jbake-status: draft Genel olarak görünmez Devam eden projeler için faydalı end note note right of Published :jbake-status: published Portföyde görünür JBake tarafından dizinlendi end note note right of Archived Arşiv/ klasörüne taşındı veya jbake-status: arşivlendi Yayınlanmadı ama saklandı end note @enduml
Tipik kullanım durumları
-
Yazım aşamasında olan proje: taslak olarak oluştur, hazır olduğunda yayınla
-
Geçici olarak gizli proje : müşteri anlaşması olana kadar taslak duruma geçmek
-
Büyük Güncelleme : drafta geçmek, düzenlemek, tekrar yayınlamak
-
A/B testing : drafte kopyala, test et, en iyi versiyonu yayınla
Şablonlama Mimarisi
Tekrar kullanılabilir şablonlar stratejisi
@startuml
skinparam backgroundColor #FEFEFE
skinparam componentStyle rectangle
package "Şablonlar Thymeleaf" {
component [index.html] as index
component [portfolio.html] as portfolio
component [project.html] as project
package "Kısmi şablonlar" {
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 "Veriler JBake" {
database "published_projects" as data
database "İçerik (proje)" as content
}
index --> header
index --> footer
portfolio --> header
portfolio --> footer
portfolio --> card
data --> portfolio : yineleme
project --> header
project --> footer
project --> badge
project --> gallery
content --> project : bireysel proje
note right of card
Yeniden kullanılabilir bölüm
proje kartı göstermek için:
- küçük resim
- başlık
- etiketler
- vurgular
end note
@enduml
Veri çıkarma deseni
JBake, AsciiDoc özelliklerini otomatik olarak Thymeleaf içinde erişilebilir olan özelliklere dönüştürür :
@startuml
skinparam backgroundColor #FEFEFE
rectangle "Document AsciiDoc" {
(":project-client: Acme Corp") as attr1
(":project-duration: 6 ay") as attr2
(":project-tags: java, react") as attr3
}
rectangle "Model JBake" {
(content['project-client']) as prop1
(content['project-duration']) as prop2
(content.tags) as prop3
}
rectangle "Template Thymeleaf" {
(th:text="${project['project-client']}") as tmpl1
(th:text="${project['project-duration']}") as tmpl2
(th:each="tag : ${project.tags}") as tmpl3
}
attr1 --> prop1 : ayrıştırma
attr2 --> prop2 : parsing
attr3 --> prop3 : ayrıştırma
prop1 --> tmpl1 : bağlama
prop2 --> tmpl2 : bağlama
prop3 --> tmpl3 : bağlayıcı
@enduml
İsimlendirme kuralları
-
Proje Özellikleri : önek`project-*` (ex:
project-client,project-tech-stack) -
Dosyalar : kebab-case (örnek:`ecommerce-platform.adoc`)
-
Görüntüler : önek isim-proje (örn:`ecommerce-platform-thumb.jpg`)
-
Templates : işlevsel ad (örnek:`project-card.html`,
tech-badge.html)
Yayın İş Akışı
Geliştirme hattı
@startuml
skinparam backgroundColor #FEFEFE
skinparam handwritten false
class ProjetAsciiDoc {
+titre: String
+jbake-type: "proje"
+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 : ayrıştır
JBakeEngine --> ThymeleafTemplate : veri sağlar
ThymeleafTemplate --> PortfolioPage : üretir
@enduml
ortamlar
| Ortam | Kullanım | Kabul edilen statü |
|---|---|---|
Yerel |
Geliştirme ve önizleme |
taslak, yayınlanmış |
Aşama |
Üretim öncesi doğrulama |
sadece yayınlandı |
Üretim |
Kamu sitesi |
Sadece yayınlanmış |
Genişletilebilirlik
Yeni özellikler ekleme
Veri modelini zenginleştirmek için sadece yeni önekli özellikler ekleyin.project-*(empty)
-
project-awards: Ödüller ve takdirler -
`project-testimonial`Müşteri alıntısı
-
`project-team-size`Ekip boyutu
-
`project-budget-range`Bütçe aralığı
Bu özellikler, JBake motoru değiştirilmeden şablonlarda otomatik olarak mevcut olur.
Gelişmiş kategorizasyon
@startuml
skinparam backgroundColor #FEFEFE
object Projet {
project-category = "web"
project-subcategory = "e-ticaret"
project-industry = "perakende"
project-complexity = "yüksek"
}
object Taxonomie {
categories : [web, mobile, data, devops]
subcategories : Map<category, List>
industries : [retail, finance, healthcare, ...]
complexities : [low, medium, high]
}
Projet --> Taxonomie : sınıflandırıldı göre
note right of Taxonomie
portfolio.html şablonunda JavaScript üzerinden çok kriterli filtrelemeyi sağlar veya sunucu tarafında yapar.
end note
@enduml
İyi Uygulamalar
Dosya Organizasyonu
-
Bir dosya = bir proje : Birden fazla projeyi karıştırma
-
Özel klasöründeki resimler
assets/img/portfolio/nom-projet/ -
Tutarlı adlandırmalar : araştırma ve bakımı kolaylaştırır
-
Versioning Git : Değişikliklerin tam takibi
İçerik yönetimi
-
Varsayılan taslak durumu : sadece hazır olduğunda yayınla
-
Yayın öncesi inceleme : Kalite ve Gizlilik Doğrulama
-
Tam Meta Veriler : İlgili tüm alanları doldurun
-
Zengin anlatıcı içerik : metavermelerle sınırlı kalmayın
Performans
-
Görselleri optimize et : commit öncesi sıkıştırma
-
Pagination si gerekli : >20 proje
-
Lazy loading : Galeri görselleri talep üzerine yüklenir
-
Tarayıcı önbelleği : varlıklar için uygun başlıklar
Sonuç
Bu mimari şuna izin verir:
-
Kullanım Kolaylığı : bir proje eklemek = bir metin dosyası oluşturmak
-
Esneklik : yeni nitelikler aracılığıyla genişletilebilir
-
Bakım kolaylığı : içerik/sunum ayrımı
-
izlenebilirlik : tam Git versiyonlama
-
Otomasyon : derleme ve sürekli dağıtım mümkün
AsciiDoc seçimi, sitenin geri kısmıyla tutarlılığı sağlarken, profesyonel bir portföy için gerekli meta verilerin zenginliğini de sunar.