はじめに

モジュールをインストールし、プロジェクトをスキャフォールドして、最初のサイトをビルドします。

はじめに

前提条件: BoxLang のインストール

以下はすべて、BoxLang ランタイム自体がすでにマシンにインストールされて いることを前提としています - install-bx-module は既存のインストール にモジュールをインストールする BoxLang 自身の CLI コマンドであり、 CommandBox の box install も実行対象となる BoxLang エンジンがすでに 存在している必要があります。まだ BoxLang をインストールしていない場合は、 以下のいずれかの方法で先にインストールしてください:

• クイックインストーラー（単一バージョン、最も手軽に始められます）:

  curl -fsSL https://install.boxlang.io/ | bash

• または BVM（BoxLang Version Manager。複数の BoxLang バージョンを 並行してインストールし、切り替えられるようにします）:

  curl -fsSL https://install-bvm.boxlang.io/ | bash
  bvm install latest && bvm use latest

Windows 版と Homebrew 版のインストーラー、および BVM コマンドの完全な リファレンスは、 BoxLang 公式のインストールドキュメント に掲載されています。

インストール

BxSites は、Markdown レンダリングに bx-markdown、 HTML エンコードに bx-esapi、 bxsites.yaml の読み込みに bx-yaml、 レスポンシブ画像パイプライン（レスポンシブ画像 を参照）に bx-image を必要とします - これら4つはすべて box.json の依存関係として自動的にインストールされるため、 bx-sites 自体をインストールするコマンドだけで済みます。BoxLang 独自の OS バイナリインストーラーを使う場合:

install-bx-module bx-sites

または CommandBox を使う場合:

box install bx-sites

どちらの方法でも box.json の boxlang.executable を参照し、PATH 上 （~/.boxlang/bin）に bxSites スクリプトを配置します。そのため、以下のコマンドは いずれも短い単独コマンドとして実行できます:

bxSites <verb> [options]

または、BoxLang は使えるがその PATH シムが設定されていない環境（CI ランナー、 インストールではなく手動で登録したモジュールなど）でも - どちらの形式もまったく 同じことを実行します:

boxlang bxSites <verb> [options]

このガイドの以降では短縮形を使用します。

プロジェクトのスキャフォールド

bxSites new my-docs
cd my-docs

以下の構造が作成されます:

my-docs/
├── docs/
│   ├── assets/
│   └── index.md
└── bxsites.yaml

--theme=material や --theme=tailwind で別のデフォルトテーマを指定してスキャフォールドでき、 --name="My Project Docs" を渡せば最初からサイト名を設定できます - 省略した場合、new はターゲットディレクトリ名からサイト名を導出します。

設定ファイルの形式

bxsites.yaml はデフォルトかつ推奨の形式です - 特に指定がない限り new はこの形式を スキャフォールドし、このガイドと 設定 の例もすべてまずこの形式で 示されます。bxsites.json も完全にサポートされており、そちらを好むプロジェクトでは --format=json を渡してスキャフォールドするか、自分で手書き/リネームするだけで構いません。 ConfigLoader は bxsites.yaml/.yml/.json のうち実際に存在するものをこの順序で解決するため、 切り替えに他の設定は一切必要ありません。両方の形式の完全なキーリファレンスは 設定 を参照してください。

GitBook のコンテンツがある場合は、bxSites migrate --source=/path/to/export で GitBook エクスポートをそのまま docs/ に変換できます - 詳しくは GitBook からの移行 を参照してください。 変換が済んだら ビルド まで読み飛ばしてもかまいません。

ページの追加

docs/ 配下のすべての .md ファイルがページになります。フォルダのネストがそのままナビゲーションのネストになります:

docs/
├── index.md              -> /
├── guides/
│   ├── index.md          -> /guides/
│   └── deployment.md     -> /guides/deployment/

（大規模なサイトでは、明示的な nav を使ってこの推定順序やグループを完全に上書きできます。 nav を参照してください。）

ページ間のリンク

別のページへのリンクは mkdocs と同様に、相手の .md ソースへのファイル相対パスを使います - まるでディスク上で2つのファイルが隣り合っているかのように（実際そうなので）:

