building-emdash-site

构建 EmDash 站点

EmDash 是基于 Astro 构建的 CMS。它将架构存储在数据库中（而非代码中），通过实时内容集合提供内容，并在 /_emdash/admin 提供完整的管理界面。站点是标准的 Astro 项目，并集成了 emdash。

常见陷阱

以下问题可能会在不报错的情况下导致站点无法正常运行。开始前请先了解。

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 是 slug；对于 URL 带有语言前缀的语言，它会带上语言前缀（例如 en/my-post；用于 URL；entry.data.slug 则是不带前缀的 slug）。entry.data.id 是数据库 ULID（用于 getEntryTerms、Comments 及其他需要真实 ID 的 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. 配置项目

阅读 references/configuration.md，了解 astro.config.mjs、live.config.ts、部署目标（Node 或 Cloudflare）和类型生成。

2. 设计架构

阅读 references/schema-and-seed.md，了解集合定义、字段类型、分类、菜单、小组件区域、分区、署名，以及完整的种子文件格式。

3. 构建页面

阅读 references/querying-and-rendering.md，了解内容查询、Portable Text 渲染、Image 组件、可视化编辑属性、缓存，以及常见页面模式（列表、详情、分类归档、RSS、搜索、404）。

4. 接入站点功能

阅读 references/site-features.md，了解站点设置、导航菜单、分类、小组件区域、搜索、SEO 元数据、评论和页面贡献。

5. 创建种子文件

编写 seed/seed.json，其中包含集合、字段、分类、菜单、小组件和示例内容。

6. 运行并验证

pnpm dev                # Start the Astro dev server

运行时会在首次请求时运行待处理的迁移；在完成设置之前，还会应用一次种子数据中的架构和结构。示例内容需要显式执行步骤；请参阅应用种子数据。Astro 集成会在服务器启动时生成 emdash-env.d.ts。管理界面位于 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 支持通过钩子、存储、设置、管理界面、API 路由和自定义 Portable Text 块类型扩展 CMS。以下情况可以考虑使用插件：

• 响应内容生命周期事件（例如，发布时发送通知、与外部服务同步）
• 添加自定义管理页面或仪表板组件
• 添加可复用的行为或自定义 Portable Text 类型（例如，嵌入式地图或代码 playground）
• 提供可复用的服务（例如，通过第三方提供商提供分析、表单、评论功能）

在 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/）。该技能涵盖插件结构、钩子、存储、管理界面、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、评论、页面扩展