ものしり

第2部 使いこなす

第5章 コンテンツモデルとコンテンツ運用

コレクション、クエリ、メディア、多言語など、日々のコンテンツ運用を学ぶ。

読了の目安 約 43 分 ・ EmDash 1.3.1 / Astro 7 系(確認日 2026-10-29)

この章で学ぶこと

この章では、EmDash で「コンテンツを作り、公開し、サイトに表示し、運用し続ける」ための仕組みを順に見ていきます。

  • エントリ (entry) の作成・公開・予約公開・リビジョン・ゴミ箱という状態遷移
  • Astro のページからコンテンツを取り出すクエリ
  • タクソノミー (taxonomy)、リレーション (relation)、メニュー (menu)、ウィジェット (widget)
  • ページレイアウト、ブロック (blocks)、セクション (section)
  • メディアライブラリ (Media Library)、サイト設定 (site settings)、SEO
  • 多言語対応 (i18n) と翻訳の関係づけ、プレビュー、ドメイン変更

各節は「なぜそうなっているのか」「どう操作するか」「迷いやすい点」の順で書きます。節ごとに WordPress との違いにも触れます。基準は EmDash 1.3.1 (確認日 2026-10-29) です。

1. コンテンツの一生: 下書き・公開・予約公開・リビジョン・ゴミ箱

なぜこの設計なのか

EmDash は、Drafts を有効にしたコレクションでは「いま公開されている版 (live)」と「編集中の版 (draft)」を分けて持ちます。保存と公開は別の操作です。公開済みの記事を直しても、「公開する」操作をするまで訪問者には以前の版が見え続けます。WordPress の「更新」ボタンが保存と公開反映を同時に行うのと大きく違う点です。

エントリの状態は draft、scheduled、published の3つです。公開済みのエントリが、同時に下書きと将来の予約を持つこともできます。ゴミ箱 (Trash) は状態とは別の軸で、ゴミ箱に入ったエントリは通常の読み取りから除外されます。

管理画面での基本操作

管理画面は /_emdash/admin です。サイドバーでコレクション (collection) を選ぶと、エントリ一覧が開きます。一覧では検索、状態・作成者・日付・ロケールでの絞り込み、20/50/100件の表示切り替え、一括の公開・下書き戻し・ゴミ箱移動ができます。

画面 5-1 は、下書きの記事の編集画面です。公開の状態が「Draft version」と表示され、「Publish now」で公開、「予約公開」で日時を指定した公開ができます。

画面 5-1: 下書きの編集画面(Publish now と予約公開のボタン)

新規作成の流れは次のとおりです。

  1. Add New を選ぶ。タイトル欄があれば、そこからスラッグ (slug) が提案される。
  2. 必須フィールドと本文を入力して Save。最初の保存で下書きとして作られ、恒久的な編集 URL が開く。
  3. コレクションがプレビューに対応していれば Preview で表示を確認する。
  4. Publish now を選び、確認すると公開される。

エントリには不変のコンテンツ ID と、変更可能なスラッグが別々にあります。スラッグを変えても ID は同じエントリを指し続けます。

保存まわりの挙動で押さえておく点は次のとおりです。

  • 初回保存の後は、入力が2秒止まると自動保存されます。自動保存は「現在の自動保存リビジョン」を置き換えるだけで、履歴を細かく増やしません。履歴に残したい時点では Save を押します。
  • 公開済みエントリを保存しても更新されるのは下書きだけです。Preview draft で未公開の版、Live View で公開中の版を確認し、準備ができたら Publish changes を押します。
  • 公開済みエントリのスラッグを変えた場合も同じ流れで、公開 URL が変わるのは下書きを公開した時点です。

注意: 保存に失敗しても、エディタは未保存の入力を残してエラーを表示します。ボタンが Saved に戻るまでページを離れないでください。

同時編集とロック

エントリを開くとそのエントリとロケールにロックが取られます。他の人が開いている場合は Open read-only か Take over を選びます。奪われた側の次の保存は拒否されます。解放されなかったロックは最後の更新から7分で期限切れになります。ロックはロケールごとに独立で、管理者はコレクション単位で無効にできます。

公開と予約公開

公開系の操作は、Publish now(新規の下書きを公開)、Publish changes(公開済みの変更を公開)、Schedule / Change schedule / Remove schedule(予約の設定・変更・取り消し)、Unpublish(公開版を外し、予約を取り消し、編集可能な下書きを残す)に分かれています。

予約公開を押すと、日付と時刻を選ぶダイアログが開きます(画面 5-2)。ダイアログには、予約に使われるタイムゾーン(この例では Asia/Tokyo)も表示されます。

画面 5-2: 予約公開のダイアログ(日付と時刻の指定)

図 5-1 に示すように、draft、scheduled、published の3つの状態は、これらの操作でつながります。ゴミ箱は状態とは別の軸です。

図 5-1: 記事のステータスの遷移

予約するには、先に保存してから Schedule で未来の日時を指定します。エディタには予約に使うタイムゾーンが表示されます。予約時刻まで公開済みの版はそのまま公開され、新規エントリはまだ誰にも見えません。

