معماری رؤیت

مبدأ توجيهي

معمار、معاملات کی جدائی کے اصول پر مبنی ہے :

  • محتوى : ملفات AsciiDoc المنظمة مع بيانات تعريفية غنية

  • معرفی : ٹیمپلیٹس Thymeleaf دوبارہ استعمال ہونے والی

  • ڈیٹا : مودل خودکار طور پر JBake سے AsciiDoc کے صفات سے اخذ کیا گیا

  • Style : Bootstrap 5 کے لیے ویجوال ہم آہنگی

استراتژیک انتخاب: AsciiDoc پورٹفولیو کیلئے

.کیوں AsciiDoc ?

معیار فائدہ

ہم آہنگی

بلاگ مضامین جیسے فارمیٹ

میتا ڈیٹا

ساختگی اور قابل توسیع صفات (project-*)

رکھاوٹ کی قابلیت

ساده متنی ترسیل، گِٹ ورژنبل

لچک

شامل ہو سکتا ہے غنى materiال (ٹبیل، کوڈ، تصاویر)

ٹیمپلتنگ

JBake خودکار طور پر Thymeleaf کے لیے صفات نکالتا ہے

ڈیٹا ماڈل

ہر پورٹوفلیو پروجیکٹ ایک AsciiDoc دستاویز ہے جس کے ساتھ :

  • ہڈر میٹا ڈیٹا : منظوم معلومات (کلائن، مدت، ٹیکنالوجیز، وغیرہ)

  • دستاویز کا جسم : روایتی تفصیل، چالن جیز، حل، نتائج

  • اخصائی خصوصیات : پیش لگایا`project-*`خودکار نکال کے لئے

@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

استعمال کے مفصل سيناريوهات

UC1: پورٹ فولیو میں ایک عنصر شامل کریں

معیاری فلکس

@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

بنانے کے لیے فائل کا ٹیمپلیٹ

ڈویلپر بناتا ہے`content/portfolio/nom-projet.adoc`ایک معیاری ڈھانچے کے ساتھ :

  • سرعنوان میں تمام ضروری خصوصیات

  • معياری سیکشن (سیاق، چیلنجز، حلول، نتائج)

  • تصاویر کی متفق نامگذاری

تصدیق کے نقاط

  • ضروری خصوصیات موجود ہیں (jbake-type, jbake-status, project-thumbnail)

  • حوالہ شدہ تصاویر میں موجود ہیں`assets/img/portfolio/`

  • جبیک کا بیلڈ بغیر کسی خطا کے کامیاب ہوتا ہے

  • پروجیکٹ پورٹ فولیو پیج پر ظاہر ہوتا ہے

  • پروجیکٹ کی انفرادی صفحہ صحیح طور پر دکھائی دے رہی ہے

UC2 : پورٹفولیو سے ایک آئٹم حذف کریں

معیاری فلکس

@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

اختیاری حکمت عملی: آرشیو

دائمی طور پر حذف کرنے کی بجائے، فولدَر بنانے کی امکان`content/portfolio/archive/`:

  • فائل کو حذف کرنے کے بجائے اسے منتقل کریں

  • آسانی سےبحال کرنے کی اجازت دیتا ہے

  • گٹ کا تاريخ کو زیادہ واضح رکھیں

وسائل کی صفائی

  • بیچھی گئی تصاویر کا جائزہ لیں میں`assets/img/portfolio/`

  • حذف کریں وہ تصاویر جو دیگر منصوبوں سے ارجاع نہیں کی گئی ہیں

  • JBake کے کیش کو صاف کریں تاکہ بhootیا ارجحانات سے بچا جا سکے

UC3 : غیر شائع کردہ (ڈرافٹ) بنائیں

نومینل فلوکس

@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

ممکن حالات

@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

عام استعمال کے حالات

  • تیار ہونے والی پروجیکٹ : ڈراфт بنائیں، جب تیار ہو تواشاعت کریں

  • پروژہ موقت خفیہ : ڈرافٹ ہو جانا کلائنٹ کے معاہدے کے دوران

  • بڑا اپ ڈیٹ : ڈرافٹ میں جانا، ترمیم کرنا، دوبارہ לפרش کرنا

  • A/B testing : ڈراфт میں نкал کریں، ٹیسٹ کریں، بہترین ویršن اشاعت کریں

