Seed 檔案格式

Seed 檔案是初始化 EmDash 網站的 JSON 文件。它們定義集合、欄位、分類法、選單、重新導向、小工具區域、網站設定和可選的範例內容。

根結構

Seed 檔案具有以下頂層結構：

{
	"$schema": "https://emdashcms.com/seed.schema.json",
	"version": "1",
	"meta": {},
	"settings": {},
	"collections": [],
	"taxonomies": [],
	"bylines": [],
	"menus": [],
	"redirects": [],
	"widgetAreas": [],
	"sections": [],
	"content": {}
}

Meta

meta 物件包含有關 seed 的可選描述性中繼資料：

{
	"meta": {
		"name": "Blog Starter",
		"description": "A simple blog with posts, pages, and categories",
		"author": "EmDash"
	}
}

Settings

settings 物件包含網站範圍的設定值：

{
	"settings": {
		"title": "My Site",
		"tagline": "A modern CMS",
		"postsPerPage": 10,
		"dateFormat": "MMMM d, yyyy"
	}
}

設定套用於帶有 site: 前綴的 options 資料表。設定精靈將從 seed 檔案（如果提供）預填 title 和 tagline，允許使用者在初始設定期間覆寫它們。

Collections

每個集合定義在資料庫中建立一個內容類型：

{
	"collections": [
		{
			"slug": "posts",
			"label": "Posts",
			"labelSingular": "Post",
			"description": "Blog posts",
			"icon": "file-text",
			"supports": ["drafts", "revisions"],
			"fields": [
				{
					"slug": "title",
					"label": "Title",
					"type": "string",
					"required": true
				},
				{
					"slug": "content",
					"label": "Content",
					"type": "portableText"
				},
				{
					"slug": "featured_image",
					"label": "Featured Image",
					"type": "image"
				}
			]
		}
	]
}

集合屬性

欄位屬性

欄位類型

Taxonomies

分類法是內容的分類系統：

{
	"taxonomies": [
		{
			"name": "category",
			"label": "Categories",
			"labelSingular": "Category",
			"hierarchical": true,
			"collections": ["posts"],
			"terms": [
				{ "slug": "news", "label": "News" },
				{ "slug": "tutorials", "label": "Tutorials" },
				{
					"slug": "advanced",
					"label": "Advanced Tutorials",
					"parent": "tutorials"
				}
			]
		},
		{
			"name": "tag",
			"label": "Tags",
			"labelSingular": "Tag",
			"hierarchical": false,
			"collections": ["posts"]
		}
	]
}

分類法屬性

術語屬性

Menus

menus 陣列定義可從管理員編輯的導覽選單：

{
	"menus": [
		{
			"name": "primary",
			"label": "Primary Navigation",
			"items": [
				{ "type": "custom", "label": "Home", "url": "/" },
				{ "type": "page", "ref": "about" },
				{ "type": "custom", "label": "Blog", "url": "/posts" },
				{
					"type": "custom",
					"label": "External",
					"url": "https://example.com",
					"target": "_blank"
				}
			]
		}
	]
}

選單項目類型

選單項目屬性

Bylines

署名檔案與所有權（author_id）分開。定義一次可重複使用的署名身分，然後從內容項目引用它們。

{
	"bylines": [
		{
			"id": "editorial",
			"slug": "emdash-editorial",
			"displayName": "EmDash Editorial"
		},
		{
			"id": "guest",
			"slug": "guest-contributor",
			"displayName": "Guest Contributor",
			"isGuest": true
		}
	]
}

Redirects

redirects 陣列定義在遷移後保留舊版 URL 的重新導向規則：

{
	"redirects": [
		{ "source": "/old-about", "destination": "/about" },
		{ "source": "/legacy-feed", "destination": "/rss.xml", "type": 308 },
		{
			"source": "/category/news",
			"destination": "/categories/news",
			"groupName": "migration"
		}
	]
}

重新導向屬性

Widget Areas

widgetAreas 陣列定義可設定的內容區域：

{
	"widgetAreas": [
		{
			"name": "sidebar",
			"label": "Main Sidebar",
			"description": "Appears on blog posts and pages",
			"widgets": [
				{
					"type": "component",
					"title": "Recent Posts",
					"componentId": "core:recent-posts",
					"props": { "count": 5 }
				},
				{
					"type": "menu",
					"title": "Quick Links",
					"menuName": "footer"
				},
				{
					"type": "content",
					"title": "About",
					"content": [
						{
							"_type": "block",
							"style": "normal",
							"children": [{ "_type": "span", "text": "Welcome to our site!" }]
						}
					]
				}
			]
		}
	]
}

小工具類型

內建元件

Sections

Sections 是編輯者透過 /section 斜線命令插入到 Portable Text 欄位中的可重複使用內容區塊：

