building-emdash-site

EmDash サイトの構築

EmDash は Astro をベースにした CMS です。スキーマをコードではなくデータベースに保存し、ライブコンテンツコレクションを通じてコンテンツを配信し、/_emdash/admin に完全な管理 UI を提供します。サイトは emdash インテグレーションを使用する標準的な Astro プロジェクトです。

よくある落とし穴

サイトを気づかないうちに壊してしまう原因となる項目です。作業を始める前に把握しておいてください。

1. 画像フィールドは文字列ではなくオブジェクトです。 post.data.featured_image は { id, src, alt } です。<img src={post.data.featured_image} /> と記述すると、[object Object] が表示されます。"emdash/ui" の <Image image={post.data.featured_image} /> を使用してください。

2. entry.id と entry.data.id は別のものです。 entry.id はスラッグで、URL にロケールのプレフィックスが付く場合はロケールが先頭に付きます（en/my-post）。URL にはこちらを使用してください。entry.data.slug はプレフィックスのないスラッグです。entry.data.id はデータベースの ULID です（実際の ID を必要とする getEntryTerms、Comments、その他の API 呼び出しに使用します）。これらを取り違えると、エラーが出ないまま結果が空になります。

3. タクソノミー名はシードと完全に一致させる必要があります。 シードで "name": "category" と定義した場合は、getTerm("category", slug) をクエリしてください。"categories" ではありません。名前が違うと、エラーが出ずに結果が空になります。

4. Astro のキャッシュが有効な場合は、キャッシュヒントを登録してください。 コンテンツクエリは cacheHint を返します。これを Astro.cache.set(cacheHint) に渡してください。キャッシュされたルートでサイト設定、メニュー、タクソノミーの用語、ウィジェットエリアをレンダリングする場合は、getSiteSettingsWithCacheHint()、getMenuWithCacheHint()、getTaxonomyTermsWithCacheHint()、getWidgetAreaWithCacheHint() を使用してください。

5. CMS コンテンツに getStaticPaths は使用しません。 EmDash のコンテンツは動的です。ページはサーバーサイドでレンダリングする必要があります（astro.config.mjs で output: "server" を指定します）。

ファイル構成

すべての EmDash サイトには、次の重要なファイルがあります。

my-site/
├── astro.config.mjs          # Astro config with emdash() integration
├── src/
│   ├── live.config.ts         # EmDash loader registration (boilerplate)
│   ├── pages/                 # Astro pages (all server-rendered)
│   ├── layouts/               # Layout components
│   └── components/            # Reusable components
├── seed/
│   └── seed.json              # Schema + demo content
├── emdash-env.d.ts          # Generated types (from `emdash types`)
└── package.json

ワークフロー

1. プロジェクトを設定する

astro.config.mjs、live.config.ts、デプロイ先（Node または Cloudflare）、型生成については、references/configuration.md を参照してください。

2. スキーマを設計する

コレクション定義、フィールドの型、タクソノミー、メニュー、ウィジェットエリア、セクション、署名欄、シードファイルの完全な形式については、references/schema-and-seed.md を参照してください。

3. ページを構築する

コンテンツクエリ、Portable Text のレンダリング、Image コンポーネント、ビジュアル編集用属性、キャッシュ、一般的なページパターン（一覧、詳細、タクソノミーアーカイブ、RSS、検索、404）については、references/querying-and-rendering.md を参照してください。

4. サイト機能を組み込む

サイト設定、ナビゲーションメニュー、タクソノミー、ウィジェットエリア、検索、SEO メタ情報、コメント、ページのコントリビューションについては、references/site-features.md を参照してください。

5. シードファイルを作成する

コレクション、フィールド、タクソノミー、メニュー、ウィジェット、サンプルコンテンツを含む seed/seed.json を作成してください。

6. 実行して確認する

pnpm dev                # Start the Astro dev server

ランタイムは最初のリクエスト時に保留中のマイグレーションを実行し、セットアップが完了するまではシードのスキーマと構造を一度だけ適用します。サンプルコンテンツの適用には明示的な手順が必要です。シードの適用を参照してください。サーバーの起動時に Astro インテグレーションが emdash-env.d.ts を生成します。管理 UI は http://localhost:4321/_emdash/admin にあります。

API クイックリファレンス

// Content (entries have .data.byline and .data.bylines eagerly loaded)
import { getEmDashCollection, getEmDashEntry } from "emdash";
const { entries, nextCursor, cacheHint } = await getEmDashCollection("posts", {
	limit: 10,
	cursor,
	orderBy: { published_at: "desc" },
});
const { entry: post, cacheHint: entryCacheHint } = await getEmDashEntry("posts", slug);

// Site features
import {
	getSiteSettings,
	getSiteSettingsWithCacheHint,
	getMenu,
	getMenuWithCacheHint,
	getTaxonomyTerms,
	getTaxonomyTermsWithCacheHint,
	getTerm,
	getEntryTerms,
	getEntriesByTerm,
	getWidgetArea,
	getWidgetAreaWithCacheHint,
	search,
	getSection,
	getSeoMeta,
} from "emdash";

// Bylines (standalone queries -- usually not needed since entries have bylines attached)
import { getByline, getBylineBySlug } from "emdash";

// UI components
import {
	PortableText,
	Blocks,
	defineBlockComponents,
	Image,
	WidgetArea,
	EmDashHead,
	EmDashBodyStart,
	EmDashBodyEnd,
} from "emdash/ui";
import { Comments, CommentForm } from "emdash/ui/comments";
import LiveSearch from "emdash/ui/search";

// Page context (for plugin contributions)
import { createPublicPageContext } from "emdash/page";

プラグイン

EmDash は、フック、ストレージ、設定、管理 UI、API ルート、カスタム Portable Text ブロックタイプを使って CMS を拡張するプラグインに対応しています。次のような場合は、プラグインの使用を検討してください。

• コンテンツのライフサイクルイベントに対応する（例：公開時に通知を送信する、外部サービスと同期する）
• カスタム管理ページやダッシュボードウィジェットを追加する
• 再利用可能な動作やカスタム Portable Text タイプを追加する（例：埋め込みマップやコードプレイグラウンド）
• 再利用可能なサービスを提供する（例：サードパーティープロバイダーを介した分析、フォーム、コメント）

プラグインは astro.config.mjs に登録します。

emdash({
	database: sqlite({ url: "file:./data.db" }),
	storage: local({ directory: "./uploads", baseUrl: "/_emdash/api/media/file" }),
	plugins: [myPlugin()],
}),

プラグインを作成するには、creating-plugins スキルを読み込んでください（.agents/skills/creating-plugins/）。プラグインの構成、フック、ストレージ、管理 UI、API ルート、Portable Text ブロック、機能、definePlugin() API の全容について解説しています。

リファレンスドキュメント

ファイル	内容
references/configuration.md	プロジェクトのセットアップ、astro.config、live.config、デプロイ、型
references/schema-and-seed.md	コレクション、フィールド、分類、メニュー、ウィジェット、シード形式
references/querying-and-rendering.md	コンテンツ API、PortableText、画像、キャッシュ、ページのパターン
references/site-features.md	設定、メニュー、ウィジェット、検索、SEO、コメント、ページへの機能追加