ٹیمپلنٹنگ کی معماری

دوبارہ استعمال ہونے والے ٹیمپلیٹ کی حکمت عملی

@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

ڈیٹا نکالنے کا نمونہ

JBake خودکار طور پر AsciiDoc کے خصوصیات کو Thymeleaf میں رسائی کے قابل خصوصیات میں بدل دیتا ہے :

@startuml
skinparam backgroundColor #FEFEFE

rectangle "AsciiDoc دستاویز" {
  (":project-client: Acme Corp") as attr1
  (":project-duration: 6 ماہ") as attr2
  (":project-tags: java, react") as attr3
}

rectangle "JBake ماڈل" {
  (content['project-client']) as prop1
  (content['project-duration']) as prop2
  (content.tags) as prop3
}

rectangle "Thymeleaf ٹیمپلیٹ" {
  (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

نامگذاری کے اصول

  • پروجیکٹ کی خصوصیات : پریفکس`project-*` (ex: project-client, project-tech-stack)

  • فائلز : kebab-case (ex:`ecommerce-platform.adoc`)

  • Images : منصوبہ کے نام کا پیشوند (مثلاً:`ecommerce-platform-thumb.jpg`)

  • Templates : عملی نام (مثال:`project-card.html`, tech-badge.html)

اشاعت کا وورک فلو

پائپ لائن ڈویلپمنٹ

@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

ماحولیات

ماحول استعمال مقبول وضع

مقامی

ترقی اور پیشنمائی

مسودہ، شائع

معراضی

پری پروڈکشن کی تصدیق

صرف شائع کیا گیا

پیداواری

عوامی سائٹ

صرف شائع

قابل توسیع

نئے خصوصیات کا شامل

ڈیٹا ماڈل کو بہتر بنانے کے لیے، صرف نئے پیشforegone خصوصیات شامل کریں`project-*`:

  • project-awards: ایوارڈز اور تحسینات

  • project-testimonial: کلائنٹ کی اقتباس

  • project-team-size: ٹیم کا سائز

  • `project-budget-range`بجٹ کی حد

یہویں خصوصیات خودکار طور پر ٹیمپلیٹس میں دستیاب ہو جاتی ہیں JBake انجن میں کسی تبدیلی کے بغیر۔

ترقیاتی تصنیف

@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

بہترین طریقے

فائلوں کی تنظیم

  • ایک فائل = ایک پروجيکت : کئی پروجيكتس کو مخلوط کرنے سے بچنا

  • مخصوص فولڈر میں تصاویر :`assets/img/portfolio/nom-projet/`

  • منسجم نامenклатура : تحقیق اور مرامتیں کو آسان بناتی ہے

  • Versioning Git : تبدیلیوں کا مکمل تعقیب

محتوى کی منیجمنٹ

  • ڈیافالٹ ڈرافت کی حیثیت : صرف جب Tayyār ho تو shāyir karein

  • منتشر ہونے سے قبل کا جائزہ : جائزہ معیار اور رازداری

  • مکمل متا ڈیٹا : تمام ذاتی فیلڈز پر بھریں

  • امیر روایت پر مبنی مواد : میتا ڈیٹا تک خود کو محدود نہ کریں

عمل

  • تصاویر کو بہتر بنانا : کمپریشن commit سے پہلے

  • پاجینیشن اگر ضروری ہو : اگر >20 پروجیکٹ

  • لاizi لودنگ : گیلریوں کی تصاویر ضرورت کے مطابق لوڈ کی جاتی ہیں

  • براؤزر کیش : ایسٹس کے لیے مناسب ہیڈرز

نتیجہ

یہ معماریت اجازت دیتی ہے:

  • استعمال کی سادگی : پروجیکٹ شامل کریں = متنی فائل بنائیں

  • لچک : نئے خصوصیات کے ذریعے قابل تمدد

  • قابل نگہداری : محتوا اور پیشگی کی جدائی

  • پیروی : ورژننگ Git کامل

  • khud-kaari : build aur tanseeb mustamer mumkin

AsciiDoc کی انتخاب، باقی ویب سائٹ کے ساتھ ہم آہمی (مطابقت) برقرار رکھتی ہے، اور پیشہ ورانہ پورٹ فولیو کے لئے ضروری میٹی ڈیٹا کی زادتی بھی فراہم کرتی ہے۔

متعلقہ مضامین