{
	"sections": [
		{
			"slug": "hero-centered",
			"title": "Centered Hero",
			"description": "Full-width hero with centered heading and CTA button",
			"keywords": ["hero", "banner", "header", "landing"],
			"content": [
				{
					"_type": "block",
					"style": "h1",
					"children": [{ "_type": "span", "text": "Welcome to Our Site" }]
				},
				{
					"_type": "block",
					"children": [
						{ "_type": "span", "text": "Your compelling tagline goes here." }
					]
				}
			]
		}
	]
}

Section 屬性

來自 seed 檔案的 sections 標記為 source: "theme"，不能從管理介面刪除。編輯者可以建立自己的 sections（source: "user"），並在編輯內容時插入任何 section 類型。

Content

content 物件包含按集合組織的範例內容項目：

{
	"content": {
		"posts": [
			{
				"id": "hello-world",
				"slug": "hello-world",
				"status": "published",
				"bylines": [
					{ "byline": "editorial" },
					{ "byline": "guest", "roleLabel": "Guest essay" }
				],
				"data": {
					"title": "Hello World",
					"content": [
						{
							"_type": "block",
							"style": "normal",
							"children": [{ "_type": "span", "text": "Welcome!" }]
						}
					],
					"excerpt": "Your first post."
				},
				"taxonomies": {
					"category": ["news"],
					"tag": ["welcome", "first-post"]
				}
			}
		],
		"pages": [
			{
				"id": "about",
				"slug": "about",
				"status": "published",
				"data": {
					"title": "About Us",
					"content": [
						{
							"_type": "block",
							"style": "normal",
							"children": [{ "_type": "span", "text": "About page content." }]
						}
					]
				}
			}
		]
	}
}

內容項目屬性

Content References

使用 $ref: 前綴引用其他內容項目：

{
	"data": {
		"related_posts": ["$ref:another-post", "$ref:third-post"]
	}
}

$ref: 前綴在種子期間將 seed ID 解析為資料庫 ID。

Media References

從 URL 包含圖像：

{
	"data": {
		"featured_image": {
			"$media": {
				"url": "https://images.unsplash.com/photo-xxx",
				"alt": "Description of the image",
				"filename": "hero.jpg",
				"caption": "Photo by Someone"
			}
		}
	}
}

從 .emdash/media/ 包含本地圖像：

{
	"data": {
		"featured_image": {
			"$media": {
				"file": "hero.jpg",
				"alt": "Description of the image"
			}
		}
	}
}

媒體屬性

*需要 url 或 file 之一，但不能同時需要兩者。

Applying Seeds Programmatically

對 CLI 工具或腳本使用 seed API：

import { applySeed, validateSeed } from "emdash/seed";
import seedData from "./.emdash/seed.json";

// 首先驗證
const validation = validateSeed(seedData);
if (!validation.valid) {
	console.error(validation.errors);
	process.exit(1);
}

// 套用 seed
const result = await applySeed(db, seedData, {
	includeContent: true,
	onConflict: "skip",
	storage: myStorage,
	baseUrl: "http://localhost:4321",
});

console.log(result);
// {
//   collections: { created: 2, skipped: 0 },
//   fields: { created: 8, skipped: 0 },
//   taxonomies: { created: 2, terms: 5 },
//   bylines: { created: 2, skipped: 0 },
//   menus: { created: 1, items: 4 },
//   redirects: { created: 3, skipped: 0 },
//   widgetAreas: { created: 1, widgets: 3 },
//   settings: { applied: 3 },
//   content: { created: 3, skipped: 0 },
//   media: { created: 2, skipped: 0 }
// }

Apply 選項

Idempotency

種子可以安全地執行多次。按實體類型的衝突行為：

Validation

Seed 檔案在套用之前進行驗證：

import { validateSeed } from "emdash/seed";

const { valid, errors, warnings } = validateSeed(seedData);

if (!valid) {
	errors.forEach((e) => console.error(e));
}

warnings.forEach((w) => console.warn(w));

驗證檢查：

• 必需欄位存在
• Slug 對其類型有效（集合和欄位 slug 允許小寫字母、數字和底線；其他 slug 還允許連字號）
• 欄位類型有效
• 引用指向現有內容
• 階層式術語父級存在
• 重新導向路徑是安全的本地 URL
• 重新導向來源是唯一的
• 集合中沒有重複的 slug

CLI Commands

.emdash/seed.json、package.json#emdash.seed 或 seed/seed.json 中的 seed 檔案被內嵌到建置中，並在資料庫為空時的第一個請求時套用。要將現有網站的結構（以及可選的其內容）匯出為 seed 檔案：

# `mkdir -p` 因為在新專案上 .emdash/ 可能還不存在
mkdir -p .emdash

# 將目前結構匯出為 seed 檔案
npx emdash export-seed > .emdash/seed.json

# 匯出包含內容
npx emdash export-seed --with-content > .emdash/seed.json

Next Steps

• Creating Themes — 建立完整主題
• Themes Overview — 主題如何運作