予約公開を動かす「スイープ」(期限切れの予約を拾って公開する処理)は、Node.js のデプロイでは自動で動きます。Cloudflare Workers では Cron Trigger が必要です(Cloudflare 向けの公式スターターには含まれます。既存デプロイは設定を確認してください)。予約が2分以上過ぎても公開されていないものは、カレンダーで Overdue と表示されます。多くの場合、スイープが動いていないことを意味します。

注意: 予約公開は scheduled ステータスで管理され、期日が来ると通常の公開と同じ経路(content:beforePublish / content:afterPublish フック)を通ります。公開までの所要時間について、公式資料は具体的な秒数を示していません。示されている目安は、2分を超えると Overdue と表示される、という点だけです。

資料の状態遷移表から読み取れる挙動は次のとおりです。

  • 予約の期日で公開されるとき、初回公開なら予約時刻が publishedAt になります。公開済みエントリに新しい下書きを公開する場合は、既存の publishedAt が保たれます。
  • 公開すると scheduledAt は消えます。スケジューラが再度走っても、予約の消えたエントリは何もされません。
  • 予約時の公開を content:beforePublish フックが拒否すると、予約は解除され、content:afterUnschedule が実行されます。
  • 公開済みエントリに更新だけを予約できます。予約時刻まで、いまの公開版が見え続けます。
  • Calendar は公開済みと予約中のエントリを月/アジェンダ表示で一覧します(更新の予約には Update の印)。

リビジョン

リビジョン対応のコレクションでは、設定パネルの Revisions に保存された版が一覧されます (新しい20件を表示し、残りは Show older versions)。版を選ぶと読み取り専用で表示され、追加は強調、削除は取り消し線で差分が見えます。Restore を押すと、その版のコピーが新しい下書きとして作られます。重要なのは次の2点です。

  • 復元しても公開はされません。公開するまで訪問者には公開中の版が見えます。
  • そのエントリが予約済みなら、復元した版が予約時刻に公開されます。

ゴミ箱

Move to Trash で通常のクエリから外れ、Trash タブに残ります。Restore すると、予約なしの下書きとして戻るので、再度公開が必要です。Delete Permanently は管理者のみで、エントリとリビジョンを消し、取り消せません。

権限は所有者が軸です。Author は自分のエントリ、Editor は任意のエントリに操作でき、完全削除だけは Admin 限定です。API・CLI も同じ下書き/公開のワークフローです。REST API の更新は下書きの保存だけですが、CLI の content create / update は --draft を付けない限り自動で公開します。直前に返された _rev を渡すと、古い状態からの上書きを CONFLICT で拒否できます(REST では任意、MCP と CLI の content update では必須)。応答が届かなかったときは、再試行の前にエントリを読み直してください。

注意: CLI リファレンスによると、emdash content create と emdash content update は --draft を渡さない限り自動で公開します。下書きのままにしたいスクリプトでは --draft を明示してください。

WordPress との違い

観点 WordPress EmDash
公開済み記事の編集 更新すると即座に反映 (プラグインで下書き運用は可能) 保存は下書きのみ (Drafts を有効にしたコレクションの場合)。公開は別操作
予約投稿 future ステータス。WP-Cron がアクセスを契機に実行 scheduled。Node.js はスイープ自動、Cloudflare は Cron Trigger が必要
リビジョン 保存ごとに増える。復元で本文が置き換わる 復元は新しい下書きを作るだけで公開しない
ゴミ箱 30日で自動削除(既定) 公開資料に自動削除の記載なし。完全削除は Admin のみ
同時編集 投稿ロック (別の人が編集中の通知) エントリ・ロケール単位のロック、Take over あり

2. クエリ: Astro のページにコンテンツを出す

基本形

EmDash のコンテンツは、サーバー描画の Astro ページで getEmDashCollection() (一覧) と getEmDashEntry() (1件) を使って取り出します。どちらも例外ではなく、戻り値に error を載せて返します。呼び出し側が 500 にするか 404 にするかを決めます。

const { entries: posts, error, cacheHint } = await getEmDashCollection("posts", {
  orderBy: { published_at: "desc" },
  limit: 7,
});

公開側のクエリは既定で status: "published" です。ブログテンプレートは output: "server" なので、公開した版は次のリクエストから見えます。下書きは、公開されるか、有効なプレビュー URL で呼ばれるまで見えません。

戻り値の主な項目は、entries (該当なし・失敗時は空配列)、error、cacheHint (Astro のキャッシュ用タグ)、nextCursor、hasMore です。

2つの ID を混同しない

  • entry.id: URL 向けの識別子(通常はスラッグ、ロケール接頭辞つきのことも)。リンクに使います。
  • entry.data.id: データベース上の不変なコンテンツ ID。タクソノミーのヘルパーや getTranslations() に渡します。
  • entry.data.slug: ロケール接頭辞を含まないスラッグ。

getEmDashEntry() はスラッグでもコンテンツ ID でも引けます。

注意: クエリのガイドは「entry.id からリンクを作る」ことを勧めていますが、タクソノミーやリレーションの例は data.slug を使っています。単一言語なら同じ結果ですが、多言語では entry.id が安全というのが筆者の読みです。

