コンテンツへスキップ

コードで定義する完全なページ

テンプレートとMarkdownを、1つのコマンドでWordPressに同期できます。

ファイルからコレクションを作成

pages.jsonを定義すると、Blockstudioがその下にあるすべてのソースを検出します。ネストされたパスはネストされたページになり、既定値はコレクション全体に適用され、存在しない親ページは生成できます。

ドキュメント、ナレッジベース、ランディングページにコレクションを使えます。また、loader.phpを使って外部フォルダーをパスプレフィックスの下にマウントできます。

pages.jsonの横にlayout.php、またはlayout.tsxのようなレンダラーレイアウトを配置すると、コレクション内のすべてのページを1つのシェルで囲めます。サイドバーにはblockstudio_page_tree()を使います。

pages/docs/pages.json
{
  "collection": "docs",
  "title": "Documentation",
  "postType": "bs_docs",
  "defaults": {
    "postStatus": "publish",
    "templateLock": "contentOnly"
  }
}

明示的な同期

wp bs pages syncで変更が適用されます。変更のないページへの書き込みは発生しません。

Markdownソース

index.mdをfrontmatterとともに使うか、page.jsonをMarkdownコンテンツと組み合わせます。

生のMarkdown

MarkdownファイルページはURLに加えて.mdでも応答します。または、Accept: text/markdownの場合は通常のURLで応答し、HTMLに戻るcanonicalリンクを含みます。

コレクションローダー

外部のドキュメントフォルダーをパスプレフィックスの下にあるコレクションへマウントできます。

サイトコレクション

scope が site のpages.jsonは、URLや投稿行を変更せずに、ページツリー全体へ共通のデフォルトを適用して一覧表示します。

ナビゲーションヘルパー

blockstudio_page_tree()、blockstudio_page_children()、blockstudio_current_page()、blockstudio_page_content()を使って、サイドバー、ページャー、本文を構築します。

コレクションと投稿タイプ

コレクションでは、専用の階層型投稿タイプを登録できます。

テンプレートのロック

contentOnly、all、insertを使って、ページまたは個別のブロックをロックできます。

HTMLを書いてブロックを作成

<h1>、<p>、<ul>などの標準要素はコアブロックに対応します。それ以外のブロック名やネストの深さには<block>を使います。

Blockstudioはページレイアウト全体を解析し、実際に編集できるWordPressブロックに変換します。

index.php
<div>
  <h1 blockEditingMode="contentOnly">About Us</h1>
  <p>We build tools for WordPress developers.</p>
  <img src="/team.jpg" alt="Our team" />
</div>

<block name="core/columns">
  <block name="core/column"><h2>Our Mission</h2></block>
  <block name="core/column"><h2>Our Stack</h2></block>
</block>

コンポーネントでレンダリングされるページ

page.jsonでrenderをpage.tsxのようなエントリーとdata.phpローダーに設定すると、テーマまたはプラグインが登録したページレンダラーがページ全体を描画します。同期ではblockstudio/pageブロックが1つ保存され、ショートコードなどのWordPressコンテンツはそのスロットに残ります。

レンダラーが返すアセットにはブロックアセットと同じ処理が適用され、1回だけ出力されるため、プリレンダリングされたページにも含まれます。blockstudio.dev自体はコンポーネントページから構築されます。

pages/legal-notice/page.json
{
  "name": "legal-notice",
  "title": "Legal Notice",
  "slug": "legal-notice",
  "postStatus": "publish",
  "render": { "entry": "page.tsx", "data": "data.php" }
}

投稿のないルート

Blockstudio\Virtual_Routes::register()は、コンポーネントのリファレンスやカタログなど、投稿に紐づかないドキュメントを提供します。prefixとmatchを使えば、1つの登録でURL群全体に応答でき、nullを返すと、URLをWordPressに任せられます。

ルートはBlockstudioの出力バッファ内でレンダリングされるため、そのブロックにはアセットとTailwind出力が適用されます。urls内のパスは静的プリレンダリングのビルドに含まれ、Virtual_Routes::urls()がそれらをサイトマップ用に返します。

functions.php
add_action( 'init', function () {
    Blockstudio\Virtual_Routes::register(
        'components',
        function ( $component, string $rest ) {
            get_header();
            echo my_component_page( $component );
            get_footer();
        },
        [
            'prefix' => true,
            'match'  => fn ( string $rest ) => '' === $rest ? 'index' : my_component( $rest ),
            'title'  => fn ( $component ) => my_component_title( $component ),
            'urls'   => fn () => my_component_paths(),
        ]
    );
} );

必要なときに同期

ページファイルの変更がWordPressに反映されるのは、指示したときだけです。wp bs pages syncは変更されたソースをすべて適用し、キー付きのエディターコンテンツを保持し、ファイルがなくなったページを削除します。

フィンガープリントはマニフェスト、ローダー、レイアウト、ソースを対象とするため、変更のないページへの書き込みは発生しません。デプロイ時にPages::reconcile()を呼び出すと、機械可読なレポートが返されます。

ターミナル
# Apply changed sources, keep keyed edits
wp bs pages sync

# Replace managed content from the files
wp bs pages sync --authoritative

# Compare every page and report as JSON
wp bs pages sync --full --format=json

キー付きブロックがコンテンツを保持

