コンテンツブロック

コンテンツブロック

Markdown 拡張機能 のすべてに加えて、BX Sites は GitBook スタイルのコンテンツブロック群をサポートしています - それ自体便利であるだけでなく、 GitBook サイトのコンテンツを簡単に移行できる理由でもあります。それぞれが 同名の GitBook ブロックに直接対応しています。すべて同じ ::: name ... ::: コンテナ構文を使い（単独の行にある裸の ::: が、現在開いているブロックを 閉じます）、bxsites.json の設定は不要で、常に使用できます。ブロックは 別のブロックの中にネストできます（例えば、カードグループを含む展開可能 セクションなど）- それぞれが自身のコンテンツの中でさらにブロックがないか 再スキャンされます。

展開可能

コールアウトのアイコン/色を持たない、プレーンな折りたたみ可能セクションです - 折りたたみ可能な Admonition（???、Admonition を参照）とは異なります:

::: expandable "これは折りたたみ可能な Admonition と違いますか？"
はい - これにはタイプ/アイコン/色がなく、単なるプレーンな展開/折りたたみ
セクションです。`open="true"` を追加すると展開された状態で開始します。
:::

カード

リンクカードのグリッドで、それぞれが ::: cards ラッパーの中の独自の ::: card です - title、icon、image、href はすべて任意です （href のないカードは、クリックできないプレーンなカードとしてレンダリング されます）。icon はフロントマター/ナビの icon 値と同じ方法で解決されます - プレーンな絵文字、または同梱ライブラリの名前付きアイコン （icon="phosphor-duotone:rocket-launch"、icon="lucide:rocket" など） です - テーマ: アイコン を参照してください:

::: cards
::: card title="はじめに" icon="phosphor-duotone:rocket-launch" href="../getting-started.md"
インストール、スキャフォールド、最初のサイトのビルド。
:::
::: card title="テーマ" icon="phosphor-duotone:palette" href="themes.md"
組み込みテーマのカスタマイズ、または独自テーマの作成。
:::
:::

列

横並びのレイアウトです - ::: column は任意の width（プレーンな CSS の 長さ/パーセンテージ、例えば "40%"）を受け付けます。明示的な幅を持たない 列は、行を均等に分け合います:

::: columns
::: column width="60%"
広い方の列。
:::
::: column
狭い方の列。
:::
:::

ステッパー

番号付きで連結されたステップの連続です:

::: stepper
::: step "インストール"
`install-bx-module bx-sites`
:::
::: step "スキャフォールド"
`bxSites new`
:::
:::

ステップ自身が持つ任意の color 属性は、そのマーカーに 4 色のうちいずれか 1 つの意味的な色を付けます - デフォルト（color なし）、success、 warning、danger です - シーケンス内でのステップの位置とは独立しています:

::: stepper
::: step "データをバックアップ" color="success"
定型作業で、いつ実行しても安全です。
:::
::: step "任意: テレメトリを有効化" color="warning"
確信が持てない場合はスキップしてください。
:::
::: step "旧インストールを削除" color="danger"
元に戻せません - 上のバックアップが完了していることを必ず確認してください。
:::
:::

番号付きマーカー、接続線、そして上記 3 つの color パレットは、いずれも サイトの他の部分のパレットとは独立して、CSS カスタムプロパティで テーマ化できます - 色のカスタマイズ を参照してください。

ファイル

PDF、動画、その他のプロジェクトアセット向けのダウンロードカードです - src は theme.logo/フロントマターの ogImage がすでに解決されているのと 同じ方法で解決されます（docs/assets/ からの相対パス）:

::: file src="assets/spec.pdf" title="API 仕様"
:::

埋め込み

認識されたプロバイダー向けのレスポンシブ iframe 埋め込みです - 現時点では YouTube、Vimeo、CodePen、Spotify、Loom、Figma に対応しています。それ以外の URL は、どのみちレンダリングを拒否する iframe（ほとんどのサイトはフレーム 表示をブロックします）の代わりに、プレーンな「訪問 ↗」リンクカードに フォールバックします:

::: embed url="https://www.youtube.com/watch?v=dQw4w9WgXcQ" title="デモ"
:::