フィルタ・並び順・ページネーション

  • where: キーがタクソノミー名ならタームのスラッグに一致し、それ以外はフィールドに一致します。複数キーは AND、配列は「いずれか」です。
  • orderBy: データベースの列名(published_at など)で指定します。publishedAt のようなキャメルケースは使えません。既定は created_at の降順で、頻繁に並べ替えるフィールドは indexed にします。
  • ページネーション: カーソル方式(cursor / nextCursor)と、オフセット方式(offset / hasMore)があり、併用できません。オフセットは記事の追加で後続ページがずれます。
  • status に "draft" などを指定できますが、公開ルートで下書きを要求してはいけません。

1件の取得と描画

decodeSlug() でパラメータをデコードして getEmDashEntry() に渡し、見つからなければ Astro.rewrite("/404") します。本文は emdash/ui の PortableText で描画します。HTML ブロックは、isolated: true なら sandbox 付き iframe で、そうでなければサニタイズされた HTML としてページに入ります。Astro の CSP を有効にすると、隔離ブロックの CSS/JS はブロックされます。

参照フィールドの読み取り

reference フィールドは data に入りません。references オプションで必要なフィールドを指名します。

const { entry: post } = await getEmDashEntry("posts", slug, {
  references: { author: true, related_posts: { limit: 6 } },
});

true は既定50件、{ limit, cursor } で最大100件ずつ取れ、続きは getEmDashReferences() です。指名しなければ追加クエリは走りません。参照先エントリには、バイラインとタームは取り込まれません。プレビュー時は下書きの選択内容が見えます。

型とキャッシュ

開発サーバーが生成する emdash-env.d.ts を tsconfig に含めれば、コレクション名から Post 型が付きます。Astro のキャッシュを使うときは cacheHint を Astro.cache.set() に渡すと、公開時に該当ページが無効化されます。固定の長い Cache-Control で置き換えると更新が遅れます。

WordPress との違い

WordPress ではテーマが WP_Query とループでテンプレートに書き出します。EmDash は、フィールドとキーが型として生成され、フィルタとソートはデータベース側で行われます。「自動的に現在のページのクエリが決まる」仕組みはなく、ルートごとに自分でクエリを書くのが基本です。

3. タクソノミー

概要

タクソノミーは、1つ以上のコレクションに適用される分類の名前付きまとまりです。投稿には、階層のあるカテゴリ category と、フラットなタグ tag が最初から用意されています。サイト独自に genre、topic のようなタクソノミーも作れます。

管理とクエリ

  • Taxonomies からターム(ラベル、スラッグ、親、説明)を追加・並べ替えます。タームを消しても、エントリは消えません。
  • 独自タクソノミーは New Taxonomy で作ります。名前は小文字英字で始まり、小文字・数字・アンダースコアのみで、作成後は変更できません。
  • テンプレートは「名前」でクエリするので、表示ラベルを変えても直す必要はありません。
  • 一覧で記事を選んで Add するか、Add to posts に公開 URL を貼る(最大50件)と、タームをまとめて付けられます。記事の未公開の下書き編集は公開されません。

タームの一覧は getTaxonomyTerms("category", { locale, includeCounts: false })、1件は getTerm() です。件数は集計コストがかかるので、表示しないなら includeCounts: false にします。エントリのタームは entry.data.terms に取り込まれるので、一覧の各行で getEntryTerms() を呼ばず、取り込まれていないときは getTermsForEntries() でまとめて取ります。アーカイブでは where: { category: category.slug } で絞り込みます。

落とし穴

  • タクソノミーの削除は、全言語のタームと、そのタームへの割り当てを消します。取り消せません。削除後もテンプレートは動き続け、getTaxonomyTerms() は空配列、where は 0 件を返すだけなので、気づきにくい壊れ方をします。
  • 翻訳: タクソノミー定義とタームはロケールごとに1行ですが、翻訳としての同一性が記録されています。name、hierarchical、collections は全ロケール共通で、label と labelSingular はロケールごとです。タームの親と並び順も全ロケール共通です。

WordPress との違い

WordPress のカテゴリ・タグ・カスタムタクソノミーと概念はほぼ同じです。違いは、(1) アーカイブの URL とクエリがテンプレートの責務であること、(2) 翻訳が WPML/Polylang のようなプラグイン無しで最初から組み込まれていることです。

4. リレーション

なぜ必要か

「記事と著者」「商品と関連商品」のような、コレクション間のリンクを扱います。リンクの実体はリレーションが持ち、reference フィールドはそれを片側から見るビューです。リンクは各エントリの翻訳グループをキーに別テーブルへ保存されるので、両側から同じ集合を編集でき、全翻訳で1つの選択が共有されます。カラムを持たないため、searchable や indexed にできず、サイト内検索や一覧のフィルタには効きません。

作り方

  1. Content Types → Relations → New Relation で、Links from(選ぶ側)と Links to(選ばれる側)を決め、各側の名前、スラッグ、個数上限(One / Any number / At most)を設定します。
  2. コンテンツタイプで Add Field → Reference を選び、リレーションに束ねます。

両端のコンテンツタイプとスラッグは作成後に変更できません。上限を下げても既存リンクは残りますが、超過したエントリは保存を拒否されます。各端に置けるフィールドは1つです。リレーションを削除すると、リンクと束ねたフィールドが消えます。リレーションを持たない旧来の reference フィールドは、Referenced collection を選ぶと、リンクが移されて picker になります(検索可能/索引のフラグは外れます)。

