ライブプレビュー

ライブプレビューは、サイト側に実装したプレビューページに、pitcmsで編集中のコンテンツを流し込むことで、即座に実際のサイトデザインでプレビューを確認できる機能です。

公開前に「サイト上でどう見えるか」を即座に確認しながら編集を進められます。

仕組み

ライブプレビューは、pitcms が提供する Draft API を通じて動作します。

1. 編集画面で「プレビュー」ボタンを押すと、サイト側に用意したプレビューページが別タブで開きます
2. プレビューページはサイト側で、pitcms の Draft API を呼び出して 編集中（コミット前）のコンテンツ を取得します
3. 取得した内容をサイトのデザインに流し込んで表示します
4. 編集を続けると、入力が止まったタイミングで内容が自動的に反映され、プレビューが更新されます

Draft API の認証トークンは pitcms がプレビューを開くときに URL の token パラメータで渡すため、サイト側でトークンを発行・保存する設定は不要です。

サイトへの設置

サイト側に プレビュー専用ページ を実装し、そのURLを pitcms.jsonc に設定するとライブプレビューが使えるようになります。

1. プレビューページを作る
2. pitcms から渡されるクエリパラメータを用いて Draft API を呼び出す
3. Draft API から取得したデータを用いてページを描画する
4. pitcms.jsonc のコレクションに preview.url（プレビューページのURL）を設定する

1. プレビューページを作る

サイトにプレビュー専用のページ（例: /preview）を用意します。pitcms は preview.url に設定されたページに、以下のようなクエリパラメータを付与して別タブで開きます。

https://example.com/preview?project=j57abc...&collection=news&slug=entry-abc123&branch=main&draft=k97xyz...&token=eyJ...&_r=1756900000000

プレビューページをローカル環境（http://localhost:4321/preview など）で開発・確認したい場合は、preview.url を書き換えずに済む 開発用プレビューモード を利用してください。

2. Draft API を呼び出す

プレビューページで、受け取ったクエリパラメータをもとに Draft API を呼び出します。

GET https://api.pitcms.net/api/preview/{project}/{collection}/{slug}?branch={branch}&draft={draft}&token={token}

認証は、pitcms から受け取った token をそのまま渡します。クエリ ?token= のほか、GET リクエストに Authorization ヘッダーを付けて渡すこともできます（URL にトークンを露出させたくない場合）。

Authorization: Bearer <token>

レスポンス（200）

{
	"slug": "entry-abc123",
	"collection": "news",
	"data": {
		"title": "お知らせのタイトル",
		"createdAt": "2026-01-01T00:00",
		"draft": false
	},
	"body": "本文のマークダウン文字列"
}

エラー

draft パラメータについて

pitcms は、編集画面で入力が止まるたびに、まだ保存（コミット）していない編集中の内容を ワーキングドラフト として一時的に保管します。ワーキングドラフトは Git のリポジトリとは別に pitcms 側で保持されるデータで、クエリパラメータの draft はその保管データを指すキーです。

Draft API に draft を渡すと、対応するワーキングドラフトの内容が返されます。これにより、保存前の入力内容をそのままプレビューに反映できます。draft を渡さない場合や、対応するワーキングドラフトが見つからない場合は、branch で指定したブランチにコミット済みの内容が返されます。

3. 取得したデータでページを描画する

Draft API から返ってきた data（frontmatter）と body（本文）を使って、サイトのデザインで描画します。

以下は、ブラウザ（クライアント）から直接 Draft API を呼び出して描画する例です。トークンは pitcms が実行時に渡す短命トークンなので、クライアントで扱っても問題ありません。サーバー側でレンダリングするサイト（SSR）でも、同じ流れをサーバー側で行うだけで実装できます。

<!-- プレビュー用ページ（例: /preview.html） -->
<div id="preview"></div>

<script type="module">
	const q = new URLSearchParams(location.search);
	const project = q.get('project');
	const collection = q.get('collection');
	const slug = q.get('slug');
	const params = new URLSearchParams({
		branch: q.get('branch') ?? '',
		draft: q.get('draft') ?? '',
		token: q.get('token') ?? ''
	});

	const res = await fetch(
		`https://api.pitcms.net/api/preview/${project}/${collection}/${slug}?${params}`
	);
	if (res.ok) {
		const entry = await res.json();
		// entry.data（frontmatter）と entry.body（本文）を使ってサイトのデザインで描画する
		document.querySelector('#preview').innerHTML = `
			<h2>${entry.data.title}</h2>
			<div>${entry.body}</div>
		`;
	}
</script>

4. pitcms.jsonc に preview.url を設定する

pitcms.jsonc のコレクションに preview.url を追加すると、そのコレクションでライブプレビューが有効になります。値には、作成したプレビューページのURLを指定します。

{
	"collections": [
		{
			"name": "news",
			"path": "src/content/news",
			"extension": "md",
			"fields": [
				/* ... */
			],
			"preview": {
				// これを設定します
				"url": "https://example.com/preview"
			}
		}
	]
}

preview.url を設定したコレクションでは、コンテンツの編集画面に 「プレビュー」ボタン が表示されます。ボタンを押すと、プレビューページが別タブで開きます。

AIチャット編集での利用

preview.url を設定したコレクションでは、AIチャット編集でもライブプレビューが使われます。

AIがコンテンツを作成・更新する前に保存前の内容をプレビューとして用意し、チャット画面右上に 「プレビューを開く」 ボタンが表示されます。実際のサイトのデザインで内容を確認してから、反映を承認できます。プレビューで確認した内容がそのまま保存されます。

開発時の使い方（ローカルで確認する）

プレビューページを開発しているときは、まだ公開していないローカルのサイト（http://localhost:4321/preview など）で、実際の表示を確認しながら開発したくなります。

このために pitcms.jsonc の preview.url を localhost に書き換えてコミットする必要はありません。「プレビュー」ボタンは本番URL（preview.url）のままにしておき、開発時だけローカルURLで開くための機能があります。

設定

1. pitcms ダッシュボードの 設定 => プレビュー を開く
2. 「開発用プレビュー」をオンにする

使い方

オンにすると、各コンテンツの編集画面に 開発用URLの入力欄 と 「開発プレビュー」ボタン が表示されます。

1. 入力欄に自分のローカルのプレビューページURL（例: http://localhost:4321/preview）を入力する
2. 「開発プレビュー」ボタン を押すと、そのURLでプレビューが開く

• 入力したURLはブラウザに記憶されるので、毎回入力する必要はありません
• 通常の「プレビュー」ボタン（preview.url = 本番）と、「開発プレビュー」ボタン（ローカル）を使い分けられます