ページリンク

別のページへのリッチなプレビューカードです - href は通常の ページリンク と同じ、 ファイル相対の規約に従います。カードとは異なり、タイトル/アイコン/サマリは ターゲットページ自身のフロントマターから自動的に取得されるため、そのページが リネームされたりサマリが変更されたりしても同期が保たれます:

::: page-link href="../getting-started.md"
:::

リンクプレビュー

外部 URL 向けのリッチなプレビューカードです - ::: page-link と同じ カード形状ですが、このサイト自身のページではないリンクのためのもので、 タイトル/サマリを自動取得できるページがありません。すべてのフィールドは ディレクティブ自身の属性から取得されます: 必須なのは url だけで、title を省略すると裸の URL にフォールバックし、description/image はどちらも 任意です。これらを自動入力するためのビルド時のターゲット URL フェッチは ありません - check を内部リンクのみに 限定しているのと同じ理由がここにも当てはまり、遅い/到達不能なサードパーティ サイトがビルド時間に影響することは決してありません:

::: link-preview url="https://boxlang.io" title="BoxLang" description="動的でマルチパラダイムな JVM 言語。" image="https://boxlang.io/og.png"
:::

BoxLang

動的でマルチパラダイムな JVM 言語。

boxlang.io

更新履歴（changelog）

日付とタグ付けが可能な変更履歴リストです - ::: update は date="YYYY-MM-DD" と、任意のカンマ区切りの tags を受け付けます:

::: updates
::: update date="2026-01-15" tags="feature,fix"
ダークモードを追加し、フッターの整列バグを修正しました。
:::
::: update date="2026-01-01"
初回リリース。
:::
:::

::: updates ブロックを持つページは、bxsites.json の baseURL が完全な URL である場合（sitemap.xml と同じ要件です）、その隣に独自の feed.xml （RSS 2.0）も書き出されます - そのため、読者はそのページの更新履歴だけを 購読できます。

再利用可能なコンテンツ（インクルード）

::: include src="..." は、別のファイルの生の Markdown をその場所に 挿入します。上記のすべてのブロックとは異なり、これはウィジェットに包まれた 何かではなく、本物のページコンテンツ（見出し、段落、自身のネストした ブロック）になります - 複数のページで繰り返される警告/告知に便利です。 パーシャル自体は docs/includes/ の下に置いてください - assets// versions//i18n//blog/ と同じ予約済みフォルダの規約です。includes/ 配下のファイルは、決してそれ自体のページとしてビルドされず、ナビ/検索/ サイトマップ/タグにも一切現れません - 他のページに挿入されるためだけに 存在します:

docs/
├── index.md
├── includes/
│   ├── beta-notice.md
│   └── legal/
│       └── terms.md
└── guides/
    └── deep/
        └── setup.md

裸の src（先頭に ./ や ../ がないもの）は、インクルードする側の ページがどれだけ深くネストしていても、常に現在のツリー自身の docs/includes/ に対して解決されます - 上記の guides/deep/setup.md は、 index.md とまったく同じ src で、まったく同じファイルに到達します:

::: include src="beta-notice.md"

裸の src は includes/ 自身のサブフォルダを指すこともできます:

::: include src="legal/terms.md"

代わりに src の前に ./ や ../ を付けると、集約された includes/ フォルダに置くつもりのない、ページに隣接するフラグメントに到達できます - この形式は、通常のページリンクと同じ規約で、インクルードする側のページ 自身のディレクトリからのファイル相対で解決されます:

::: include src="../local-note.md"

バージョン/ロケールのツリーも同じ方法で独自の includes/ を持ちます - docs/versions/2.0/ 配下のページは、裸の src を docs/versions/2.0/includes/ に対して解決し、docs/i18n/es/ 配下の ページは docs/i18n/es/includes/ に対して解決します - それぞれのツリーの パーシャルは独自のものであり、メインツリーの docs/includes/ とは 共有されません。

インクルードされたファイルは、さらに別のファイルをインクルードできます （循環参照はビルド時に永久ループする代わりに BxSites.CircularInclude を送出します）。