読み取り

前節のとおり、references オプションで取り出します。親側のフィールドは編集者が並べた順で返り、子側は並び順を持ちません。

WordPress との違い

ACF の関連投稿は、メタ値に ID を保存するだけで、逆方向の参照は自分でクエリする必要がありました。EmDash は逆方向のフィールドを用意でき、個数上限もリレーション側で一元管理されます。

5. メニュー

メニューは、テンプレートを変えずに編集者が順序付きリンクを管理する仕組みです。Menus で名前(テンプレートが検索するキー)とラベルを決め、Add Content か Add Custom Link で項目を足し、Parent でネストします。

メニューは、管理画面の「メニュー」で管理します(画面 5-3)。

画面 5-3: メニューの一覧(メニュー名・識別名・項目数)

コンテンツやタームへの項目は完成した URL ではなく参照を保存します。getMenu() の呼び出し時に urlPattern(なければ /{collection}/{slug})から URL が決まるので、スラッグが変わっても追従します。注意点は次のとおりです。

  • 公開済みの翻訳が1つもないコンテンツ項目は、子項目ごと結果から省かれます(編集モードでは表示されます)。
  • 返される URL にロケール接頭辞は含まれません。多言語では getRelativeLocaleUrl() で接頭辞を足します。
  • メニューが存在しなければ null が返ります。
  • ロケールは、明示した locale、リクエストのロケール、既定ロケールの順で、足りなければフォールバックをたどります。

多言語では同じメニュー名を全ロケールで使い、Translations パネルで他言語版を作ります。WordPress の wp_nav_menu() と違い、描画は自分のコンポーネントで書きます。

6. ウィジェット

使い分け

同期した内容にしたいもの(サイドバー、フッター、告知)はウィジェットエリア、編集者が挿入後に個別に変えたいものはセクション(第8節)、と使い分けます。

ウィジェットの種類は Content(Portable Text)、Menu、Component で、Component は組み込みの core:recent-posts、core:categories、core:tags、core:search、core:archives から選びます。テンプレートでは emdash/ui の WidgetArea を置きます。エリアが存在しないか空なら何も描画しません。Astro のスタイルは既定でスコープされるので、WidgetArea 内のマークアップには <style is:global> で当てます。

多言語での落とし穴

組み込みのウィジェットレンダラーは、メニューやタクソノミーのヘルパーが返すルート相対 URL をそのまま使い、Astro のロケール接頭辞を足しません。多言語サイトで接頭辞が必要なら、getWidgetArea() で自前描画するか、メニュー/タクソノミーは前述の描画パターンで書きます。自前描画の例は、component タイプのウィジェットを描画しないので、組み込みコンポーネントも使うなら標準の WidgetArea を併用してください。

WordPress のウィジェットは PHP のウィジェットクラスで拡張しますが、EmDash では「Component ウィジェット」が組み込みの5種類で、それ以外は Astro コンポーネントを自分で書きます。

7. ページレイアウトとブロック

ページレイアウト: select で切り替える

固定ページごとにレイアウト(Default、Full Width、Landing など)を選ばせるには、template という select フィールドをページのコレクションに追加し、ルートで値を Astro のレイアウトコンポーネントに対応づけます。

選択肢の値が保存値と管理画面の表示名を兼ねます。公式ドキュメントでは方針が 2 つに分かれています。Page Layouts ガイドは full-width のようなスラッグではなく "Full Width" のような読みやすい名前を値にすることを勧め、Create a theme のガイド (第 6 章) は default / full-width / landing のような安定した値を使います。サイト内だけで使うなら前者でも動きます。テーマとして配布するなら安定した値を推奨します (筆者の見解)。どちらの場合も、未知の値は既定レイアウトに落とすのが無難です。これは WordPress のページテンプレートに相当します。

ブロック: 1ページの中を組み立てる

1ページの中でセクションを並べ替えたい(ヒーロー、特徴一覧、CTA…)場合は blocks フィールドを使います。各ブロックは型 (_type)、バージョン (_version)、安定キー (_key)、そのバージョンで宣言されたフィールドを持ちます。

手順は次のとおりです。

  1. ブロック型をシード(またはスキーマ API / MCP)で定義する。currentVersion と版ごとの fields を持つ。
  2. blocks フィールドの validation.allowedTypes で、使えるブロックと選択肢の順序を指定する(maxItems は最大100)。
  3. 型ごとに Astro コンポーネントを書き、defineBlockComponents で全型の対応を型チェックして、<Blocks value components /> で描画する。

<Blocks> は追加のクエリを実行せず、保存順にそのまま描画します。開発中、対応するコンポーネントがない型は目に見えるプレースホルダと警告になりますが、本番では fallback を渡さない限り何も出力されません。レンダラーは、ブロック型を本番コンテンツで有効にする前に先にデプロイしてください。

8. セクション

セクションは再利用できる Portable Text のまとまりです。Sections で作成し、本文で /section と入力して挿入します。挿入されるのは独立したコピーで、あとから原本を編集しても挿入済みの分は変わりません。CTA、著者紹介、定型の注意書きに向いています。

