ドキュメントサイトを作成する
ドキュメントは、説明対象のコードのそばに置くのが理想です。執筆者はMarkdownを好み、レビュアーはプルリクエストで変更を確認したいと考え、リリースにはドキュメントも同じコミットで含めるべきです。一方、WordPressでは投稿をデータベースに保存します。検索、パーマリンク、リビジョン、エディターがそこにあるためです。
Blockstudioページコレクションは、この2つをつなぎます。Markdownファイルのフォルダーが、独自の投稿タイプ、URLベース、親子階層を持つ実際のWordPress投稿の集合になります。layout.phpファイルは、同じデータから作られたナビゲーションとともに、コレクション内のすべてのページを表示します。ファイルが信頼できる情報源であり続け、明示的な同期コマンドでデータベースに書き込みます。
このガイドでは、acmeというテーマ向けの小さなドキュメントセクションを、マニフェスト、Markdownページ、変更履歴を生成するローダー、同期、サイドバーと前後リンク付きのレイアウトの順に作成します。
作成するもの
theme/
└── pages/
└── docs/
├── pages.json
├── layout.php
├── loader.php
├── index.md
├── getting-started.md
├── data/
│ └── releases.json
└── guide/
├── index.md
├── install.md
└── configure.md
同期後、コレクションから次のURLにアクセスできます。
| ソース | 公開URL |
|---|---|
index.md |
/docs/ |
getting-started.md |
/docs/getting-started/ |
guide/index.md |
/docs/guide/ |
guide/install.md |
/docs/guide/install/ |
guide/configure.md |
/docs/guide/configure/ |
| ローダーのエントリー | /docs/changelog/ |
ステップ1:コレクションのマニフェスト
コレクションはpages/内のフォルダーで、pages.jsonマニフェストを含みます。pages/docs/pages.jsonを作成します。
{
"collection": "docs",
"title": "Documentation",
"postType": "acme_docs",
"postTypeArgs": {
"label": "Docs"
},
"defaults": {
"postStatus": "publish",
"templateLock": "contentOnly"
}
}
collectionはコレクションのスラッグで、公開URLベースになります。postTypeを指定すると、コレクション内のすべてのページに専用の投稿タイプが割り当てられ、管理画面で通常のページと混在しません。その投稿タイプがまだ存在しない場合は、Blockstudioが登録します。登録時のデフォルト設定は、公開、階層あり、RESTAPIで利用可能、タイトル、エディター、ページ属性、サムネイル、抜粋、リビジョンに対応し、リライトスラッグはコレクションのスラッグと同じです。postTypeArgsはこれらのデフォルト設定にマージされるため、このマニフェストでは管理画面のラベルだけを変更しています。
defaultsは、コレクション内のすべてのページにページプロパティを適用します。ここでは同期時にすべてのページを公開し、コンテンツのみ編集可能にロックします。そのため、編集者はエディターで誤字を修正できますが、Markdownが定義する構造は変更できません。
ステップ2:Markdownでページを書く
コレクション内では、Markdownファイルがすべてページになります。ファイルの場所から識別情報が決まるため、フロントマターは省略できます。タイトル、並び順、後で読み込む追加データにはフロントマターを使います。
---
title: Introduction
order: 0
description: What Acme does and where to start.
---
# Introduction
Acme is a toolkit for building fast WordPress sites.
Start with [Getting Started](/docs/getting-started/).
---
title: Getting Started
order: 10
---
# Getting Started
Install the theme, then activate it under **Appearance > Themes**.
```bash
wp theme activate acme
```
ガイドセクションは独自のindex.mdを持つフォルダーで、隣接するページの親になります。
---
title: Guide
order: 20
---
# Guide
Task-focused walkthroughs for everyday work.
---
title: Installation
order: 10
---
# Installation
| Requirement | Version |
| --- | --- |
| WordPress | 6.7+ |
| PHP | 8.2+ |
---
title: Configuration
order: 20
---
# Configuration
Settings live in `acme.json` at the theme root.
> Changes apply on the next deploy.
Blockstudioは各ファイルから論理パスとページ名を導き出します。
| ファイル | パス | ページ名 |
|---|---|---|
index.md |
. |
docs-home |
getting-started.md |
getting-started |
docs-getting-started |
guide/index.md |
guide |
docs-guide |
guide/install.md |
guide/install |
docs-guide-install |
guide/install.mdとguide/install/index.mdは同じパスになるため、URLを変えずに、後からフラットなファイルとフォルダーを切り替えられます。
orderは兄弟ページを並べ替え、その値は投稿のメニュー順に使われます。順序が指定されていないページは、順序指定済みのページの後にタイトル順で並びます。上記のdescriptionのように、Blockstudioが認識しないフロントマターのキーは、ページのmeta配列に保持されます。
同期時にMarkdownはGitHub Flavored Markdownとして解析され、HTMLに変換された後、ネイティブブロックに解析されます。保存される投稿に含まれるのはブロックであり、Markdownテキストではありません。見出しには安定したアンカーが付与され、表はcore/tableに、引用はcore/quoteに、フェンス付きコードは言語クラスを保持するcore/preformattedブロックになります。これはインストールページの保存済みコンテンツです(前後の空白を除去)。
<!-- wp:heading {"level":1,"anchor":"installation"} --><h1 id="installation" class="wp-block-heading">Installation</h1><!-- /wp:heading -->
<!-- wp:table --><figure class="wp-block-table"><table>
<thead><tr><th>Requirement</th><th>Version</th></tr></thead>
...
</table></figure><!-- /wp:table -->
ステップ3:ローダーでページを生成する
書くより生成した方がよいページもあります。変更履歴がその一例です。リリースデータはすでに存在するため、Markdownに手作業でコピーすると内容がずれる原因になります。コレクションには、追加のページ定義を返すloader.phpを含められます。
リリースデータはコレクション内に置きます。
[
{ "version": "1.1.0", "date": "2026-09-01", "notes": "Added dark mode." },
{ "version": "1.0.0", "date": "2026-06-15", "notes": "First release." }
]
次に、そのデータから1つのMarkdownページを作成します。
<?php
$releases = json_decode(
(string) file_get_contents( __DIR__ . '/data/releases.json' ),
true
);
$markdown = "# Changelog\n";
foreach ( $releases as $release ) {
$markdown .= "\n## {$release['version']}\n\n";
$markdown .= "Released {$release['date']}. {$release['notes']}\n";
}
return array(
'pages' => array(
array(
'name' => 'docs-changelog',
'title' => 'Changelog',
'path' => 'changelog',
'order' => 90,
'content' => $markdown,
'contentType' => 'markdown',
),
),
);
ローダーは明示的な検出と同期の際に実行され、通常のページ表示時には実行されません。決定論的かつローカルに保ってください。テーマ内のファイルを読み込むのは問題ありませんが、リモートのAPIを取得してはいけません。同期がそのサービスに接続できるかどうかに左右されるためです。
ローダーのページには生成済みの印が付きます。ローダーの出力から項目がなくなると、次回の同期ではその投稿が孤立したものとして扱われ、blockstudio/pages/orphan_actionフィルターで処理されます。デフォルトではゴミ箱に移動します。
ローダーはpathsを返して、Markdownの他のローカルフォルダーを、任意のプレフィックスを付けてコレクションに追加することもできます。コレクションのルート外にあるフォルダーにはblockstudio/pages/allow_external_loader_pathフィルターが必要です。詳しい形式はコレクションローダーを参照してください。
ステップ4:同期する
実行を指示するまで、データベースには何も書き込まれません。
wp bs pages sync
このコマンドはすべてのページソースを検出し、acme_docs投稿タイプを登録して、投稿を作成または更新します。また、discovered、created、updated、unchanged、removed、failedの件数を含む概要行を出力します。変更がない状態で再実行すると、すべてのページが未変更として報告され、投稿への書き込みは発生しません。デプロイスクリプトで完全なレポートが必要な場合は--format=jsonを追加します。
同期後、投稿はファイルツリーを反映します。guide/install は guide の子で、後者はコレクションルートの子です。各投稿のメニュー順はフロントマターの order で決まります。コレクションのURLは、コレクションのスラッグと各ページの論理パスを組み合わせたものです:
/docs/
/docs/getting-started/
/docs/guide/
/docs/guide/install/
/docs/guide/configure/
/docs/changelog/
パーマリンクを再保存する必要はありません。登録済みのコレクション投稿タイプが変わると、コレクションのリライトルールは自動的にフラッシュされます。
同期をデプロイの一部にしてください。フロントエンドと管理画面のリクエストではページの検出を行わないため、新しいMarkdownファイルをコピーしてもwp bs pages syncを実行しなければ、以前のコンテンツが引き続き表示されます。
ステップ5:レイアウト
投稿は作成されましたが、どの投稿もテーマ標準の単一テンプレートで表示され、ナビゲーションもありません。pages.jsonの隣にlayout.phpを置くと、コレクション内のすべてのページのフロントエンド表示をラップできます。
<?php
$current = blockstudio_current_page();
$tree = blockstudio_page_tree( 'docs' );
// Flatten the tree in reading order for previous and next links.
$flat = array();
$flatten = function ( array $nodes ) use ( &$flatten, &$flat ) {
foreach ( $nodes as $node ) {
$flat[] = $node;
$flatten( $node['children'] );
}
};
$flatten( $tree );
$keys = array_column( $flat, 'key' );
$position = array_search( $current['key'] ?? null, $keys, true );
$previous = false !== $position ? ( $flat[ $position - 1 ] ?? null ) : null;
$next = false !== $position ? ( $flat[ $position + 1 ] ?? null ) : null;
$render_nav = function ( array $nodes ) use ( &$render_nav, $current ) {
echo '<ul>';
foreach ( $nodes as $node ) {
$is_current = ( $node['key'] ?? null ) === ( $current['key'] ?? null );
printf(
'<li><a href="%s"%s>%s</a>',
esc_url( $node['permalink'] ?? '#' ),
$is_current ? ' aria-current="page"' : '',
esc_html( $node['title'] )
);
if ( array() !== $node['children'] ) {
$render_nav( $node['children'] );
}
echo '</li>';
}
echo '</ul>';
};
?>
<div class="docs">
<nav class="docs-sidebar" aria-label="Documentation">
<?php $render_nav( $tree ); ?>
</nav>
<article class="docs-content">
<?php echo blockstudio_page_content(); ?>
<nav class="docs-pager" aria-label="Previous and next">
<?php if ( $previous ) : ?>
<a rel="prev" href="<?php echo esc_url( $previous['permalink'] ?? '#' ); ?>">
<?php echo esc_html( $previous['title'] ); ?>
</a>
<?php endif; ?>
<?php if ( $next ) : ?>
<a rel="next" href="<?php echo esc_url( $next['permalink'] ?? '#' ); ?>">
<?php echo esc_html( $next['title'] ); ?>
</a>
<?php endif; ?>
</nav>
</article>
</div>
blockstudio_page_tree('docs')はコレクションをネストされたノードとして返します。order、続いてタイトル順に並び、各ノードの子はchildrenに格納されます。ここでは、導入ページがルートとなり、その下にほかのページがあります。各ノードにはkey、title、path、permalinkが含まれます。この順序でツリーを平坦化すると閲覧順になり、前後リンクに必要な情報が得られます。
blockstudio_page_content()は、WordPressがthe_content経由でレンダリングするページ本文を出力します。省略するとコンテンツは非表示になります。サイトのhttps://example.comでの/docs/guide/install/では、レイアウトは次のようにレンダリングします(抜粋):
<nav class="docs-sidebar" aria-label="Documentation">
<ul><li><a href="https://example.com/docs/">Introduction</a><ul>
<li><a href="https://example.com/docs/getting-started/">Getting Started</a></li>
<li><a href="https://example.com/docs/guide/">Guide</a><ul>
<li><a href="https://example.com/docs/guide/install/" aria-current="page">Installation</a></li>
<li><a href="https://example.com/docs/guide/configure/">Configuration</a></li>
</ul></li>
<li><a href="https://example.com/docs/changelog/">Changelog</a></li>
</ul></li></ul>
</nav>
...
<a rel="prev" href="https://example.com/docs/guide/">Guide</a>
<a rel="next" href="https://example.com/docs/guide/configure/">Configuration</a>
このレイアウトは、メインループ内の単一ページに対するフロントエンドリクエストでのみ実行されます。保存済みのpost_contentは変更せず、エディターのキャンバスもラップしません。パスは同期された各投稿に保存され、ページのフィンガープリントにも含まれるため、レイアウトを編集すると次回の同期で反映されます。
PHPでコレクションデータを読み込む
レイアウトヘルパーはBlockstudio\Pagesクラスを薄くラップしたものです。テンプレート、ブロック、プラグインのいずれでも使えます。
| ヘルパー | クラスメソッド | 戻り値 |
|---|---|---|
blockstudio_pages('docs') |
Pages::pages('docs') |
ページキーをキーにした、ソート済みコレクションページのフラットなリスト |
blockstudio_page_tree('docs') |
Pages::tree('docs') |
childrenを持つネストされたノード |
blockstudio_page_children('docs-guide', 'docs') |
Pages::children('docs-guide', 'docs') |
1ページの直接の子ページ |
blockstudio_page_collection('docs') |
Pages::collection('docs') |
マニフェストのコレクションデータ |
blockstudio_current_page() |
Pages::current_page() |
レンダリング中のページ、またはnull |
Pages::get_page('docs-guide-install') |
名前で指定した1ページ |
ページ配列には、同期済みのpost_id、permalink、name、key、title、path、order、collection、postTypeとmeta配列が含まれます。フロントマターの追加項目はmetaに格納されるため、レイアウトから導入ページの概要を出力できます。
<?php $summary = $current['meta']['description'] ?? ''; ?>
フロントエンドのリクエストでは、これらの関数は同期済みの投稿と、前回の同期で保存された設定を読み込みます。Markdownファイルは読み込まないため、ファイルシステムへの処理は発生しません。フロントエンドで利用できるのは公開済みのページのみです。
ツール向けの生のMarkdown
ページはMarkdownファイルから生成されるため、Blockstudioは元のソースも提供できます。.md拡張子を付けてページをリクエストします。たとえば/docs/guide/install.mdのように指定するか、通常のURLにAccept: text/markdownを送信します。レスポンスではフロントマターが省略され、正規のLinkヘッダーとともにHTMLページへの参照が示されます。検索インデクサー、アシスタント、その他のプレーンテキストを扱うツールに便利です。ローダーのインラインコンテンツから生成されたページにはソースファイルがないため、.mdレスポンスはありません。
フィルターを1つ使って無効にできます。
add_filter( 'blockstudio/pages/serve_markdown', '__return_false' );
ヒント
パスで構造を表す。 ファイルを移動すると、パス、親ページ、URLも次回の同期で更新されます。pathフロントマターを使うのは、URLをファイルの場所と異なるものにする場合だけにしてください。
ページに追加情報が必要な場合は、page.jsonとMarkdownを組み合わせる。 page.jsonとindex.mdを持つフォルダーでは、JSONでpostIdやtemplateLockなどのページプロパティを、Markdownでコンテンツを管理します。index.mdのフロントマターは、同じ項目のpage.json値より優先されます。
エディターではなく、ファイルに書き込みます。 templateLock: "contentOnly"を使うと、
エディターでテキストを直接修正できますが、変更したソースを次に同期すると、
ファイルの内容で保存済みのコンテンツが上書きされます。ドキュメントを書く場所はMarkdownと
考えてください。エディターで管理するページは、代わりにpage.json内に
"sync": falseを設定します。これにより通常の同期ではスキップされ、
Blockstudio\Pages::force_sync()が一度だけ作成します。
投稿タイプの変更は安全です。 コレクションをpageから
カスタム投稿タイプに移行すると、保存済みの識別情報が一致する同期済み投稿はその場で移行されるため、投稿IDは維持されます。
次のステップ
- ページのリファレンス:すべての
page.jsonとpages.jsonプロパティ、ローダー、レイアウト、調整レポート。 - ファイルベースのページを作成する:テンプレートのロック、 ブロック編集モード、クライアントが編集するページのキー付きマージ。
- サイトエディターのテンプレートとパーツをファイルから作成: ヘッダー、フッター、テーマテンプレートにも同じファイル優先の方法を適用します。