[デプロイ](guides/deployment.md) を参照するか、そのガイドから
[はじめにに戻る](../getting-started.md#ページの追加) ことができます。

BxSites はビルド時にすべてのリンクをビルド後のキレイな URL に書き換えます （guides/deployment.md → /guides/deployment/index.html、アンカーとクエリ文字列を保持）。 これは リンク元 ページ自身のフォルダを基準に解決されます - ../ や兄弟参照は、 他の相対パスを解決するのとまったく同じように機能します。これは、ビルドされたサイトではなく GitHub 上で直接ファイルを読んだ場合でもリンクが機能し続ける理由でもあります - どちらの場合でも、実在するファイルへの本物の有効な相対パスだからです。 絶対 URL、mailto:、すでに / で始まるリンクはそのまま保持されます。

Markdown としてページをダウンロード

ビルドされた各ページには、元の .md ソースも一緒に公開されます （docs/guides/deployment.md は site/guides/deployment.md としてコピーされ、 site/guides/deployment/index.html の隣に置かれます）- ページ自体には 「Edit this page」の隣に「Markdown をダウンロード」リンクが表示されます。 設定不要で常に有効です。

これは llms.txt と同じ動機によるものです - 人間（あるいは LLM）が、レンダリング済みの HTML をスクレイピングする代わりに、 ページの生の Markdown を直接取得できます。また docs/ ツリー全体が 1:1 でミラーされるため、 この方法で読んでもページ自身の相対リンクは機能し続けます。

各ページは小さなフロントマターブロックから始めることができます:

---
title: デプロイ
order: 2
hidden: false
description: ビルドした BxSites サイトのデプロイ方法。
tags: [ガイド, デプロイ]
icon: 🚀
summary: サイトを公開するために必要なすべてのこと。
ogImage: assets/deployment-card.png
toc: true
---

# デプロイ

コンテンツをここに。

• title - ナビゲーションやページタイトルを上書きします（省略時はファイル名から導出）
• order - ナビゲーション内の兄弟ページの並び順を制御します（小さい値が先、省略されたページはアルファベット順で最後になります）
• hidden - true にするとナビゲーションと検索から除外されますが、ビルドからは除外されません
• description - このページのソーシャルカード/メタ説明（ogImage を参照）。省略時はサイト設定の全体 description にフォールバック
• tags - このページのタグ配列。タイトル下にクリック可能なバッジとして表示され、 サイト全体の /tags/ インデックスページに収集されます（少なくとも1ページに タグが付くまではこのページ自体ビルドされません）。一致するクエリに対する 検索の関連度も高めます
• icon - ページタイトルとナビゲーションエントリの横に表示されます - 単純な絵文字、 またはバンドルされたライブラリの名前付きアイコン（rocket、lucide:rocket、 tabler:rocket、プロジェクト独自の custom:my-icon）を指定できます。 アイコン を参照してください
• summary - タイトルの下に表示される1行のリードイン（ページ自体には レンダリングされないメタタグ専用の description とは別物です）
• ogImage - このページのソーシャルカード画像を上書きします - ogImage を参照してください
• toc - false にすると、見出しが2つ以上あっても（通常はこれが表示のトリガーです） このページ自身の「このページの内容」目次を非表示にします - フローティング TOC を 自分のコンテンツと競合させたくないランディング/ヒーローページに便利です。 デフォルトは true です

フロントマターの値には、インラインリスト（tags: [a, b, c]）、YAML 形式のブロック リスト（tags: の後にインデントされた - item 行を続ける）、複数行値のための >/| ブロックスカラーを使用できます - ただしこれは小さな自作パーサーであり完全な YAML ではないため、ネストしたオブジェクト/マップはサポートされません。

ビルド

bxSites build

docs/ のすべてのページを site/ の静的サイトとしてレンダリングします。静的ファイルを配信できる場所であればどこにでもホストできます。

ローカルで配信

bxSites serve

プロジェクトをビルドし、http://127.0.0.1:8080/ で site/ を配信します。 docs/、bxsites.yaml/.json のサイト設定、またはプロジェクトレベルの theme/ オーバーライドを保存するたびに自動的に再ビルドされ、ブラウザも自動的にリロードされます。 バインドの変更には --port=3000 や --host=0.0.0.0 を使用します。

クリーン

bxSites clean

docs/ ソースを変更せずに site/ とビルドキャッシュを削除します。