getSection("slug") で現在の値を直接描画すると、描画のたびに原本を読むため、編集が使用箇所すべてに反映されます。同期が目的のときだけ使います。シードで提供するときは、各ブロックとスパンに安定した _key を付け、emdash seed --validate で検証します。

WordPress の再利用ブロックは原本の編集が全箇所に同期されますが、EmDash では「挿入はコピー、同期はウィジェットエリア」です。移行時に誤解しやすい点です。

9. メディアライブラリ

アップロードと制限

Media またはエディタ内のピッカーからアップロードします。既定で受け付けるのは、PNG/JPEG/GIF/WebP/AVIF、MP4/WebM/QuickTime などの動画、MP3/WAV/Ogg などの音声、PDF です。SVG は既定で除外されます(能動的なコンテンツを含みうるため)。最大は1ファイル50 MB で、maxUploadSize で変更できます。画像/ファイルフィールドには受け付ける MIME タイプを個別に設定でき、保存時にサーバー側でも再検査されます。フォルダを削除してもファイルは Main library に戻るだけで、URL も参照も変わりません。

画像の扱い: 「この使用箇所」と「素材そのもの」を区別する

画像の編集には、影響範囲の異なる操作が並んでいます。迷うのはここです。

操作 影響範囲
Replace (エディタ内) このフィールド/ブロック/ギャラリー位置だけを別の素材にする。他のエントリは変わらない
Edit asset 素材そのものを開く。メタデータや破壊的な画像変更は、その素材を使うすべての箇所に影響しうる
Remove このコンテンツ上の参照を外す。ライブラリの素材は残る
Replace image (ライブラリ) 同じメディア ID・URL のまま、バイト列を差し替える。使用している全箇所が新しい画像になる
Crop → Create cropped copy 新しい素材を作り、元は変えない
Crop → Replace original メディア ID を保ったまま画像を変更する。全箇所に反映される

どこで使われているか、削除の安全性

素材の Used in は、参照しているエントリとサイト設定(Logo、Favicon、Default Social Image)を一覧します。ただし管理者が Settings → Media usage tracking で一度だけ有効化する必要があります。有効化中はコンテンツ等の書き込みが一時的に拒否されるので、編集を止めてから行います。一度有効にすると無効にできません。追跡の対象は、画像/ファイルフィールド、blocks 内、Portable Text の画像/ギャラリー/動画ブロックなどで、カスタムブロックや独自コード、外部サイトは見ません。

注意: メディアの削除にはゴミ箱がなく、取り消せません。コンテンツ内の参照は書き換わらず、画像が壊れて表示されます。Used in が空でも安全の証明にはなりません。

テンプレートでの描画

画像フィールドの値は URL ではなくメディア値です。emdash/ui の Image に渡すと、寸法、焦点、レスポンシブ変種、プレースホルダがまとめて処理されます。

<Image image={post.data.featured_image} width={1200} height={675} priority />
  • priority はファーストビューのメイン画像だけに使います。他は既定の lazy のままにします。
  • quality は数値か "low" | "mid" | "high" | "max" です。組み込みの Cloudflare Images プロバイダーは、現時点ではこのオプションを適用しません。
  • 画像フィールドで Dark mode variant(シードなら options: { darkVariant: true })を有効にすると、Image が2つの <img> を出し、CSS で切り替えます。priority を付けると両方ダウンロードされます。
  • ファイルフィールドには、すぐ使える URL がありません。meta.storageKey を Astro.locals.emdash.getPublicMediaUrl() に渡します。

ストレージは設定したアダプターが決めます(Node.js はディスクか S3 互換、Cloudflare は R2 が一般的)。Cloudflare Images/Stream は外部プロバイダーとして登録でき、その素材にはローカルエディタのトリミング等が使えません。

WordPress との違い

WordPress の「メディア」は添付ファイルで、サイズ違いの派生画像が生成されます。EmDash では Image コンポーネントが描画時に最適な出力を担当します。素材の使用箇所の追跡は、WordPress では標準にはなく、EmDash では明示的に有効化する機能です。また、WordPress の SVG と同様に、EmDash は SVG を既定では許可していません。

10. サイト設定

Settings は General(タイトル、キャッチフレーズ、ロゴ、ファビコン、公開 URL、投稿数、日付形式、タイムゾーン)、Social、SEO に分かれます。設定は任意で、テンプレート側にフォールバックを用意します。

設定画面は、サイト、メディア、セキュリティなどの項目に分かれています(画面 5-4)。

画面 5-4: 設定画面(サイト・メディア・セキュリティ設定)
  • レイアウトでは getSiteSettings() を1回呼びます。1件なら getSiteSetting("timezone") です。同一リクエスト内ではキャッシュされます。
  • dateFormat は MMMM d, yyyy のようなパターン文字列で、Intl.DateTimeFormat では使えません。
  • ソーシャルはハンドルを保存します。URL の組み立てはテーマの責任です。
  • ロゴ・ファビコン・既定の OGP 画像はメディア参照です。参照先が削除されると url が欠けるので、描画前に確認します。API からは null で削除でき、省略すると変更されません。

WordPress の「サイトの設定」に近い位置づけですが、資料に列挙されている設定項目には配色やレイアウトは含まれていないため、それらはテンプレートに書きます。

11. SEO

何が入っているか

