Maven プラグイン

Maven プラグイン

Java・Spring Boot 開発者は、自分のプロジェクトに bx-sites のサイトを 追加するために CommandBox やシステム全体への BoxLang インストールを 必要としません - io.boxlang:bxsites-maven-plugin Maven プラグインは、 初回実行時に必要なもの（BoxLang ランタイムと bx-sites 本体）をすべて ローカルキャッシュにダウンロードします。前提条件は JDK 21 だけです。 Gradle プラグイン の Maven 版に相当し、どちらの プラグインも同じ基盤ロジックをラップしているため、verb のカバレッジと 挙動は両方のビルドツールで同一に保たれます。

ステータス: バージョン1.0未満で、まだ Maven Central には公開されて いません - ソースコードと現時点のビルド/テスト手順は bx-sites リポジトリの maven-plugin/ を参照してください。このページは公開後の動作を説明しています。以下の メカニズムはすでに実装され検証済みですが、まだ Maven Central の 座標として利用できるわけではありません。

クイックスタート

<build>
  <plugins>
    <plugin>
      <groupId>io.boxlang</groupId>
      <artifactId>bxsites-maven-plugin</artifactId>
      <version>&lt;version&gt;</version>
    </plugin>
  </plugins>
</build>

mvn bxsites:new     # docs/ + bxsites.yaml を生成
mvn bxsites:build   # docs/**.md を site/ にレンダリング
mvn bxsites:serve   # ビルドしてライブリロード付きでローカル配信

短縮形の bxsites:<goal>（動作確認済み）を使うには、上記の <plugin> ブロックが <pluginManagement> だけでなく、具体的に <build><plugins> の下に宣言されている必要があります - それによって 現在のプロジェクトで io.boxlang が解決可能な goal プレフィックスとして 登録されます。そこに宣言されていない場合は、完全修飾形式を使ってください: mvn io.boxlang:bxsites-maven-plugin:build。

デフォルト設定であれば、これ以上の設定は不要です - プラグインが コンテンツディレクトリ（docs/、なければ src/）と出力ディレクトリ （常に <projectRoot>/site/）を自動的に検出します。サイト自体の見た目、 テーマ、ナビゲーション、その他すべての設定はプロジェクトルートの bxsites.yaml/.toml/.json で完全に制御されます。 設定 に記載されているとおりで、プラグインはこの スキーマを一切複製せず、bx-sites を自分のビルドからどのように・ いつ実行するかだけを担います。

Goal

各 goal は初回実行時に、自分で必要なものをプロビジョニング （ダウンロード/キャッシュ）します - Gradle プラグインとは異なり、事前に 実行すべき別個の「provision」goal はありません。

デフォルトでは、どの goal も Maven のライフサイクルフェーズに紐付けられ ていません - 明示的に実行してください。bxsites:build を自動実行したい 場合は、<executions> ブロックで自分でバインドしてください。例えば pre-site に紐付けるのは、Maven 自身の site ライフサイクルとの 自然な組み合わせです。

設定

<plugin>
  <groupId>io.boxlang</groupId>
  <artifactId>bxsites-maven-plugin</artifactId>
  <configuration>
    <projectRoot>${project.basedir}</projectRoot>
    <boxlangMiniserverVersion>1.18.0-snapshot</boxlangMiniserverVersion>
    <bxSitesVersion>1.0.0-snapshot</bxSitesVersion>
    <boxlangHomeDir>${project.build.directory}/bxsites/boxlang-home</boxlangHomeDir>
  </configuration>
</plugin>

どのパラメータにも適切なデフォルト値があり、新規プロジェクトでは どれも設定する必要はありません。出力ディレクトリはここでは一切設定 できません - bx-sites 自体が <projectRoot>/site/ に固定しているため、 実際には反映されない設定項目を用意する代わりに、プラグインがそれを 導出するだけです。

ビルドの Staleness チェック

Maven には Gradle のような組み込みの増分ビルドエンジンがないため、 bxsites:build は独自の軽量なチェックを実装しています - コンテンツ ディレクトリ配下（および存在すれば設定ファイル）の最新の更新時刻 （mtime）と、<projectRoot>/site/ にすでに存在する最新の更新時刻を 比較します。何も新しくなければ、goal はスキップする旨をログに記録し、 bx-sites を一切再呼び出しせずに終了します。それでも強制的にリビルド するには:

mvn bxsites:build -Dbxsites.build.forceRebuild=true

まだ実装されていないもの

• Spring Boot ドキュメント生成（OpenAPI、Javadoc、コントローラースキャン）- 計画中。
• bxsites:serve のライブ出力ストリーミング - 現在は出力をバッファリングし30分のタイムアウトを適用していますが、どちらも無期限に実行され続けるべき goal としては誤った挙動です。

Gradle 側の対応物については Gradle プラグイン の ガイドを参照してください - どちらのプラグインも同じ基盤ロジックを ラップしているため、verb のカバレッジと挙動は両方のビルドツールで 同一に保たれます。

BoxLang ドキュメント生成

bxsites:docbox は DocBox から BoxLang/CFML の API リファレンスを生成します。対象は .bx/.cfc クラスをソースに含む JVM プロジェクトです。Spring Boot 系のジェネレーターと異なり、JVM 内で動く ジェネレーターではなく docbox verb の薄いラッパーです。実装は BoxLang 側にあり、両方のビルドツールが同じ実装を呼ぶため、実装がずれることは ありません。実際に設定したオプションだけが渡され、それ以外は bxsites.yaml の内容に従います。 DocBox APIリファレンス を参照してください。用意された BoxLang ランタイムに bx-docbox モジュールが必要です。

ColdBox 用のタスクは意図的にありません。 ColdBox アプリケーションは CommandBox でビルド・実行するものであり、Maven で扱うものではないため、 bxSites coldbox は bx-sites CLI の役割のままです。