任意のブロックにkeyを追加できます。次回の同期では、キー付きブロックはテンプレートの属性を既存のユーザーコンテンツとマージし、キーのないブロックは置き換えられます。

クライアントのコンテンツを保ったまま、デプロイをまたいで構造を変更できます。

index.php
<h1 key="title">About Us</h1>
<block name="core/cover" key="hero" url="/hero.jpg">
  <h2>Welcome to our company</h2>
  <p>Edit this content freely.</p>
</block>
<block name="core/columns" key="team">
  <block name="core/column"><h3>Our Team</h3></block>
</block>

テンプレートのロックと編集モード

"all"は変更を禁止し、"contentOnly"はテキスト編集を許可しながら構造をロックし、"insert"は追加・削除を許可せずに編集や並べ替えを許可します。

blockEditingModeで任意の要素を上書きし、ロックしたページの一部だけを編集可能にするか、個別のブロックを無効にできます。

index.php
<h1>Welcome to Our Product</h1>
<p>The best solution for your needs.</p>
<block name="core/cover" blockEditingMode="disabled" url="/static-banner.jpg">
  <p>Promotional banner</p>
</block>
<block name="core/group" blockEditingMode="default">
  <h2>Customizable Section</h2>
</block>

ファイルベースのサイトエディターテンプレート

templates/にtemplate.jsonとテンプレートを追加するか、parts/にpart.jsonを追加すると、ブロックテーマにファイルベースのwp_templateおよびwp_template_partソースが設定されます。

ページと同じ構文を使います。サイトエディターでのカスタマイズはリセットされるまで優先され、リセットするとファイルソースに戻ります。

templates/front-page/index.php
<block name="core/template-part" slug="header" />

<div>
  <h1>Welcome</h1>
  <block name="core/post-content" />
</div>

<block name="core/template-part" slug="footer" />

git内の選択したデータベースコンテンツ

wp bs content pullは、許可リストにある投稿、ターム、リレーション、宣言済みメタデータを持ち運び可能なファイルに出力し、pushはそれらを別の環境に適用します。宣言済みの参照、親、タームリレーションは、安定したUIDとして引き継がれます。

ページ同期で管理されている投稿はincludePageSyncManagedと連携できます。各ファイルには"bodyOwner": "page-sync"が含まれるため、Content Syncがメタデータを移行し、ページ同期が本文を保持します。

blockstudio.json
{
  "content": {
    "enabled": true,
    "id": "default",
    "path": "content",
    "postTypes": ["team_member"],
    "taxonomies": ["category"],
    "meta": {
      "include": ["_my_*"],
      "references": {
        "_thumbnail_id": { "kind": "attachment" },
        "_related_posts": { "kind": "post", "path": "*" }
      }
    },
    "media": "manifest"
  }
}

キー付きブロック

テンプレートを変更してもユーザーコンテンツを保持します。

編集モード

ページの既定値を設定し、個々の要素で上書きできます。

ブロックバインディング

ブロックを投稿メタに接続して、同期後もコンテンツを保持します。

投稿タイプテンプレート

templateForを使うと、その投稿タイプの新しい投稿すべてに適用するページのブロック構造を指定できます。

固定投稿ID

ページを削除して再同期すると、postIdによって同じIDが再利用されるため、メニューやリンクが引き続き機能します。

ひな形とロック

sync: falseとPages::force_sync()を使うと、編集者が管理するページを一度だけ作成します。Pages::lock()とunlock()を使うと、1つのページを同期対象から除外できます。

カスタムパーサーレンダラー

ビルダーとレンダラーのフィルターを使うと、ブロックタグをサードパーティ製ブロックのブロック配列に変換したり、コアブロックの書き出し方を変更したりできます。

要素のマッピング

HTML要素を別のブロックにマッピングし、要素の属性からブロックを選択して、段落のHTMLをコンテンツフィールドに割り当てます。

カスタム検出パス

フィルターを使うと、たとえばプラグインから、ページ、パターン、サイトエディターのテンプレート用にルートを追加できます。

論理的な検出ソース

プレビュー、オーバーレイ、生成されたテーマでは、1つのテーマフォルダーの代わりに、合成したファイル一覧をBlockstudioに渡せます。

安定した参照

宣言された投稿、ターム、添付ファイルへの参照は、プル時に移植可能なUIDになり、プッシュ時にローカルIDへ解決されます。

プッシュ前の状態

wp bs content statusは各エンティティの状態をunchanged、would-update、missing-db、conflict、locked、orphanedのいずれかで報告し、秘密情報のように見えるメタキーがあれば警告します。

検証済みで対象を限定したプッシュ

プッシュでは書き込み前に計画全体を検証し、ロックされたエンティティをスキップします。–dry-runは計画を表示し、–prune –yesはこのコンテンツセットのエンティティだけを削除します。

バージョン管理に対応

ページファイルをGitで管理し、環境間でデプロイします。

PHP API

ツリー、子要素、メタデータ、同期、ロック、IDにプログラムからアクセスできます。

Plus

公式拡張キット

プレミアムサイトテンプレート、AIシステム指示、会員限定Discordコミュニティ。買い切りで、アップデートは生涯無料です。

  • 500+のサイトテンプレート
  • AIシステム向け指示
  • 無期限アップデート
  • 非公開Discordコミュニティ