SEO の機能は、コレクションで SEO を有効にし、<EmDashHead> をページの <head> に置くことで多くが動きます。

機能 出力 必要なもの
SEO パネル エントリごとのタイトル、説明、画像、canonical、noindex コレクションで SEO 有効
ヘッドのメタ情報 description、robots、canonical、Open Graph、Twitter Card <EmDashHead>
構造化データ JSON-LD の BlogPosting または WebSite <EmDashHead>
サイトマップ /sitemap.xml と /sitemap-{collection}.xml コレクションで SEO 有効
robots.txt サイトマップ参照つき 不要
リダイレクトと404ログ リダイレクト/410/451、404 の記録 不要

シードでは、コレクションの supports 配列に "seo" を加えます。Routable をオフにしたコレクションはサイトマップに載りません。

実務の要点

  • <EmDashHead> は <title> を出力しません。レイアウトで書きます。
  • コンテンツページでは createPublicPageContext() に content: { collection, id, slug } を渡すと、SEO パネルの値がサイト既定より優先されます。getSeoMeta() は空のとき title と excerpt にフォールバックします。
  • Hide from search engines は noindex, nofollow を出力し、サイトマップと hreflang からも外します。
  • サイトマップは1ファイル2,000エントリまでで、超えると -2、-3 と続きます。
  • robots.txt は既定で全許可、/_emdash/ を拒否し、サイトマップを参照します。Disallow AI training で、GPTBot、ClaudeBot、CCBot などの AI 学習クローラー向けルールが加わります。強制力のない取り決めです。自前の robots.txt.ts ルートを置くと、これは無視されます。
  • 公開済みのスラッグを変えると、旧 URL から新 URL への 301 が自動作成されます(別の翻訳が旧スラッグを使っていれば作られません)。404 ログから、リダイレクトや 410 を設定できます。
  • サイトマップ等の絶対 URL は、Site URL、siteUrl オプション、EMDASH_SITE_URL、リクエスト元オリジンの順で決まります。robots.txt は最大1日、サイトマップは最大1時間キャッシュされることがあります。

WordPress では Yoast や Rank Math に頼る領域が本体機能です。インポートした Yoast/Rank Math の値は、SEO パネルとは別の通常フィールドに入るので、テンプレートが自分で描画します。

12. 多言語 (i18n) と翻訳の関係づけ

モデル: 1ロケール1行

EmDash の翻訳は、1ロケールにつき1行のモデルです。翻訳ごとに、独自の ID、スラッグ、ステータス、リビジョン履歴を持ち、translation_group という共通の識別子で結びつきます。

ec_posts:
id       | slug        | locale | translation_group | status
01ABC... | my-post     | en     | 01ABC...          | published
01DEF... | mon-article | fr     | 01ABC...          | draft
01GHI... | mi-entrada  | es     | 01ABC...          | published

その結果、ロケールごとのスラッグ、公開、リビジョンが自然に成立し、フランス語が下書きのまま英語だけ公開、といった運用ができます。リスト系のクエリは1つのロケールだけを返します。

図 5-2 に示すように、各行は独自の ID を持ちながら、共通の translation_group の値で結びつきます。

図 5-2: 1ロケール1行の翻訳と translation_group

設定と最大の落とし穴

Astro の設定に i18n ブロックを追加します。i18n がなければ、i18n 機能は無効で単一言語の CMS として動きます。

i18n: {
  defaultLocale: "en",
  locales: ["en", "fr", "es"],
  fallback: { fr: "en", es: "en" },
},

注意: 既定ロケールにも接頭辞を付けるルーティング (prefixDefaultLocale: true または "prefix-always") を使うと、/_emdash/admin とセットアップ・ログイン画面が 404 になります。Astro の既定 (prefix-other-locales) を使い、routing ブロックは書かないでください。公開 URL に既定ロケールを入れたいなら、前段で / から /en/ へリダイレクトや書き換えを行います。

ロケールのフォールバック

単一エントリの取得では、リクエストのロケールに公開済みの該当がなければ、フォールバックチェーンをたどります。fallback: { fr: "en" } なら、fr、en、既定ロケールの順です。実務で迷うのは次の点です。

  1. フォールバックは単一エントリだけです。一覧クエリは、リクエストしたロケールの行だけを返します。
  2. 探す識別子は同じです。about なら英語の about に落ちますが、フランス語のスラッグ a-propos では英語の about は見つかりません。スラッグが違う翻訳の関連づけには getTranslations() を使います。
  3. 戻り値の fallbackLocale で、フォールバックが使われたかが分かります。
  4. メニューとタクソノミーの単一ターム取得も、チェーンをたどります。
  5. 多言語ルートでは Astro.currentLocale を明示的に渡すのが推奨です。同じスラッグが複数ロケールにありうるためです。

図 5-3 に示すように、フォールバックが働くのは単一エントリの取得だけで、一覧クエリは働きません。

図 5-3: ロケールのフォールバックが働く範囲

翻訳の作成と関係づけ

管理画面では、Translations パネルで未翻訳ロケールの Translate を選びます。翻訳は下書きとして、元エントリのデータと同じスラッグで作られます(スラッグはロケール内でユニークならよい)。API では locale と translationOf(元の行の entry.data.id)、CLI では --locale と --translation-of を指定します。シードでは元のエントリを翻訳より前に書きます。

