建築的ビジョン

指導原理

アーキテクチャは、*関心の分離*という原則に基づいています :

  • Contenu : 構造化されたAsciiDocファイル(メタデータが豊富)

  • プレゼンテーション : テンプレート Thymeleaf 再利用可能

  • データ : JBake によって AsciiDoc の属性から自動抽出されたモデル

  • Style : ビジュアルの一貫性のための Bootstrap 5

戦略的な選択 : ポートフォリオ用のAsciiDoc

なぜ AsciiDoc ですか?

基準 利点

整合性

ブログ記事と同じフォーマット

メタデータ

構造化および拡張可能な属性 (project-*)

保守性

シンプルなテキスト編集、Gitでバージョン管理可能

�柔軟性

�豊富なコンテンツ(表、コード、画像)を含むことがあります

テンプレーティング

JBakeは自動的にThymeleafの属性を抽出します

データモデル

各ポートフォリオプロジェクトはAsciiDocドキュメントです:

  • ヘッダーのメタデータ : 構造化された情報 (クライアント, 期間, テクノロジー, など)

  • ドキュメント本文 : ナラティブな説明, 課題, 解決策, 結果

  • カスタム属性 : プレフィックス付き`project-*`自動抽出のために

Diagram

詳細なユースケース

UC1 : ポートフォリオにアイテムを追加する

定格フラックス

Diagram

作成するファイルのテンプレート

開発者は作成します`content/portfolio/nom-projet.adoc`標準化された構造:

  • すべての必須属性を備えたヘッダー

  • 標準化されたセクション (コンテキスト、課題、ソリューション、結果)

  • 画像の一貫した命名法

検証ポイント

  • 必須属性は存在します (jbake-type, jbake-status, project-thumbnail)

  • 参照されている画像が存在する中に`assets/img/portfolio/`

  • JBakeのビルドはエラーなく成功します

  • プロジェクトがポートフォリオページに表示されます

  • プロジェクトの個別ページが正しく表示されます

UC2 : ポートフォリオから要素を削除

名義フラックス

Diagram

代替戦略:アーカイブ

完全に削除する代わりに、フォルダを作成することが可能です`content/portfolio/archive/`:

  • ファイルを削除する代わりに移動する

  • 簡単に復元できる

  • Gitの履歴をもっと分かりやすく保つ

リソースのクリーンアップ

  • �孤児画像を確認する中に`assets/img/portfolio/`

  • 他のプロジェクトで参照されていない画像を削除

  • JBakeのキャッシュをクリアして、幽霊参照を避けてください。

UC3 : 下書き(非公開)に設定

定格フラックス

Diagram

可能な状態

Diagram

典型的な使用例

  • 作成中のプロジェクト : ドラフトで作成し、準備ができたら公開する

  • Projet confidentiel temporairement : 顧客の合意が得られるまでドラフト状態に保つ

  • 主要アップデート : ドラフトに切り替え、編集し、再公開

  • A/B testing : 下書きで複製し、テストし、最良のバージョンを公開する

テンプレーティングアーキテクチャ

再利用可能なテンプレートの戦略

Diagram

データ抽出パターン

JBakeは、AsciiDocの属性をThymeleafでアクセス可能なプロパティに自動的に変換します。

Diagram

命名規則

  • プロジェクト属性 : プレフィックス`project-*` (ex: project-client, project-tech-stack)

  • ファイル : kebab-case (例:`ecommerce-platform.adoc`)

  • Images : プロジェクト名プレフィックス(例:ecommerce-platform-thumb.jpg)

  • テンプレート : 機能的な名前 (例:`project-card.html`, tech-badge.html)

公開ワークフロー

開発パイプライン

Diagram

環境

環境 使用 受け入れられたステータス

ローカル

開発とプレビュー

下書き, 公開済み

ステージング

本番前検証

publishedのみ

生産

公共サイト

公開済みのみ

拡張性

新しい属性の追加

データモデルを充実させるには、単純にプレフィックス付きの新しい属性を追加`project-*`:

  • `project-awards`賞と表彰

  • project-testimonial: クライアント見積もり

  • project-team-size: チームサイズ

  • project-budget-range: 予算範囲

これらの属性は、JBakeエンジンを変更せずにテンプレート内で自動的に利用可能になります。

高度な分類

Diagram

ベストプラクティス

ファイルの整理

  • 1 ファイル = 1 プロジェクト : 複数のプロジェクトを混ぜないでください

  • 専用フォルダ内の画像assets/img/portfolio/nom-projet/

  • 一貫した命名規則 : 検索と保守を容易にする

  • Versioning Git : 変更の完全な追跡

コンテンツ管理

  • デフォルトの下書きステータス : 公開するのは準備ができたときだけ

  • 公開前レビュー : 品質と機密性の確認

  • 完全なメタデータ : すべての関連フィールドを入力してください

  • 豊かなナラティブコンテンツ : メタデータに限定しない

パフォーマンス

  • 画像を最適化 : コミット前の圧縮

  • 必要に応じたページネーション : 20プロジェクト以上の場合

  • Lazy loading : ギャラリーの画像は必要に応じて読み込まれます

  • ブラウザキャッシュ : アセット用の適切なヘッダー

結論

このアーキテクチャは次のことを許可します :

  • 使いやすさ : プロジェクトを追加 = テキストファイルを作成

  • 柔軟性 : 新しい属性を通じて拡張可能

  • 保守性 : コンテンツとプレゼンテーションの分離

  • トレーサビリティ : Gitの完全なバージョン管理

  • 自動化 : ビルドとデプロイの継続的な可能性

AsciiDocの選択は、サイトの他の部分との一貫性を保ちながら、プロフェッショナルなポートフォリオに必要なメタデータの豊かさを提供します。

関連記事