JBake Architecture Portfolio - Vision and Use Cases
Published on 15 January 2026
Architectural Vision
Guiding principle
The architecture is based on the principle of separation of concerns:
-
Content: structured AsciiDoc files with rich metadata
-
Presentation: reusable Thymeleaf templates
-
Data: model automatically extracted by JBake from AsciiDoc attributes
-
Style: Bootstrap 5 for visual consistency
Strategic choice: AsciiDoc for the portfolio
| Criterion | Advantage |
|---|---|
Consistency |
Same format as blog posts |
Metadata |
Structured and extensible attributes ( |
Maintainability |
Simple text editing, Git versionable |
Flexibility |
Can contain rich content (tables, code, images) |
Templating |
JBake automatically extracts attributes for Thymeleaf |
Data model
Each portfolio project is an AsciiDoc document with:
-
Header metadata: structured information (client, duration, technologies, etc.)
-
Document body: narrative description, challenges, solutions, results
-
Custom attributes: prefixed`project-*`for automatic extraction
Detailed Use Cases
UC1: Adding an item to the portfolio
Nominal flow
Template of the file to create
The developer creates`content/portfolio/nom-projet.adoc`with a standardized structure:
-
Header with all required attributes
-
Standardized sections (Context, Challenges, Solutions, Results)
-
Consistent image naming
Validation points
-
Mandatory attributes are present (
jbake-type,jbake-status,project-thumbnail) -
Referenced images exist in`assets/img/portfolio/`
-
The JBake build succeeds without error
-
The project appears on the portfolio page
-
The individual project page displays correctly
UC2: Deleting an item from the portfolio
Nominal flow
Alternative strategy: archiving
Instead of permanent deletion, possibility to create an`content/portfolio/archive/`folder:
-
Move the file instead of deleting it
-
Allows for easy restoration
-
Keeps the Git history cleaner
Resource cleanup
-
Check for orphaned images in`assets/img/portfolio/`
-
Delete images not referenced by other projects
-
Clear JBake cache to avoid ghost references
UC3: Setting to unpublished (draft)
Nominal flow
Possible states
Typical use cases
-
Project in drafting : create as draft, publish when ready
-
Temporarily confidential project : set to draft until client agreement
-
Major update : set to draft, modify, republish
-
A/B testing : duplicate as draft, test, publish the best version
Templating Architecture
Reusable template strategy
Data extraction pattern
JBake automatically transforms AsciiDoc attributes into properties accessible in Thymeleaf:
Naming conventions
-
Project attributes : prefix`project-*` (ex:
project-client,project-tech-stack) -
Files : kebab-case (e.g.,
ecommerce-platform.adoc) -
Images : project-name prefix (e.g.,
ecommerce-platform-thumb.jpg) -
Templates : functional name (e.g.,
project-card.html,tech-badge.html)
Publication Workflow
Development pipeline
Environments
| Environment | Usage | Accepted status |
|---|---|---|
Local |
Development and preview |
draft, published |
Staging |
Pre-production validation |
published only |
Production |
Public site |
published only |
Extensibility
Adding new attributes
To enrich the data model, simply add new attributes prefixed`project-*`:
-
project-awards: Price and awards -
project-testimonial: Client quote -
project-team-size: Team size -
project-budget-range: Budget range
These attributes automatically become available in the templates without modifying the JBake engine.
Advanced categorization
Best Practices
File organization
-
One file = one project : avoid mixing multiple projects
-
Images in dedicated folder :`assets/img/portfolio/nom-projet/`
-
Consistent nomenclature : facilitates search and maintenance
-
Git Versioning : complete tracking of modifications
Content management
-
Draft status by default : publish only when ready
-
Review before publication : quality and confidentiality validation
-
Complete metadata : fill in all relevant fields
-
Rich narrative content : do not limit to metadata
Performance
-
Optimize images : compression before commit
-
Pagination if necessary : if >20 projects
-
Lazy loading : gallery images loaded on demand
-
Browser cache : appropriate headers for assets
Conclusion
This architecture allows:
-
Simplicity of use : adding a project = creating a text file
-
Flexibility : extensible via new attributes
-
Maintainability : separation of content/presentation
-
Traceability : complete Git versioning
-
Automation : continuous build and deployment possible
The choice of AsciiDoc ensures consistency with the rest of the site while offering the metadata richness necessary for a professional portfolio.