言語切り替えは getTranslations(collection, entryId) で兄弟の翻訳を得て、getRelativeLocaleUrl() でリンクを作ります。下書きや予約中の兄弟も返るので、公開リンクには status === "published" で絞り込みます。

翻訳対象のフィールド

各フィールドには translatable があり、既定は true です。翻訳可能なフィールドは元のロケールから事前入力され、翻訳可能でないもの(SKU、並び順の数値など)は全翻訳でコピーされ同期されます。リビジョンのあるコレクションでは、公開時に、変更された非翻訳フィールドの値が他の翻訳へコピーされ、下書きの保存では同期されません。status、published_at、author_id などのシステムフィールドは常にロケールごとで同期されません。リレーションのリンクは同期ではなく共有で、どのロケールから編集しても全ロケールに反映されます。

SEO まわり

<EmDashHead> は、i18n が有効でページに content があるとき、公開済みの翻訳ごとに hreflang の alternate(自分自身を含む)と x-default を出します。サイトマップも翻訳ごとに <url> を持ち、xhtml:link で結ばれます。下書き、noindex、i18n.locales にないロケールは含まれません。手書きの <head> には getHreflangAlternates() を使いますが、絶対 URL が必要で、siteUrl かサイト設定の URL がないと空配列を返します。

移行時の注意

WordPress の WXR エクスポートには、WPML や Polylang が持つロケールと翻訳グループの情報が含まれません。インポートしたコンテンツは既定ロケールに入ります。翻訳が必要なら、インポート後に --translation-of で元の ID に結びつけて作ります。

WordPress との違い

WordPress の多言語は WPML や Polylang といったプラグインで実現するのが一般的で、翻訳の関連づけの方式はプラグインごとに違います。EmDash では行単位の翻訳とグループがコアの設計に入っています。翻訳ごとに独立したステータスとリビジョンを持つ点は Polylang に近いと筆者は考えます (公式ドキュメントに比較はありません)。また、フォールバックチェーンを Astro の設定として持つ点が特徴です。

13. プレビュー

仕組み

下書きを公開前に見るには、署名付きで有効期限のある URL を使います。管理画面が下書きの URL に _preview クエリ (HMAC-SHA256 署名のトークン)を付けて発行し、EmDash のミドルウェアがトークンを検証して、そのエントリに限り下書きを読む許可をリクエスト文脈に記録します。テンプレートは通常どおり getEmDashEntry() を呼ぶだけで、有効なプレビューなら下書き、通常のリクエストなら公開版が返ります。別のコレクションやエントリ向けのトークンでは、下書きは見えません。

トークンが有効なとき戻り値の isPreview が true になるので、バナーを出せます。

設定とURLの作成

署名用の秘密鍵は初回使用時にサイトごとに自動生成され、DB に保存されるので、通常は設定不要です。複数プロセスで共有する、値を固定する、といった場合のみ EMDASH_PREVIEW_SECRET を設定します(環境変数が優先)。編集者は管理画面の View on site を使います。サーバー側でリンクを作るなら getPreviewUrl({ collection, id, secret, expiresIn }) を使います。DB の鍵は読めないので、環境変数の設定が必要です。

  • expiresIn は "30m"、"1h"(既定)、"2w" のような文字列か秒数です。
  • pathPattern で {collection}、{id}、{locale} を使えます。
  • 公開ルートが /{collection}/{id} と違うなら EMDASH_PREVIEW_PATH_PATTERN を設定します。View on site はスラッグでなくデータベース ID を使います。

落とし穴

セキュリティ: EMDASH_PREVIEW_SECRET を知っている人は、任意のコンテンツのプレビュートークンを作れます。漏らさないでください。共有されたプレビューリンクは、有効期限内なら誰でも開けるので、レビュワーに渡す期限は短くします。

通常のページは verifyPreviewToken() を呼ぶ必要はありません。ミドルウェアが検証済みです。独自のフローでミドルウェアの外から検証するときだけ使います。

WordPress のプレビューは、ログイン中のユーザーが下書きを見る機能で、共有には別のプラグインが必要でした。EmDash は、期限付き署名 URL を標準で提供する点が違います。

14. ドメイン変更

サイトの公開アドレスは Settings > General の Site URL です。メール内のリンク、サイトマップ、robots.txt、hreflang、OGP 画像 URL、SEO パネルの canonical は、これを参照します。変更は管理者のみで、Change domain のダイアログから行います。

手順

  1. 先に新ドメインをサイトへ向けます。Cloudflare Workers では Worker の Domains タブでカスタムドメインを追加します(ルート (route) では確認が通りません)。
  2. https://<新ドメイン>/_emdash/admin でサインイン画面が出ることを確認します。
  3. Change domain に新ドメインを入力し、Check and switch を選びます。EmDash は新ドメインの /_emdash/api/site/domain-proof から1回限りのコードを取得し、一致すれば保存します。

確認に失敗した理由(DNS 未解決、接続不可、リダイレクト、別のサイトを配信)は画面に表示されます。ローカル開発や認証の壁の裏では Use … anyway で確認なしに保存できますが、到達性は保証されません。siteUrl などを設定している場合、メール等のリンクはそちらが優先されます。

切り替え後に起こること

メールは即座に新しいアドレスになります。プラグインの ctx.site.url はサーバー再起動後に変わります。サイトマップは最大1時間、robots.txt は最大1日、古い版がキャッシュされます。旧アドレスはホスト側で外すまで配信を続けるので、リダイレクトはホストか DNS 側で設定します。

パスキーに注意

パスキー (passkey) は作成したアドレスでしか使えません。旧アドレスにサインインしているうちに、Settings > General の Continue on …(1回限り、5分で失効)から新アドレスで Register Passkey します。他のユーザーにはメールが設定済みなら Email users で通知でき(1時間に3回まで)、マジックリンクでサインインしてからパスキーを追加します。

セキュリティ: 旧アドレスを外す前に、すべての管理者が新アドレスでサインインできることを確認してください。

まとめ

  • 保存と公開は別操作です。予約公開は scheduled で、Node.js はスイープが自動、Cloudflare は Cron Trigger が必要です。
  • クエリはルートごとに書き、entry.id(URL 用)と entry.data.id(DB ID)を使い分けます。
  • 同期するか(ウィジェット)、コピーか(セクション)で再利用の仕組みを選びます。ページ全体の枠は select、ページ内の部品は blocks です。
  • メディアは使用箇所への操作と素材への操作で影響範囲が違い、削除にゴミ箱はありません。
  • 多言語は1ロケール1行で、フォールバックは単一エントリだけです。既定ロケールに接頭辞を付けると管理画面に入れません。
  • プレビューは署名付き期限付き URL、ドメイン変更はパスキーの再登録に注意します。

理解度チェック

  1. 公開済みの記事を編集して Save を押しました。訪問者にはどの版が見えますか。変更を公開するにはどの操作が必要ですか。
  2. エントリを予約公開にしましたが、期日を過ぎても公開されません。Cloudflare Workers で最初に確認することは何ですか。また、カレンダー上のどの表示が手がかりになりますか。
  3. テンプレートで、記事一覧のリンクと、タクソノミーのヘルパーに渡す ID は、それぞれ entry のどの値を使いますか。
  4. fallback: { fr: "en" } の設定で、フランス語の記事一覧ページと、記事 a-propos の個別ページは、未翻訳の英語記事に対してそれぞれどう動きますか。
  5. ライブラリの画像の Replace image と、記事内の Replace は何が違いますか。メディアを削除する前に確認すべきことは何ですか。
  6. セクションとウィジェットエリアは、どちらも再利用可能な内容を扱います。更新が全箇所に反映されるのはどちらですか。

答え

  1. 訪問者には以前の公開版が見え続けます。保存は下書きだけを更新します。Publish changes で公開します。
  2. Cron Trigger が設定されているかを確認します(スターターテンプレートには含まれる)。カレンダーでは、予約が2分以上過ぎたものに Overdue と表示されます。
  3. リンクには URL 向けの entry.id、タクソノミーのヘルパー(getEntryTerms() など)にはデータベース上の ID である entry.data.id を使います。
  4. 一覧はリクエストしたロケールの行だけを返すので、未翻訳の英語記事は含まれません。個別ページはフォールバックが働きますが、同じ識別子で探すため、英語のスラッグが a-propos でなければ見つかりません。
  5. ライブラリの Replace image は、同じメディア ID・URL のままバイト列を差し替えるため、使用している全箇所が変わります。記事内の Replace はその使用箇所だけを別の素材にします。削除前には、Used in(有効化が必要)の確認に加え、カスタムテンプレートやデータストアに URL がないかも確認します。
  6. ウィジェットエリアです。セクションは挿入時にコピーされるので、あとから原本を編集しても挿入済みの分は変わりません。ただし getSection() で直接描画する場合は、原本の変更が反映されます。

出典

公式ドキュメント(https://docs.emdashcms.com/ 以下。リポジトリの sources/emdash-docs/ の MDX に対応)。

  • 第1節: https://docs.emdashcms.com/guides/working-with-content/、https://docs.emdashcms.com/reference/content-lifecycle/
  • 第2節: https://docs.emdashcms.com/guides/querying-content/、https://docs.emdashcms.com/guides/create-a-blog/
  • 第3節: https://docs.emdashcms.com/guides/taxonomies/
  • 第4節: https://docs.emdashcms.com/guides/relations/、https://docs.emdashcms.com/reference/field-types/
  • 第5節: https://docs.emdashcms.com/guides/menus/
  • 第6節: https://docs.emdashcms.com/guides/widgets/
  • 第7節: https://docs.emdashcms.com/guides/page-layouts/、https://docs.emdashcms.com/guides/blocks/
  • 第8節: https://docs.emdashcms.com/guides/sections/
  • 第9節: https://docs.emdashcms.com/guides/media-library/、https://docs.emdashcms.com/guides/dark-mode/
  • 第10節: https://docs.emdashcms.com/guides/site-settings/
  • 第11節: https://docs.emdashcms.com/guides/seo/
  • 第12節: https://docs.emdashcms.com/guides/internationalization/
  • 第13節: https://docs.emdashcms.com/guides/preview/
  • 第14節: https://docs.emdashcms.com/guides/change-domain/