commit bde1af8ccf9aec84775b777d9f605e37a4efe9b5 Author: Nox Date: Thu Apr 2 19:25:13 2026 +0200 feat: initial emdash setup with Docker + QNAP config diff --git a/.agents/skills/building-emdash-site/SKILL.md b/.agents/skills/building-emdash-site/SKILL.md new file mode 100644 index 0000000..d4852da --- /dev/null +++ b/.agents/skills/building-emdash-site/SKILL.md @@ -0,0 +1,150 @@ +--- +name: building-emdash-site +description: Build and customize EmDash CMS sites on Astro. Use when creating pages, defining collections, writing seed files, querying content, rendering Portable Text, setting up menus/taxonomies/widgets, configuring deployment, or any task involving an EmDash-powered Astro site. Assumes basic Astro knowledge but provides all EmDash-specific patterns. +--- + +# Building an EmDash Site + +EmDash is a CMS built on Astro. It stores schema in the database (not in code), serves content via live content collections, and provides a full admin UI at `/_emdash/admin`. Sites are standard Astro projects with the `emdash` integration. + +## Common Gotchas + +These are the things that silently break sites. Know them before you start. + +1. **Image fields are objects, not strings.** `post.data.featured_image` is `{ id, src, alt }`. Writing `` renders `[object Object]`. Use `` from `"emdash/ui"`. + +2. **`entry.id` vs `entry.data.id` are different things.** `entry.id` is the slug (use in URLs). `entry.data.id` is the database ULID (use for `getEntryTerms`, `Comments`, and other API calls that need the real ID). Mixing them up causes silent empty results. + +3. **Taxonomy names must match the seed exactly.** If your seed defines `"name": "category"`, you must query `getTerm("category", slug)` -- not `"categories"`. Wrong name = empty results, no error. + +4. **Always pass `cacheHint` to `Astro.cache.set()`.** Every query returns a `cacheHint`. Call `Astro.cache.set(cacheHint)` on every page that queries content, or cache invalidation won't work when editors publish changes. + +5. **No `getStaticPaths` for CMS content.** EmDash content is dynamic. Pages must be server-rendered (`output: "server"` in `astro.config.mjs`). + +## File Structure + +Every EmDash site has these key files: + +``` +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 +``` + +## Workflow + +### 1. Configure the project + +Read **[references/configuration.md](references/configuration.md)** for `astro.config.mjs`, `live.config.ts`, deployment targets (Node vs Cloudflare), and type generation. + +### 2. Design the schema + +Read **[references/schema-and-seed.md](references/schema-and-seed.md)** for collection definitions, field types, taxonomies, menus, widget areas, sections, bylines, and the complete seed file format. + +### 3. Build the pages + +Read **[references/querying-and-rendering.md](references/querying-and-rendering.md)** for content queries, Portable Text rendering, the Image component, visual editing attributes, caching, and common page patterns (list, detail, taxonomy archive, RSS, search, 404). + +### 4. Wire up site features + +Read **[references/site-features.md](references/site-features.md)** for site settings, navigation menus, taxonomies, widget areas, search, SEO meta, comments, and page contributions. + +### 5. Create the seed file + +Write `seed/seed.json` with collections, fields, taxonomies, menus, widgets, and sample content. Validate with: + +```bash +npx emdash seed seed/seed.json --validate +``` + +### 6. Run and verify + +```bash +npx emdash dev # Start dev server (runs migrations + seeds, and generates types) +``` + +The admin UI is at `http://localhost:4321/_emdash/admin`. + +## Quick API Cheat Sheet + +```typescript +// 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 } = await getEmDashEntry("posts", slug); + +// Site features +import { + getSiteSettings, + getMenu, + getTaxonomyTerms, + getTerm, + getEntryTerms, + getEntriesByTerm, + getWidgetArea, + search, + getSection, + getSeoMeta, +} from "emdash"; + +// Bylines (standalone queries -- usually not needed since entries have bylines attached) +import { getEntryBylines, getBylinesForEntries, getByline, getBylineBySlug } from "emdash"; + +// UI components +import { + PortableText, + Image, + Comments, + CommentForm, + WidgetArea, + EmDashHead, + EmDashBodyStart, + EmDashBodyEnd, +} from "emdash/ui"; +import LiveSearch from "emdash/ui/search"; + +// Page context (for plugin contributions) +import { createPublicPageContext } from "emdash/page"; +``` + +## Plugins + +EmDash supports plugins for extending the CMS with hooks, storage, settings, admin UI, API routes, and custom Portable Text block types. Consider a plugin when you need to: + +- React to content lifecycle events (e.g., send a notification on publish, sync to an external service) +- Add custom admin pages or dashboard widgets +- Add custom block types to the Portable Text editor (e.g., embedded maps, code playgrounds, CTAs) +- Provide a reusable service (e.g., analytics, forms, comments via a third-party provider) + +Plugins are registered in `astro.config.mjs`: + +```javascript +emdash({ + database: sqlite({ url: "file:./data.db" }), + storage: local({ directory: "./uploads", baseUrl: "/_emdash/api/media/file" }), + plugins: [myPlugin()], +}), +``` + +**To build a plugin, load the `creating-plugins` skill** (in `.agents/skills/creating-plugins/`). It covers plugin anatomy, hooks, storage, admin UI, API routes, Portable Text blocks, capabilities, and the full `definePlugin()` API. + +## Reference Documents + +| File | Contents | +| ---------------------------------------------------------------------------- | ------------------------------------------------------------------- | +| [references/configuration.md](references/configuration.md) | Project setup, astro.config, live.config, deployment, types | +| [references/schema-and-seed.md](references/schema-and-seed.md) | Collections, fields, taxonomies, menus, widgets, seed format | +| [references/querying-and-rendering.md](references/querying-and-rendering.md) | Content APIs, PortableText, Image, caching, page patterns | +| [references/site-features.md](references/site-features.md) | Settings, menus, widgets, search, SEO, comments, page contributions | diff --git a/.agents/skills/building-emdash-site/references/configuration.md b/.agents/skills/building-emdash-site/references/configuration.md new file mode 100644 index 0000000..68d3b81 --- /dev/null +++ b/.agents/skills/building-emdash-site/references/configuration.md @@ -0,0 +1,193 @@ +# Configuration + +## astro.config.mjs + +### Node.js (local development / self-hosted) + +```javascript +import node from '@astrojs/node'; +import react from '@astrojs/react'; +import { defineConfig } from 'astro/config'; +import emdash, { local } from 'emdash/astro'; +import { sqlite } from 'emdash/db'; + +export default defineConfig({ + output: 'server', + adapter: node({ mode: 'standalone' }), + image: { + layout: 'constrained', + responsiveStyles: true, + }, + integrations: [ + react(), + emdash({ + database: sqlite({ url: 'file:./data.db' }), + storage: local({ + directory: './uploads', + baseUrl: '/_emdash/api/media/file', + }), + }), + ], + devToolbar: { enabled: false }, +}); +``` + +### Cloudflare (D1 + R2) + +```javascript +import cloudflare from '@astrojs/cloudflare'; +import react from '@astrojs/react'; +import { d1, r2 } from '@emdash-cms/cloudflare'; +import { defineConfig } from 'astro/config'; +import emdash from 'emdash/astro'; + +export default defineConfig({ + output: 'server', + adapter: cloudflare(), + image: { + layout: 'constrained', + responsiveStyles: true, + }, + integrations: [ + react(), + emdash({ + database: d1({ binding: 'DB', session: 'auto' }), + storage: r2({ binding: 'MEDIA' }), + }), + ], + devToolbar: { enabled: false }, +}); +``` + +Requires a `wrangler.jsonc` with D1 and R2 bindings: + +```jsonc +{ + "name": "my-site", + "compatibility_date": "2026-03-29", + "compatibility_flags": ["nodejs_compat"], + "assets": { "directory": "./dist" }, + "d1_databases": [ + { + "binding": "DB", + "database_name": "my-site", + // from `wrangler d1 create my-site` + }, + ], + "r2_buckets": [ + { + "binding": "MEDIA", + "bucket_name": "my-site-media", + }, + ], +} +``` + +### Plugins + +Register plugins in `astro.config.mjs`: + +```javascript +import { auditLogPlugin } from "@emdash-cms/plugin-audit-log"; + +emdash({ + database: sqlite({ url: "file:./data.db" }), + storage: local({ directory: "./uploads", baseUrl: "/_emdash/api/media/file" }), + plugins: [auditLogPlugin()], +}), +``` + +## live.config.ts + +Every EmDash site needs this file at `src/live.config.ts`. It's boilerplate -- the same in every project: + +```typescript +import { defineLiveCollection } from 'astro:content'; +import { emdashLoader } from 'emdash/runtime'; + +export const collections = { + _emdash: defineLiveCollection({ loader: emdashLoader() }), +}; +``` + +This registers EmDash's live content collections with Astro. All content types are served through the single `_emdash` collection -- you query specific types using `getEmDashCollection("posts")` etc. + +## emdash-env.d.ts + +Auto-generated at the project root when the dev server starts. Provides TypeScript types for your collections. This is the file your `tsconfig.json` includes. + +```typescript +/// + +import type { PortableTextBlock } from 'emdash'; + +export interface Post { + id: string; + slug: string | null; + status: string; + title: string; + featured_image?: { + id: string; + src?: string; + alt?: string; + width?: number; + height?: number; + }; + content?: PortableTextBlock[]; + excerpt?: string; + createdAt: Date; + updatedAt: Date; + publishedAt: Date | null; +} + +declare module 'emdash' { + interface EmDashCollections { + posts: Post; + } +} +``` + +The dev server regenerates this file automatically when schema changes. You can also generate it manually: + +## Type Generation + +```bash +# From local dev server (writes emdash-env.d.ts at project root) +npx emdash types + +# From remote instance +npx emdash types --url https://my-site.pages.dev + +# Custom output path +npx emdash types --output src/types/cms.ts +``` + +The CLI also writes `.emdash/schema.json` with the raw schema for tooling. + +## package.json + +Key dependencies for a Node.js site: + +```json +{ + "dependencies": { + "astro": "^6.0.0", + "emdash": "^0.0.3", + "@astrojs/node": "^9.0.0", + "@astrojs/react": "^4.0.0", + "react": "^18.0.0", + "react-dom": "^18.0.0" + } +} +``` + +For Cloudflare, replace `@astrojs/node` with `@astrojs/cloudflare` and add `@emdash-cms/cloudflare`. + +## Dev Server + +```bash +npx emdash dev # Start dev server (runs migrations, applies seed) +npx emdash dev --types # Start and generate types from schema +``` + +The admin UI is at `http://localhost:4321/_emdash/admin`. On first run, you'll go through setup to create an admin account. diff --git a/.agents/skills/building-emdash-site/references/querying-and-rendering.md b/.agents/skills/building-emdash-site/references/querying-and-rendering.md new file mode 100644 index 0000000..e568f8b --- /dev/null +++ b/.agents/skills/building-emdash-site/references/querying-and-rendering.md @@ -0,0 +1,388 @@ +# Querying and Rendering Content + +## Content Queries + +All query functions are imported from `"emdash"`. + +### getEmDashCollection + +Fetch multiple entries from a collection. Returns `{ entries, error, cacheHint, nextCursor }`. + +```typescript +import { getEmDashCollection } from "emdash"; + +// Basic +const { entries: posts } = await getEmDashCollection("posts"); + +// With options +const { entries: posts, cacheHint } = await getEmDashCollection("posts", { + status: "published", + limit: 10, + orderBy: { published_at: "desc" }, + where: { category: "news" }, +}); +``` + +Options: + +- `status` -- filter by status (`"published"`, `"draft"`, etc.) +- `limit` -- max entries +- `cursor` -- opaque cursor for keyset pagination (pass `nextCursor` from a previous result) +- `orderBy` -- `{ field: "asc" | "desc" }` (default: `{ created_at: "desc" }`) +- `where` -- filter by field values or taxonomy terms. Supports arrays for OR: `{ category: ["news", "featured"] }` +- `locale` -- filter by locale (when i18n is configured) + +### getEmDashEntry + +Fetch a single entry by slug. Returns `{ entry, error, isPreview, cacheHint }`. + +```typescript +import { getEmDashEntry } from "emdash"; + +const { entry: post, cacheHint } = await getEmDashEntry("posts", slug); + +if (!post) { + return Astro.redirect("/404"); +} +``` + +### Entry Shape + +```typescript +interface ContentEntry { + id: string; // The slug (used in URLs) + data: T; // All fields, including system fields + edit: EditProxy; // Visual editing attributes (spread onto elements) +} + +// data includes system fields plus your custom fields: +interface PostData { + id: string; // Database ULID (use for taxonomy lookups, etc.) + slug: string; + status: string; + title: string; + featured_image?: { + id: string; + src?: string; + alt?: string; + width?: number; + height?: number; + }; + content?: PortableTextBlock[]; + createdAt: Date; + updatedAt: Date; + publishedAt: Date | null; + // Bylines (eagerly loaded) + byline: BylineSummary | null; // Primary author + bylines: ContentBylineCredit[]; // All credits (with roleLabel, source) + // ... your custom fields +} +``` + +**Important:** `entry.id` is the slug (for URLs), `entry.data.id` is the database ULID (for API calls like `getEntryTerms`). + +### Caching + +Query results include a `cacheHint` for Astro's Route Caching: + +```astro +--- +const { entries: posts, cacheHint } = await getEmDashCollection("posts"); +Astro.cache.set(cacheHint); +--- +``` + +Always call `Astro.cache.set(cacheHint)` -- it enables automatic cache invalidation when content changes. + +## Rendering Portable Text + +### PortableText component + +```astro +--- +import { PortableText } from "emdash/ui"; +--- + +``` + +Renders standard blocks (paragraphs, headings, lists, blockquotes, code blocks, images) and inline marks (bold, italic, code, strikethrough, links). + +### Custom block types + +For custom PT blocks (e.g., marketing components), pass a `components` prop: + +```astro +--- +import { PortableText } from "emdash/ui"; +import Hero from "./blocks/Hero.astro"; +import Features from "./blocks/Features.astro"; + +const customTypes = { + "marketing.hero": Hero, + "marketing.features": Features, +}; +--- + +``` + +Each custom component receives the block data as props. + +## Image Component + +**Always use the EmDash Image component for CMS images.** Image fields are objects, not strings. + +```astro +--- +import { Image } from "emdash/ui"; +--- + +{/* Correct -- passes the image object */} + + +{/* Also works with explicit props */} +{post.data.featured_image?.src && ( + {post.data.featured_image.alt +)} +``` + +**Common mistake:** + +```astro +{/* WRONG -- image is an object, not a string */} + +``` + +## Visual Editing Attributes + +Entries include `edit` attributes for inline editing. Spread them onto the element that displays the field: + +```astro +

{post.data.title}

+

{post.data.excerpt}

+
+ +
+``` + +When an admin is logged in and views the site, these attributes enable click-to-edit functionality. + +## Common Page Patterns + +### List page (e.g., `/posts/index.astro`) + +```astro +--- +import { getEmDashCollection, getEntryTerms } from "emdash"; +import { Image } from "emdash/ui"; +import Base from "../../layouts/Base.astro"; + +const { entries: posts, cacheHint } = await getEmDashCollection("posts", { + orderBy: { published_at: "desc" }, +}); +Astro.cache.set(cacheHint); + +const sortedPosts = posts.toSorted((a, b) => { + const dateA = a.data.publishedAt?.getTime() ?? 0; + const dateB = b.data.publishedAt?.getTime() ?? 0; + return dateB - dateA; +}); +--- + + {sortedPosts.map(post => ( +
+ {post.data.featured_image && } + {post.data.title} + {post.data.excerpt &&

{post.data.excerpt}

} +
+ ))} + +``` + +### Detail page (e.g., `/posts/[slug].astro`) + +```astro +--- +import { getEmDashEntry, getEntryTerms, getSeoMeta } from "emdash"; +import { Image, PortableText } from "emdash/ui"; +import Base from "../../layouts/Base.astro"; + +const { slug } = Astro.params; +if (!slug) return Astro.redirect("/404"); + +const { entry: post, cacheHint } = await getEmDashEntry("posts", slug); +if (!post) return Astro.redirect("/404"); + +Astro.cache.set(cacheHint); + +const seo = getSeoMeta(post, { + siteTitle: "My Blog", + siteUrl: Astro.url.origin, + path: `/posts/${slug}`, +}); + +const tags = await getEntryTerms("posts", post.data.id, "tag"); +--- + +
+ {post.data.featured_image && ( +
+ +
+ )} +

{post.data.title}

+ + {tags.length > 0 && ( +
+ {tags.map(t => {t.label})} +
+ )} +
+ +``` + +### Taxonomy archive (e.g., `/category/[slug].astro`) + +```astro +--- +import { getTerm, getEmDashCollection } from "emdash"; +import Base from "../../layouts/Base.astro"; + +const { slug } = Astro.params; +const term = slug ? await getTerm("category", slug) : null; +if (!term) return Astro.redirect("/404"); + +const { entries: posts } = await getEmDashCollection("posts", { + where: { category: term.slug }, + orderBy: { published_at: "desc" }, +}); +--- + +

{term.label}

+ {posts.map(post => ( + {post.data.title} + ))} + +``` + +### RSS feed (e.g., `/rss.xml.ts`) + +```typescript +import type { APIRoute } from "astro"; +import { getEmDashCollection } from "emdash"; + +const siteTitle = "My Site"; + +export const GET: APIRoute = async ({ url }) => { + const siteUrl = url.origin; + const { entries: posts } = await getEmDashCollection("posts", { + orderBy: { published_at: "desc" }, + limit: 20, + }); + + const items = posts + .filter((p) => p.data.publishedAt) + .map((post) => { + const postUrl = `${siteUrl}/posts/${post.id}`; + return ` + ${escapeXml(post.data.title)} + ${postUrl} + ${postUrl} + ${post.data.publishedAt!.toUTCString()} + ${escapeXml(post.data.excerpt || "")} + `; + }) + .join("\n"); + + return new Response( + ` + + + ${escapeXml(siteTitle)} + ${siteUrl} + + en-us + ${new Date().toUTCString()} +${items} + +`, + { + headers: { + "Content-Type": "application/rss+xml; charset=utf-8", + "Cache-Control": "public, max-age=3600", + }, + }, + ); +}; + +function escapeXml(s: string): string { + return s + .replace(/&/g, "&") + .replace(//g, ">") + .replace(/"/g, """) + .replace(/'/g, "'"); +} +``` + +### 404 page (`/404.astro`) + +```astro +--- +import Base from "../layouts/Base.astro"; +--- + +

Page not found

+

The page you're looking for doesn't exist.

+ Go home + +``` + +### Empty state + +When a collection has no content, show a helpful empty state: + +```astro +{posts.length === 0 ? ( +
+

No posts yet

+

Create your first post in the admin panel.

+ Create a post +
+) : ( + /* ... render posts ... */ +)} +``` + +## Pagination + +`getEmDashCollection` supports cursor-based keyset pagination. Pass `cursor` from a previous result's `nextCursor` to get the next page: + +```astro +--- +const cursor = Astro.url.searchParams.get("cursor") ?? undefined; +const { entries, nextCursor, cacheHint } = await getEmDashCollection("posts", { + limit: 10, + cursor, + orderBy: { published_at: "desc" }, +}); +Astro.cache.set(cacheHint); +--- +{entries.map(post => ( + {post.data.title} +))} +{nextCursor && Next page} +``` + +`nextCursor` is `undefined` when there are no more results. + +## Date Formatting + +Dates come as `Date` objects. Use `toLocaleDateString` or `Intl.DateTimeFormat`: + +```typescript +const formatted = post.data.publishedAt?.toLocaleDateString("en-US", { + year: "numeric", + month: "long", + day: "numeric", +}); +``` diff --git a/.agents/skills/building-emdash-site/references/schema-and-seed.md b/.agents/skills/building-emdash-site/references/schema-and-seed.md new file mode 100644 index 0000000..378c657 --- /dev/null +++ b/.agents/skills/building-emdash-site/references/schema-and-seed.md @@ -0,0 +1,469 @@ +# Schema and Seed Files + +The seed file (`seed/seed.json`) defines the site's entire schema and optional demo content. It's applied on first run or via `npx emdash seed seed/seed.json`. + +## Seed File Structure + +```json +{ + "$schema": "https://emdashcms.com/seed.schema.json", + "version": "1", + "meta": { + "name": "My Site", + "description": "A description of this site", + "author": "Author Name" + }, + "settings": { ... }, + "collections": [ ... ], + "taxonomies": [ ... ], + "menus": [ ... ], + "widgetAreas": [ ... ], + "sections": [ ... ], + "bylines": [ ... ], + "content": { ... } +} +``` + +## Collections + +Collections define content types. Each collection becomes a database table (`ec_{slug}`). + +```json +{ + "slug": "posts", + "label": "Posts", + "labelSingular": "Post", + "supports": ["drafts", "revisions", "search", "seo"], + "commentsEnabled": true, + "fields": [ ... ] +} +``` + +### Collection Supports + +| Support | Description | +| ----------- | ------------------------- | +| `drafts` | Draft/published workflow | +| `revisions` | Revision history | +| `search` | Full-text search indexing | +| `seo` | SEO meta fields in admin | + +### Slug Rules + +- Lowercase alphanumeric + underscores: `/^[a-z][a-z0-9_]*$/` +- Max 63 characters +- Cannot conflict with reserved slugs + +## Field Types + +| Type | Column type | Runtime shape | Notes | +| -------------- | ----------- | ------------------------------------- | ---------------------------- | +| `string` | TEXT | `string` | Single line text | +| `text` | TEXT | `string` | Multi-line text (textarea) | +| `number` | REAL | `number` | Floating point | +| `integer` | INTEGER | `number` | Whole numbers | +| `boolean` | INTEGER | `boolean` | Stored as 0/1 | +| `datetime` | TEXT | `Date` | ISO 8601 string in DB | +| `image` | TEXT | `{ id, src?, alt?, width?, height? }` | **Object, not a string** | +| `reference` | TEXT | `string` (ID) | Reference to another entry | +| `portableText` | JSON | `PortableTextBlock[]` | Rich text as structured JSON | +| `json` | JSON | `any` | Arbitrary JSON data | + +### Field Definition + +```json +{ + "slug": "title", + "label": "Title", + "type": "string", + "required": true, + "searchable": true +} +``` + +Fields can have: + +- `slug` (required) -- field identifier +- `label` (required) -- display label in admin +- `type` (required) -- one of the types above +- `required` -- validation +- `searchable` -- include in full-text search index + +### Common Field Patterns + +**Blog post:** + +```json +"fields": [ + { "slug": "title", "label": "Title", "type": "string", "required": true, "searchable": true }, + { "slug": "featured_image", "label": "Featured Image", "type": "image" }, + { "slug": "content", "label": "Content", "type": "portableText", "searchable": true }, + { "slug": "excerpt", "label": "Excerpt", "type": "text" } +] +``` + +**Portfolio project:** + +```json +"fields": [ + { "slug": "title", "label": "Title", "type": "string", "required": true, "searchable": true }, + { "slug": "featured_image", "label": "Featured Image", "type": "image", "required": true }, + { "slug": "client", "label": "Client", "type": "string" }, + { "slug": "year", "label": "Year", "type": "string" }, + { "slug": "summary", "label": "Summary", "type": "text", "searchable": true }, + { "slug": "content", "label": "Content", "type": "portableText", "searchable": true }, + { "slug": "gallery", "label": "Gallery", "type": "json" }, + { "slug": "url", "label": "Project URL", "type": "string" } +] +``` + +**Page (minimal):** + +```json +"fields": [ + { "slug": "title", "label": "Title", "type": "string", "required": true, "searchable": true }, + { "slug": "content", "label": "Content", "type": "portableText", "searchable": true } +] +``` + +## Taxonomies + +Taxonomies are tag/category systems attached to collections. + +```json +{ + "name": "category", + "label": "Categories", + "labelSingular": "Category", + "hierarchical": true, + "collections": ["posts"], + "terms": [ + { "slug": "development", "label": "Development" }, + { "slug": "design", "label": "Design" } + ] +} +``` + +- `hierarchical: true` -- tree structure (like WordPress categories) +- `hierarchical: false` -- flat list (like WordPress tags) +- `collections` -- which collections this taxonomy applies to +- `terms` -- pre-defined terms to create + +## Menus + +Navigation menus, managed from the admin UI. + +```json +{ + "name": "primary", + "label": "Primary Navigation", + "items": [ + { "type": "custom", "label": "Home", "url": "/" }, + { "type": "custom", "label": "About", "url": "/pages/about" }, + { "type": "custom", "label": "Posts", "url": "/posts" } + ] +} +``` + +Menu item types: + +- `custom` -- arbitrary URL +- Content references are resolved at render time + +## Widget Areas + +Named regions where editors can add configurable widgets. + +```json +{ + "name": "sidebar", + "label": "Sidebar", + "description": "Widget area displayed on single post pages", + "widgets": [ + { + "type": "component", + "componentId": "core:search", + "title": "Search" + }, + { + "type": "component", + "componentId": "core:categories", + "title": "Categories" + }, + { + "type": "component", + "componentId": "core:tags", + "title": "Tags" + }, + { + "type": "component", + "componentId": "core:recent-posts", + "title": "Recent Posts", + "settings": { "count": 5, "showDate": true } + }, + { + "type": "component", + "componentId": "core:archives", + "title": "Archives", + "settings": { "type": "monthly", "limit": 6 } + }, + { + "type": "content", + "title": "About", + "content": [ + { + "_type": "block", + "style": "normal", + "children": [{ "_type": "span", "text": "Some rich text content." }] + } + ] + } + ] +} +``` + +### Widget types + +| Type | Description | Key fields | +| ----------- | ------------------------- | ------------------------- | +| `content` | Rich text (Portable Text) | `content` | +| `menu` | Navigation menu | `menuName` | +| `component` | Core or custom component | `componentId`, `settings` | + +### Core widget components + +- `core:search` -- search form +- `core:categories` -- category list with counts +- `core:tags` -- tag cloud +- `core:recent-posts` -- latest posts list +- `core:archives` -- monthly archive links + +## Sections (Reusable Blocks) + +Reusable content blocks that editors can insert via `/section` slash command in the editor. + +```json +{ + "slug": "newsletter-signup", + "title": "Newsletter Signup", + "description": "A call-to-action block for newsletter subscriptions", + "keywords": ["newsletter", "subscribe", "email", "cta"], + "source": "theme", + "content": [ + { + "_type": "block", + "style": "h3", + "children": [{ "_type": "span", "text": "Stay in the loop" }] + }, + { + "_type": "block", + "style": "normal", + "children": [{ "_type": "span", "text": "Get notified when new posts are published." }] + } + ] +} +``` + +## Bylines + +Named author profiles, independent of user accounts. + +```json +{ + "id": "byline-editorial", + "slug": "emdash-editorial", + "displayName": "EmDash Editorial" +} +``` + +Guest bylines: + +```json +{ + "id": "byline-guest", + "slug": "guest-contributor", + "displayName": "Guest Contributor", + "isGuest": true +} +``` + +## Settings + +Site-wide settings: + +```json +"settings": { + "title": "My Blog", + "tagline": "Thoughts on building for the web" +} +``` + +Available keys: `title`, `tagline`, `logo`, `favicon`, `social`, `timezone`, `dateFormat`. + +## Content + +Sample content organized by collection slug: + +```json +"content": { + "posts": [ + { + "id": "post-1", + "slug": "hello-world", + "status": "published", + "data": { + "title": "Hello World", + "excerpt": "My first post.", + "featured_image": { + "$media": { + "url": "https://images.unsplash.com/photo-xxx?w=1200&h=800&fit=crop", + "alt": "Description of image", + "filename": "hello-world.jpg" + } + }, + "content": [ + { + "_type": "block", + "style": "normal", + "children": [{ "_type": "span", "text": "This is the body text." }] + } + ] + }, + "bylines": [ + { "byline": "byline-editorial" } + ], + "taxonomies": { + "category": ["development"], + "tag": ["webdev", "opinion"] + } + } + ], + "pages": [ + { + "id": "about", + "slug": "about", + "status": "published", + "data": { + "title": "About", + "content": [ + { + "_type": "block", + "style": "normal", + "children": [{ "_type": "span", "text": "About this site." }] + } + ] + } + } + ] +} +``` + +### Media references in seed content + +Use `$media` for image fields -- EmDash downloads and stores the image: + +```json +"featured_image": { + "$media": { + "url": "https://images.unsplash.com/photo-xxx?w=1200&h=800&fit=crop", + "alt": "Description", + "filename": "my-image.jpg" + } +} +``` + +For external images without downloading: + +```json +"featured_image": "https://images.unsplash.com/photo-xxx?w=1200" +``` + +### Reference fields in seed content + +Use `$ref:id` format to reference other entries: + +```json +"author": "$ref:byline-editorial" +``` + +### Portable Text in seed content + +Content fields of type `portableText` are arrays of blocks: + +```json +[ + { + "_type": "block", + "style": "normal", + "children": [{ "_type": "span", "text": "A paragraph." }] + }, + { + "_type": "block", + "style": "h2", + "children": [{ "_type": "span", "text": "A heading" }] + }, + { + "_type": "block", + "style": "blockquote", + "children": [{ "_type": "span", "text": "A quote." }] + } +] +``` + +Inline marks (bold, italic, links): + +```json +{ + "_type": "block", + "style": "normal", + "children": [ + { "_type": "span", "text": "This is " }, + { "_type": "span", "text": "bold", "marks": ["strong"] }, + { "_type": "span", "text": " and " }, + { "_type": "span", "text": "italic", "marks": ["em"] } + ] +} +``` + +Block styles: `normal`, `h1`-`h6`, `blockquote`. + +### Draft content + +Set `"status": "draft"` to create unpublished content: + +```json +{ + "id": "post-draft", + "slug": "work-in-progress", + "status": "draft", + "data": { ... } +} +``` + +## Validation + +```bash +npx emdash seed seed/seed.json --validate +``` + +Catches: + +- Image fields with raw URLs (should use `$media`) +- Reference fields with raw IDs (should use `$ref:id`) +- PortableText not an array or missing `_type` +- Type mismatches (string vs number, etc.) + +## Applying Seeds + +```bash +npx emdash seed seed/seed.json # Apply with content +npx emdash seed seed/seed.json --no-content # Schema only (no sample content) +``` + +## Exporting Seeds + +```bash +npx emdash export-seed # Schema only +npx emdash export-seed --with-content # Schema + all content +npx emdash export-seed --with-content=posts,pages # Specific collections +``` diff --git a/.agents/skills/building-emdash-site/references/site-features.md b/.agents/skills/building-emdash-site/references/site-features.md new file mode 100644 index 0000000..40593b9 --- /dev/null +++ b/.agents/skills/building-emdash-site/references/site-features.md @@ -0,0 +1,495 @@ +# Site Features + +## Site Settings + +```typescript +import { getSiteSettings, getSiteSetting } from "emdash"; + +// All settings +const settings = await getSiteSettings(); +settings.title; // "My Site" +settings.tagline; // "A description" +settings.logo?.url; // Resolved media URL +settings.favicon?.url; + +// Single setting +const title = await getSiteSetting("title"); +``` + +Available keys: `title`, `tagline`, `logo`, `favicon`, `social`, `timezone`, `dateFormat`. + +Use these instead of hard-coding site name, logo, etc. + +## Navigation Menus + +```typescript +import { getMenu, getMenus } from "emdash"; + +// Fetch a named menu +const menu = await getMenu("primary"); + +// List all menus +const menus = await getMenus(); +``` + +### Rendering a menu + +```astro +--- +import { getMenu } from "emdash"; +const primaryMenu = await getMenu("primary"); +--- + +``` + +### Nested menus (dropdowns) + +```astro +{primaryMenu?.items.map(item => ( +
  • + {item.label} + {item.children.length > 0 && ( + + )} +
  • +))} +``` + +### MenuItem shape + +```typescript +interface MenuItem { + id: string; + label: string; + url: string; // Resolved URL + target?: string; // "_blank" etc. + children: MenuItem[]; +} +``` + +## Taxonomies + +```typescript +import { getTaxonomyTerms, getTerm, getEntryTerms, getEntriesByTerm } from "emdash"; + +// All terms in a taxonomy (name must match your seed's "name" field exactly) +const categories = await getTaxonomyTerms("category"); +const tags = await getTaxonomyTerms("tag"); + +// Single term by slug +const term = await getTerm("category", "news"); +// { id, name, slug, label, children, count } + +// Terms for a specific entry (use data.id, not entry.id!) +const postCategories = await getEntryTerms("posts", post.data.id, "category"); +const postTags = await getEntryTerms("posts", post.data.id, "tag"); + +// Entries with a specific term +const newsPosts = await getEntriesByTerm("posts", "category", "news"); +``` + +**Important:** The taxonomy name argument must match exactly what your seed defines in `"name"`. The blog seed uses `"category"` and `"tag"` (singular). Using `"categories"` returns empty results with no error. + +**Important:** `getEntryTerms` takes the database ULID (`post.data.id`), not the slug (`post.id`). + +### Displaying post terms + +```astro +--- +const tags = await getEntryTerms("posts", post.data.id, "tag"); +--- +{tags.map(t => ( + {t.label} +))} +``` + +### Filtering by taxonomy + +```astro +--- +const { entries: posts } = await getEmDashCollection("posts", { + where: { category: term.slug }, + orderBy: { published_at: "desc" }, +}); +--- +``` + +## Widget Areas + +Render a named widget area: + +```astro +--- +import { WidgetArea } from "emdash/ui"; +--- + +``` + +The `WidgetArea` component automatically renders all widgets in the area (search, categories, tags, recent posts, rich text, etc.) with appropriate HTML and CSS classes. + +### Manual widget rendering + +For more control, use the `getWidgetArea` function: + +```astro +--- +import { getWidgetArea } from "emdash"; +import { PortableText } from "emdash/ui"; + +const sidebar = await getWidgetArea("sidebar"); +--- +{sidebar?.widgets.map(widget => ( +
    + {widget.title &&

    {widget.title}

    } + {widget.type === "content" && widget.content && ( + + )} +
    +))} +``` + +## Search + +### LiveSearch component (instant search) + +```astro +--- +import LiveSearch from "emdash/ui/search"; +--- + +``` + +Customizable CSS classes: + +```astro + +``` + +Theme via CSS variables: + +```css +:root { + --emdash-search-bg: var(--color-bg); + --emdash-search-text: var(--color-text); + --emdash-search-muted: var(--color-muted); + --emdash-search-border: var(--color-border); + --emdash-search-hover: var(--color-surface); + --emdash-search-highlight: var(--color-text); +} +``` + +### Programmatic search + +```typescript +import { search } from "emdash"; + +const results = await search("hello world", { + collections: ["posts", "pages"], + status: "published", + limit: 20, +}); +// { results: SearchResult[], total, nextCursor? } +``` + +Each result has: `collection`, `id`, `title`, `slug`, `snippet` (HTML with `` highlights), `score`. + +### Search page + +```astro +--- +import LiveSearch from "emdash/ui/search"; +import Base from "../layouts/Base.astro"; + +const query = Astro.url.searchParams.get("q") || ""; +--- + +

    Search

    + + +``` + +### Keyboard shortcut + +Add Cmd+K / Ctrl+K to focus search: + +```html + +``` + +### Search prerequisites + +Search requires per-collection enablement: + +1. In admin: Edit Content Type -> check "Search" in Features +2. Mark fields as `"searchable": true` in the seed file +3. Only searchable fields of searchable collections are indexed + +## SEO Meta + +Generate SEO meta from content entries: + +```typescript +import { getSeoMeta } from "emdash"; + +const seo = getSeoMeta(post, { + siteTitle: "My Blog", + siteUrl: Astro.url.origin, + path: `/posts/${slug}`, + defaultOgImage: featuredImageUrl, // Optional fallback +}); + +// Returns: { title, description, canonical, ogImage, robots } +``` + +Use in your layout's ``: + +```astro +{seo.title} + + + +{seo.robots && } +``` + +## Comments + +Built-in comments system: + +```astro +--- +import { Comments, CommentForm } from "emdash/ui"; +--- + + +``` + +Comments are enabled per-collection in the seed: `"commentsEnabled": true`. + +## Page Contributions (Plugin Head/Body Injection) + +Plugins can inject content into the `` and `` of pages. To support this, use the page contribution components: + +```astro +--- +import { EmDashHead, EmDashBodyStart, EmDashBodyEnd } from "emdash/ui"; +import { createPublicPageContext } from "emdash/page"; + +const pageCtx = createPublicPageContext({ + Astro, + kind: content ? "content" : "custom", + pageType: "article", + title: fullTitle, + description, + canonical, + image, + content: { collection: "posts", id: post.data.id, slug }, +}); +--- + + + + + + + + + + + +``` + +This enables plugins (analytics, tracking pixels, structured data, etc.) to contribute to any page. + +## Bylines + +Bylines are author profiles, independent of user accounts. They support guest authors and multi-author attribution with role labels. + +### Eagerly loaded on entries + +Bylines are automatically attached to every entry by the query layer: + +```astro +{/* Primary author */} +{post.data.byline && ( + {post.data.byline.displayName} +)} + +{/* All credits (includes roleLabel for co-authors, guest essays, etc.) */} +{post.data.bylines?.map(credit => ( + + {credit.byline.displayName} + {credit.roleLabel && ({credit.roleLabel})} + +))} +``` + +- `entry.data.byline` -- primary `BylineSummary` or `null` +- `entry.data.bylines` -- array of `ContentBylineCredit` (each has `.byline`, `.roleLabel`, `.source`) + +### Standalone query functions + +```typescript +import { getEntryBylines, getByline, getBylineBySlug, getBylinesForEntries } from "emdash"; + +// Bylines for a single entry +const credits = await getEntryBylines("posts", post.data.id); + +// Batch-fetch for a list page (avoids N+1) +const ids = entries.map((e) => e.data.id); +const bylinesMap = await getBylinesForEntries("posts", ids); +// bylinesMap.get(entryId) => ContentBylineCredit[] + +// Look up a specific byline +const byline = await getBylineBySlug("jane-doe"); +``` + +### BylineSummary shape + +```typescript +interface BylineSummary { + id: string; + slug: string; + displayName: string; + bio: string | null; + avatarMediaId: string | null; + websiteUrl: string | null; + isGuest: boolean; +} +``` + +### ContentBylineCredit shape + +```typescript +interface ContentBylineCredit { + byline: BylineSummary; + sortOrder: number; + roleLabel: string | null; // e.g., "Guest essay", "Photographer" + source?: "explicit" | "inferred"; // "inferred" = fallback from author_id +} +``` + +## Dark Mode Pattern + +Cookie-based theme switching (no flash on load): + +```html + + +``` + +Then use CSS variables that change based on `.dark` class: + +```css +:root { + --color-bg: #ffffff; + --color-text: #1a1a1a; +} +:root.dark { + --color-bg: #0d0d0d; + --color-text: #ededed; +} +``` + +## Layout Pattern + +A typical base layout: + +```astro +--- +import { getMenu, getEmDashCollection } from "emdash"; +import { WidgetArea, EmDashHead, EmDashBodyStart, EmDashBodyEnd } from "emdash/ui"; +import { createPublicPageContext } from "emdash/page"; +import LiveSearch from "emdash/ui/search"; + +interface Props { + title: string; + description?: string | null; + image?: string | null; + content?: { collection: string; id: string; slug?: string | null }; +} + +const { title, description, image, content } = Astro.props; +const menu = await getMenu("primary"); + +const pageCtx = createPublicPageContext({ + Astro, + kind: content ? "content" : "custom", + pageType: "website", + title, + description, + image, + content, +}); +--- + + + + + + {title} + {description && } + + + + +
    + +
    +
    + +
    +
    + +
    + + + +``` diff --git a/.agents/skills/creating-plugins/SKILL.md b/.agents/skills/creating-plugins/SKILL.md new file mode 100644 index 0000000..5dc53d4 --- /dev/null +++ b/.agents/skills/creating-plugins/SKILL.md @@ -0,0 +1,457 @@ +--- +name: creating-plugins +description: Create EmDash CMS plugins with hooks, storage, settings, admin UI, API routes, and Portable Text block types. Use this skill when asked to build, scaffold, or implement an EmDash plugin, or when creating plugin features like custom block types, admin pages, or content hooks. +--- + +# Creating EmDash Plugins + +EmDash plugins extend the CMS with hooks, storage, settings, admin UI, API routes, and custom Portable Text block types. All plugins are TypeScript packages. + +## Plugin Types + +EmDash has two plugin formats: + +| Type | Format | Admin UI | Where it runs | +| ------------ | ------------------------------------------------------- | ------------------ | ------------------------------------------- | +| **Standard** | `definePlugin({ hooks, routes })` | Block Kit | Isolate on Cloudflare, in-process elsewhere | +| **Native** | `createPlugin()` / `definePlugin()` with `id`+`version` | React or Block Kit | Always in host isolate | + +**Standard is the default.** Most plugins should use it. Standard plugins can be published to the marketplace and work in both trusted and sandboxed modes. + +**Native is an escape hatch** for plugins that need React admin components, direct DB access, or custom Astro components. Native plugins can only run in `plugins: []` -- they cannot be sandboxed or published to the marketplace. + +## Plugin Anatomy + +Every plugin has two parts that **run in different contexts**: + +1. **Plugin descriptor** (`PluginDescriptor`) — returned by the factory function in `index.ts`. Declares metadata (id, version, capabilities, storage). **Runs at build time in Vite** (imported in `astro.config.mjs`). Must be side-effect-free. +2. **Plugin definition** (`definePlugin()`) — contains the runtime logic (hooks, routes). **Runs at request time on the deployed server.** Has access to the full plugin context (`ctx`). Lives in a separate file (typically `sandbox-entry.ts`). + +These must be in **separate entrypoints** because they execute in completely different environments: + +``` +my-plugin/ +├── src/ +│ ├── index.ts # Descriptor factory (runs in Vite at build time) +│ ├── sandbox-entry.ts # Plugin definition with definePlugin() (runs at deploy time) +│ ├── admin.tsx # Admin UI exports (React) — optional, native only +│ └── astro/ # Site-side rendering components — optional, native only +│ └── index.ts # Must export `blockComponents` +├── package.json +└── tsconfig.json +``` + +## Minimal Plugin (Standard Format) + +The simplest possible plugin -- just hooks: + +```typescript +// src/index.ts — descriptor factory, runs in Vite at build time +import type { PluginDescriptor } from "emdash"; + +export function myPlugin(): PluginDescriptor { + return { + id: "my-plugin", + version: "1.0.0", + format: "standard", + entrypoint: "@my-org/my-plugin/sandbox", + options: {}, + }; +} +``` + +```typescript +// src/sandbox-entry.ts — plugin definition, runs at request time +import { definePlugin } from "emdash"; +import type { PluginContext } from "emdash"; + +export default definePlugin({ + hooks: { + "content:afterSave": { + handler: async (event: any, ctx: PluginContext) => { + ctx.log.info(`Saved ${event.collection}/${event.content.id}`); + }, + }, + }, +}); +``` + +The descriptor is what gets imported in `astro.config.mjs`. The `entrypoint` field points to the module containing the `definePlugin()` default export. For standard plugins, this is the `./sandbox` export from `package.json`. + +Key differences from native format: + +- No `id`, `version`, or `capabilities` in `definePlugin()` -- those live in the descriptor +- `definePlugin()` is an identity function providing type inference +- Hook handlers use `(event, ctx)` two-arg pattern +- Route handlers use `(routeCtx, ctx)` two-arg pattern +- Exported as `default` (not a factory function) + +## Plugin ID Rules + +- Lowercase alphanumeric + hyphens only +- Simple (`my-plugin`) or scoped (`@my-org/my-plugin`) +- Unique across all installed plugins + +## Registration + +The descriptor is imported in `astro.config.mjs` (Vite context): + +```typescript +import { myPlugin } from "@my-org/my-plugin"; + +export default defineConfig({ + integrations: [ + emdash({ + plugins: [myPlugin()], // runs in-process + // OR + sandboxed: [myPlugin()], // runs in isolate on Cloudflare + }), + ], +}); +``` + +Standard plugins work in either array. Native plugins only work in `plugins: []`. + +## Trusted vs Sandboxed Plugins + +EmDash has two execution modes. Plugin code is identical in both — only the enforcement changes. + +| | Trusted | Sandboxed | +| ------------------- | ----------------------------------------- | ------------------------------------------------------ | +| **Runs in** | Main process | Isolated V8 isolate (Dynamic Worker Loader) | +| **Install method** | `astro.config.mjs` (code change + deploy) | Admin UI (one-click from marketplace) | +| **Capabilities** | Advisory (not enforced) | Enforced at runtime via RPC bridge | +| **Resource limits** | None | CPU 50ms, 10 subrequests, 30s wall-time, ~128MB memory | +| **Network access** | Unrestricted | Blocked; only via `ctx.http` with `allowedHosts` | +| **Data access** | Full database access | Scoped to declared capabilities | +| **Node.js APIs** | Full access | Not available (V8 isolate only) | +| **Available on** | All platforms | Cloudflare Workers only | +| **Best for** | First-party code, reviewed npm packages | Third-party extensions, marketplace plugins | + +### Trusted Mode + +Trusted plugins are npm packages or local files added in `astro.config.mjs`. They run in-process with your Astro site. + +- **Capabilities are documentation only.** Declaring `["read:content"]` documents intent but isn't enforced — the plugin has full process access. +- Only install from sources you trust. A malicious trusted plugin has the same access as your application code. + +### Sandboxed Mode + +Sandboxed plugins run in isolated V8 isolates on Cloudflare Workers via [Dynamic Worker Loader](https://developers.cloudflare.com/workers/runtime-apis/bindings/worker-loader/). Each plugin gets its own isolate. + +- **Capabilities are enforced.** If a plugin declares `["read:content"]`, it can only call `ctx.content.get()` and `ctx.content.list()`. Attempting `ctx.content.create()` throws a permission error. +- **Network is blocked by default.** Direct `fetch()` calls fail. Plugins must use `ctx.http.fetch()`, which validates against `allowedHosts`. +- **Storage is scoped.** A plugin can only access its own KV and storage collections. +- **Admin UI uses Block Kit.** Sandboxed plugins describe their UI as JSON blocks -- no plugin JavaScript runs in the browser. See [Block Kit reference](./references/block-kit.md). +- **No Portable Text block types.** PT blocks require Astro components for site-side rendering (`componentsEntry`), which are loaded at build time from npm. Sandboxed plugins are installed at runtime and can't ship components. PT blocks are a native-plugin-only feature. +- **Routes work.** Standard plugin routes are available in both trusted and sandboxed modes via the sandbox runner's `invokeRoute()` RPC. + +Sandboxing is not available on Node.js. All plugins run in trusted mode on non-Cloudflare platforms. + +### Developing for Both Modes + +Write the same code. Develop locally in trusted mode (faster iteration, easier debugging). Deploy to sandboxed mode in production without code changes. With the standard format, the same entrypoint serves both modes -- no separate sandbox entry needed. + +```typescript +// src/sandbox-entry.ts -- works in both trusted and sandboxed modes +import { definePlugin } from "emdash"; +import type { PluginContext } from "emdash"; + +export default definePlugin({ + hooks: { + "content:afterSave": { + handler: async (event: any, ctx: PluginContext) => { + // Trusted: ctx.http present because descriptor declares network:fetch + // Sandboxed: ctx.http present and enforced via RPC bridge + if (!ctx.http) return; + await ctx.http.fetch("https://api.analytics.example.com/track", { + method: "POST", + body: JSON.stringify({ contentId: event.content.id }), + }); + }, + }, + }, +}); +``` + +Key constraint for sandbox compatibility: **no Node.js built-ins** (`fs`, `path`, `child_process`, etc.) in backend code. Use Web APIs instead. + +## Capabilities + +Capabilities control what APIs are available on `ctx`. Always declare what your plugin needs — even in trusted mode, they document intent and are required for sandboxed execution. + +| Capability | Grants | `ctx` property | +| ----------------- | ---------------------------------------------------------------------- | -------------- | +| `read:content` | `ctx.content.get()`, `ctx.content.list()` | `content` | +| `write:content` | `ctx.content.create()`, `ctx.content.update()`, `ctx.content.delete()` | `content` | +| `read:media` | `ctx.media.get()`, `ctx.media.list()` | `media` | +| `write:media` | `ctx.media.getUploadUrl()`, `ctx.media.delete()` | `media` | +| `network:fetch` | `ctx.http.fetch()` (restricted to `allowedHosts`) | `http` | +| `read:users` | `ctx.users.get()`, `ctx.users.list()`, `ctx.users.getByEmail()` | `users` | +| `email:send` | `ctx.email.send()` — send email through the pipeline | `email` | +| `email:provide` | Can register `email:deliver` exclusive hook (transport provider) | — | +| `email:intercept` | Can register `email:beforeSend` / `email:afterSend` hooks | — | + +Storage (`ctx.storage`) and KV (`ctx.kv`) are **always available** — no capability needed. They're automatically scoped to the plugin. + +**Email capabilities are distinct:** + +- `email:send` — for plugins that _consume_ email (call `ctx.email.send()`) +- `email:provide` — for plugins that _deliver_ email (implement the transport, e.g. Resend, SMTP) +- `email:intercept` — for plugins that _observe or transform_ email (middleware hooks) + +```typescript +// In the descriptor (index.ts) +export function myPlugin(): PluginDescriptor { + return { + id: "my-plugin", + version: "1.0.0", + format: "standard", + entrypoint: "@my-org/my-plugin/sandbox", + options: {}, + capabilities: ["read:content", "network:fetch"], + allowedHosts: ["api.example.com", "*.googleapis.com"], // Wildcards supported + }; +} +``` + +When a marketplace plugin is installed, the admin sees a capability consent dialog listing what the plugin can access. Users must approve before installation. + +## Publishing to the Marketplace + +Standard plugins can be published to the EmDash Marketplace for one-click installation: + +```bash +emdash plugin bundle --dir packages/plugins/my-plugin # creates .tar.gz +emdash plugin login # authenticate via GitHub +emdash plugin publish --tarball dist/my-plugin-1.0.0.tar.gz +``` + +See [Publishing Reference](./references/publishing.md) for bundle format, validation, and security audit details. + +## Package Exports + +Configure `package.json` exports so EmDash can load each entry point: + +```json +{ + "name": "@my-org/my-plugin", + "type": "module", + "exports": { + ".": "./src/index.ts", + "./sandbox": "./src/sandbox-entry.ts", + "./admin": "./src/admin.tsx" + }, + "peerDependencies": { + "emdash": "^0.1.0" + } +} +``` + +| Export | Context | Purpose | +| ------------- | ----------------- | ---------------------------------------------------------------------- | +| `"."` | Vite (build time) | Descriptor factory -- imported in `astro.config.mjs` | +| `"./sandbox"` | Server (runtime) | `definePlugin({ hooks, routes })` -- loaded by `entrypoint` at runtime | +| `"./admin"` | Browser | React components for admin pages/widgets (native plugins only) | +| `"./astro"` | Server (SSR) | Astro components for site-side block rendering (native plugins only) | + +The `"."` export has the descriptor. The `"./sandbox"` export has the implementation. The descriptor's `entrypoint` field points to `"./sandbox"`. Only include `./admin` and `./astro` exports for native-format plugins. + +## Plugin Features + +Each feature is optional. Add only what your plugin needs: + +| Feature | Where | Standard | Native | Purpose | +| ------------------- | ---------------------------- | -------- | ------ | ------------------------------------------------------- | +| **Hooks** | `definePlugin({ hooks })` | Yes | Yes | React to content/media/lifecycle events | +| **Storage** | descriptor `storage` | Yes | Yes | Document collections with indexed queries | +| **KV** | `ctx.kv` in hooks/routes | Yes | Yes | Key-value store for internal state | +| **API Routes** | `definePlugin({ routes })` | Yes | Yes | REST endpoints at `/_emdash/api/plugins//` | +| **Admin Pages** | Block Kit `admin` route | Yes | Yes | Admin pages via Block Kit (JSON blocks) | +| **Widgets** | Block Kit `admin` route | Yes | Yes | Dashboard cards via Block Kit | +| **React Admin** | `admin.entry` + React export | No | Yes | React-based admin pages and widgets (native only) | +| **PT Blocks** | `admin.portableTextBlocks` | No | Yes | Custom block types in the Portable Text editor | +| **Site Components** | `componentsEntry` | No | Yes | Astro components for rendering blocks on the site | + +See the reference files for detailed syntax: + +- **[Hooks Reference](./references/hooks.md)** — All hook types, signatures, configuration +- **[Storage & Settings](./references/storage.md)** — Collections, KV, settings schema +- **[Admin UI](./references/admin-ui.md)** — Pages, widgets, entry point structure +- **[API Routes](./references/api-routes.md)** — Route handlers, validation, context +- **[Block Kit](./references/block-kit.md)** — Declarative UI for sandboxed plugins (similar to Slack Block Kit but not identical) +- **[Portable Text Blocks](./references/portable-text-blocks.md)** — Custom block types + frontend rendering +- **[Publishing](./references/publishing.md)** — Bundle format, validation, marketplace publishing + +## Complete Example: Standard Plugin with Hooks, Routes, and Storage + +```typescript +// src/index.ts — descriptor factory, runs in Vite at build time +import type { PluginDescriptor } from "emdash"; + +export function submissionsPlugin(): PluginDescriptor { + return { + id: "submissions", + version: "1.0.0", + format: "standard", + entrypoint: "@my-org/plugin-submissions/sandbox", + options: {}, + capabilities: ["read:content"], + storage: { + submissions: { + indexes: ["formId", "status", "createdAt"], + }, + }, + adminPages: [{ path: "/submissions", label: "Submissions", icon: "list" }], + adminWidgets: [{ id: "recent-submissions", title: "Recent Submissions", size: "half" }], + }; +} +``` + +```typescript +// src/sandbox-entry.ts — plugin definition, runs at request time +import { definePlugin } from "emdash"; +import type { PluginContext } from "emdash"; + +export default definePlugin({ + hooks: { + "plugin:install": { + handler: async (_event: any, ctx: PluginContext) => { + ctx.log.info("Submissions plugin installed"); + await ctx.kv.set("settings:maxSubmissions", 1000); + }, + }, + }, + + routes: { + submit: { + public: true, // No auth required + handler: async (routeCtx: any, ctx: PluginContext) => { + const { formId, ...data } = routeCtx.input as Record; + + const count = await ctx.storage.submissions.count({ formId }); + const max = (await ctx.kv.get("settings:maxSubmissions")) ?? 1000; + + if (count >= max) { + return { success: false, error: "Submission limit reached" }; + } + + const id = `${Date.now()}-${Math.random().toString(36).slice(2)}`; + await ctx.storage.submissions.put(id, { + formId, + data, + status: "pending", + createdAt: new Date().toISOString(), + }); + + return { success: true, id }; + }, + }, + + list: { + handler: async (routeCtx: any, ctx: PluginContext) => { + const url = new URL(routeCtx.request.url); + const limit = Math.max( + 1, + Math.min(parseInt(url.searchParams.get("limit") || "50", 10) || 50, 100), + ); + const cursor = url.searchParams.get("cursor") || undefined; + + const result = await ctx.storage.submissions.query({ + orderBy: { createdAt: "desc" }, + limit, + cursor, + }); + + return { + items: result.items.map((item: any) => ({ id: item.id, ...item.data })), + cursor: result.cursor, + hasMore: result.hasMore, + }; + }, + }, + + // Block Kit admin handler for pages and widgets + admin: { + handler: async (routeCtx: any, ctx: PluginContext) => { + const interaction = routeCtx.input as { type: string; page?: string }; + + if (interaction.type === "page_load" && interaction.page === "/submissions") { + const result = await ctx.storage.submissions.query({ + orderBy: { createdAt: "desc" }, + limit: 50, + }); + return { + blocks: [ + { type: "header", text: "Submissions" }, + { + type: "table", + blockId: "submissions-table", + columns: [ + { key: "formId", label: "Form", format: "text" }, + { key: "status", label: "Status", format: "badge" }, + { key: "createdAt", label: "Date", format: "relative_time" }, + ], + rows: result.items.map((item: any) => item.data), + }, + ], + }; + } + + return { blocks: [] }; + }, + }, + }, +}); +``` + +## Plugin Context + +All hooks and routes receive `ctx` (PluginContext): + +```typescript +interface PluginContext { + plugin: { id: string; version: string }; + storage: Record; // Declared collections + kv: KVAccess; // Key-value store + log: LogAccess; // Structured logger + content?: ContentAccess; // If "read:content" capability + media?: MediaAccess; // If "read:media" capability + http?: HttpAccess; // If "network:fetch" capability + users?: UserAccess; // If "read:users" capability + cron?: CronAccess; // Always available — scoped to plugin + email?: EmailAccess; // If "email:send" capability AND a provider is configured +} +``` + +Capabilities are declared in the **descriptor** (not in `definePlugin()` for standard format): + +```typescript +// In the descriptor +export function myPlugin(): PluginDescriptor { + return { + id: "my-plugin", + version: "1.0.0", + format: "standard", + entrypoint: "@my-org/my-plugin/sandbox", + options: {}, + capabilities: ["read:content", "network:fetch"], + allowedHosts: ["api.example.com"], + storage: { events: { indexes: ["timestamp"] } }, + }; +} +``` + +## Output Checklist + +When creating a standard-format plugin, provide: + +1. **`src/index.ts`** -- Descriptor factory (runs in Vite at build time) +2. **`src/sandbox-entry.ts`** -- `definePlugin({ hooks, routes })` as default export (runs at request time) +3. **`package.json`** -- With exports `"."` (descriptor) and `"./sandbox"` (implementation) +4. **`tsconfig.json`** -- Standard TypeScript config + +For native-format plugins (React admin, PT blocks, Astro components), also provide: + +5. **`src/admin.tsx`** -- Admin entry point with React components +6. **`src/astro/index.ts`** -- Block components export (if PT blocks) diff --git a/.agents/skills/creating-plugins/references/admin-ui.md b/.agents/skills/creating-plugins/references/admin-ui.md new file mode 100644 index 0000000..e2289e1 --- /dev/null +++ b/.agents/skills/creating-plugins/references/admin-ui.md @@ -0,0 +1,191 @@ +# Admin UI + +Plugins extend the admin panel with React pages and dashboard widgets. + +## Entry Point + +Export pages and widgets from `src/admin.tsx`: + +```typescript +// src/admin.tsx +import { SettingsPage } from "./components/SettingsPage"; +import { ReportsPage } from "./components/ReportsPage"; +import { StatusWidget } from "./components/StatusWidget"; + +// Pages keyed by path (must match admin.pages paths) +export const pages = { + "/settings": SettingsPage, + "/reports": ReportsPage, +}; + +// Widgets keyed by ID (must match admin.widgets IDs) +export const widgets = { + status: StatusWidget, +}; +``` + +Reference in plugin definition: + +```typescript +definePlugin({ + id: "my-plugin", + version: "1.0.0", + + admin: { + entry: "@my-org/my-plugin/admin", + pages: [ + { path: "/settings", label: "Settings", icon: "settings" }, + { path: "/reports", label: "Reports", icon: "chart" }, + ], + widgets: [{ id: "status", title: "Status", size: "half" }], + }, +}); +``` + +Pages mount at `/_emdash/admin/plugins//`. + +## Pages + +React components. Use `usePluginAPI()` to call plugin routes. + +```typescript +// src/components/SettingsPage.tsx +import { useState, useEffect } from "react"; +import { usePluginAPI } from "@emdash-cms/admin"; + +export function SettingsPage() { + const api = usePluginAPI(); + const [settings, setSettings] = useState>({}); + const [saving, setSaving] = useState(false); + + useEffect(() => { + api.get("settings").then(setSettings); + }, []); + + const handleSave = async () => { + setSaving(true); + await api.post("settings/save", settings); + setSaving(false); + }; + + return ( +
    +

    Settings

    + + +
    + ); +} +``` + +## Widgets + +Dashboard cards with at-a-glance info. + +```typescript +// src/components/StatusWidget.tsx +import { useState, useEffect } from "react"; +import { usePluginAPI } from "@emdash-cms/admin"; + +export function StatusWidget() { + const api = usePluginAPI(); + const [data, setData] = useState({ count: 0 }); + + useEffect(() => { + api.get("status").then(setData); + }, []); + + return ( +
    +
    {data.count}
    +
    + ); +} +``` + +### Widget Sizes + +| Size | Width | +| ------- | -------------------- | +| `full` | Full dashboard width | +| `half` | Half width | +| `third` | One-third width | + +## usePluginAPI() + +Auto-prefixes plugin ID to route URLs: + +```typescript +const api = usePluginAPI(); + +const data = await api.get("status"); // GET /.../plugins//status +await api.post("settings/save", { enabled: true }); // POST with body +const result = await api.get("history?limit=50"); // Query params +``` + +## Admin Components + +Pre-built components from `@emdash-cms/admin`: + +```typescript +import { Card, Button, Input, Select, Toggle, Table, Loading, Alert } from "@emdash-cms/admin"; +``` + +## Auto-Generated Settings + +If your plugin only needs settings, skip custom pages — use `settingsSchema` and EmDash generates the form: + +```typescript +admin: { + settingsSchema: { + apiKey: { type: "secret", label: "API Key" }, + enabled: { type: "boolean", label: "Enabled", default: true }, + } +} +``` + +## Build Configuration + +Admin components need a separate build entry: + +```typescript +// tsdown.config.ts +export default { + entry: { + index: "src/index.ts", + admin: "src/admin.tsx", + }, + format: "esm", + dts: true, + external: ["react", "react-dom", "emdash", "@emdash-cms/admin"], +}; +``` + +Keep React and `@emdash-cms/admin` as externals to avoid bundling duplicates. + +## Plugin Descriptor + +The descriptor (returned by factory function) also declares admin metadata: + +```typescript +export function myPlugin(options = {}): PluginDescriptor { + return { + id: "my-plugin", + entrypoint: "@my-org/my-plugin", + version: "1.0.0", + options, + adminEntry: "@my-org/my-plugin/admin", + adminPages: [{ path: "/settings", label: "Settings", icon: "settings" }], + adminWidgets: [{ id: "status", title: "Status", size: "half" }], + }; +} +``` diff --git a/.agents/skills/creating-plugins/references/api-routes.md b/.agents/skills/creating-plugins/references/api-routes.md new file mode 100644 index 0000000..941d688 --- /dev/null +++ b/.agents/skills/creating-plugins/references/api-routes.md @@ -0,0 +1,265 @@ +# API Routes + +Plugin routes work in both standard and native plugins, and in both trusted and sandboxed modes. Sandboxed plugin routes are invoked via the sandbox runner's `invokeRoute()` RPC. + +Plugin routes expose REST endpoints at `/_emdash/api/plugins//`. + +## Defining Routes + +```typescript +import { definePlugin } from "emdash"; +import { z } from "astro/zod"; + +definePlugin({ + id: "forms", + version: "1.0.0", + + routes: { + // Simple route + status: { + handler: async (ctx) => { + return { ok: true }; + }, + }, + + // Route with input validation + submissions: { + input: z.object({ + formId: z.string().optional(), + limit: z.number().default(50), + cursor: z.string().optional(), + }), + handler: async (ctx) => { + const { formId, limit, cursor } = ctx.input; + const result = await ctx.storage.submissions!.query({ + where: formId ? { formId } : undefined, + orderBy: { createdAt: "desc" }, + limit, + cursor, + }); + return { + items: result.items, + cursor: result.cursor, + hasMore: result.hasMore, + }; + }, + }, + + // Nested path + "settings/save": { + input: z.object({ + enabled: z.boolean().optional(), + apiKey: z.string().optional(), + }), + handler: async (ctx) => { + for (const [key, value] of Object.entries(ctx.input)) { + if (value !== undefined) { + await ctx.kv.set(`settings:${key}`, value); + } + } + return { success: true }; + }, + }, + }, +}); +``` + +## Route URLs + +| Plugin ID | Route Name | URL | +| --------- | --------------- | ------------------------------------------ | +| `forms` | `status` | `/_emdash/api/plugins/forms/status` | +| `forms` | `submissions` | `/_emdash/api/plugins/forms/submissions` | +| `seo` | `settings/save` | `/_emdash/api/plugins/seo/settings/save` | + +## Handler Context + +```typescript +interface RouteContext extends PluginContext { + input: TInput; // Validated input + request: Request; // Original request + plugin: { id: string; version: string }; + storage: Record; + kv: KVAccess; + content?: ContentAccess; // If capability declared + media?: MediaAccess; + http?: HttpAccess; + log: LogAccess; +} +``` + +## Input Validation + +Use Zod schemas. Invalid input returns 400. + +```typescript +routes: { + create: { + input: z.object({ + title: z.string().min(1).max(200), + email: z.string().email(), + priority: z.enum(["low", "medium", "high"]).default("medium"), + tags: z.array(z.string()).optional(), + }), + handler: async (ctx) => { + // ctx.input is typed and validated + const { title, email, priority } = ctx.input; + // ... + }, + }, +} +``` + +Input sources: + +- **POST/PUT/PATCH** — Request body (JSON) +- **GET/DELETE** — URL query parameters + +## Return Values + +Return any JSON-serializable value. Response is always `Content-Type: application/json`. + +```typescript +return { success: true, data: items }; // Object +return items; // Array +return 42; // Primitive +``` + +## Errors + +Throw to return error response: + +```typescript +throw new Error("Item not found"); // 500 with { error: "Item not found" } + +// Custom status code +throw new Response(JSON.stringify({ error: "Not found" }), { + status: 404, + headers: { "Content-Type": "application/json" }, +}); +``` + +## HTTP Methods + +Routes respond to all methods. Check `ctx.request.method`: + +```typescript +handler: async (ctx) => { + switch (ctx.request.method) { + case "GET": + return await ctx.storage.items!.get(ctx.input.id); + case "DELETE": + await ctx.storage.items!.delete(ctx.input.id); + return { deleted: true }; + default: + throw new Response("Method not allowed", { status: 405 }); + } +}; +``` + +## Common Patterns + +### Settings CRUD + +```typescript +routes: { + settings: { + handler: async (ctx) => { + const settings = await ctx.kv.list("settings:"); + const result: Record = {}; + for (const entry of settings) { + result[entry.key.replace("settings:", "")] = entry.value; + } + return result; + }, + }, + "settings/save": { + handler: async (ctx) => { + const input = await ctx.request.json(); + for (const [key, value] of Object.entries(input)) { + if (value !== undefined) await ctx.kv.set(`settings:${key}`, value); + } + return { success: true }; + }, + }, +} +``` + +### Paginated List + +```typescript +routes: { + list: { + input: z.object({ + limit: z.number().min(1).max(100).default(50), + cursor: z.string().optional(), + status: z.string().optional(), + }), + handler: async (ctx) => { + const { limit, cursor, status } = ctx.input; + const result = await ctx.storage.items!.query({ + where: status ? { status } : undefined, + orderBy: { createdAt: "desc" }, + limit, + cursor, + }); + return { + items: result.items.map((item) => ({ id: item.id, ...item.data })), + cursor: result.cursor, + hasMore: result.hasMore, + }; + }, + }, +} +``` + +### External API Proxy + +Requires `network:fetch` capability and `allowedHosts`: + +```typescript +definePlugin({ + capabilities: ["network:fetch"], + allowedHosts: ["api.weather.example.com"], + + routes: { + forecast: { + input: z.object({ city: z.string() }), + handler: async (ctx) => { + const apiKey = await ctx.kv.get("settings:apiKey"); + if (!apiKey) throw new Error("API key not configured"); + + const response = await ctx.http!.fetch( + `https://api.weather.example.com/forecast?city=${ctx.input.city}`, + { headers: { "X-API-Key": apiKey } }, + ); + + if (!response.ok) throw new Error(`API error: ${response.status}`); + return response.json(); + }, + }, + }, +}); +``` + +## Calling from Admin UI + +```typescript +import { usePluginAPI } from "@emdash-cms/admin"; + +const api = usePluginAPI(); +const data = await api.get("status"); +await api.post("settings/save", { enabled: true }); +``` + +## Calling Externally + +```bash +curl https://your-site.com/_emdash/api/plugins/forms/submissions?limit=10 + +curl -X POST https://your-site.com/_emdash/api/plugins/forms/create \ + -H "Content-Type: application/json" \ + -d '{"title": "Hello"}' +``` + +Plugin routes don't have built-in auth. Admin-only routes are protected by the admin session middleware. diff --git a/.agents/skills/creating-plugins/references/block-kit.md b/.agents/skills/creating-plugins/references/block-kit.md new file mode 100644 index 0000000..397505b --- /dev/null +++ b/.agents/skills/creating-plugins/references/block-kit.md @@ -0,0 +1,415 @@ +# Block Kit + +Declarative JSON UI for sandboxed plugin admin pages. The host renders blocks — no plugin JavaScript runs in the browser. Inspired by Slack's Block Kit but not identical — similar concepts and naming, different block/element types and capabilities. + +Trusted plugins (declared in `astro.config.ts`) can ship custom React components instead. Block Kit is for runtime-installed sandboxed plugins. + +Block Kit elements are also used for [Portable Text block editing fields](./portable-text-blocks.md). When a plugin declares `fields` on a block type, the editor renders a Block Kit form. + +## How It Works + +1. User navigates to plugin admin page +2. Admin sends `page_load` interaction to plugin's admin route +3. Plugin returns `BlockResponse` with array of blocks +4. Admin renders blocks using `BlockRenderer` +5. User interacts (button click, form submit) → interaction sent back +6. Plugin returns new blocks + +```typescript +routes: { + admin: { + handler: async (ctx) => { + const interaction = await ctx.request.json(); + + if (interaction.type === "page_load") { + return { + blocks: [ + { type: "header", text: "My Plugin Settings" }, + { + type: "form", + block_id: "settings", + fields: [ + { type: "text_input", action_id: "api_url", label: "API URL" }, + { type: "toggle", action_id: "enabled", label: "Enabled", initial_value: true }, + ], + submit: { label: "Save", action_id: "save" }, + }, + ], + }; + } + + if (interaction.type === "form_submit" && interaction.action_id === "save") { + await ctx.kv.set("settings", interaction.values); + return { + blocks: [/* updated blocks */], + toast: { message: "Settings saved", type: "success" }, + }; + } + }, + }, +} +``` + +## Block Types + +| Type | Description | +| --------- | --------------------------------------------------- | +| `header` | Large bold heading | +| `section` | Text with optional accessory element | +| `divider` | Horizontal rule | +| `fields` | Two-column label/value grid | +| `table` | Data table with formatting, sorting, pagination | +| `actions` | Horizontal row of buttons and controls | +| `stats` | Dashboard metric cards with trend indicators | +| `form` | Input fields with conditional visibility and submit | +| `image` | Block-level image with caption | +| `context` | Small muted help text | +| `columns` | 2-3 column layout with nested blocks | +| `chart` | Charts (timeseries line/bar, pie, custom ECharts) | +| `code` | Syntax-highlighted code block | +| `meter` | Progress/quota meter bar | +| `banner` | Info, warning, or error inline messages | + +## Element Types + +| Type | Description | +| -------------- | ----------------------------------------------- | +| `button` | Action button with optional confirmation dialog | +| `text_input` | Single-line or multiline text input | +| `number_input` | Numeric input with min/max | +| `select` | Dropdown select | +| `toggle` | On/off switch | +| `secret_input` | Masked input for API keys and tokens | +| `checkbox` | Multi-select checkboxes | +| `radio` | Single-select radio buttons | +| `date_input` | Date picker | +| `combobox` | Searchable dropdown select | + +## Block Syntax + +### Header + +```json +{ "type": "header", "text": "Settings" } +``` + +### Section + +```json +{ + "type": "section", + "text": "Configure your plugin settings below.", + "accessory": { "type": "button", "text": "Refresh", "action_id": "refresh" } +} +``` + +### Divider + +```json +{ "type": "divider" } +``` + +### Fields + +```json +{ + "type": "fields", + "fields": [ + { "label": "Status", "value": "Active" }, + { "label": "Last Sync", "value": "2 hours ago" } + ] +} +``` + +### Stats + +```json +{ + "type": "stats", + "stats": [ + { "label": "Total", "value": "1,234", "trend": "+12%", "trend_direction": "up" }, + { "label": "Active", "value": "567" } + ] +} +``` + +### Table + +```json +{ + "type": "table", + "columns": [ + { "key": "name", "label": "Name" }, + { "key": "status", "label": "Status" }, + { "key": "date", "label": "Date" } + ], + "rows": [{ "name": "Item 1", "status": "Active", "date": "2025-01-01" }] +} +``` + +### Actions + +```json +{ + "type": "actions", + "elements": [ + { "type": "button", "text": "Save", "action_id": "save", "style": "primary" }, + { "type": "button", "text": "Cancel", "action_id": "cancel" } + ] +} +``` + +### Form + +```json +{ + "type": "form", + "block_id": "settings", + "fields": [ + { "type": "text_input", "action_id": "name", "label": "Name" }, + { "type": "number_input", "action_id": "count", "label": "Count", "min": 0, "max": 100 }, + { + "type": "select", + "action_id": "theme", + "label": "Theme", + "options": [ + { "label": "Light", "value": "light" }, + { "label": "Dark", "value": "dark" } + ] + }, + { "type": "toggle", "action_id": "enabled", "label": "Enabled", "initial_value": true }, + { "type": "secret_input", "action_id": "api_key", "label": "API Key" } + ], + "submit": { "label": "Save", "action_id": "save_settings" } +} +``` + +### Columns + +```json +{ + "type": "columns", + "columns": [ + { "blocks": [{ "type": "header", "text": "Left" }] }, + { "blocks": [{ "type": "header", "text": "Right" }] } + ] +} +``` + +### Chart (Timeseries) + +```json +{ + "type": "chart", + "config": { + "chart_type": "timeseries", + "series": [ + { + "name": "Requests", + "data": [ + [1709596800000, 42], + [1709600400000, 67], + [1709604000000, 53] + ], + "color": "#086FFF" + }, + { + "name": "Errors", + "data": [ + [1709596800000, 2], + [1709600400000, 5], + [1709604000000, 1] + ] + } + ], + "x_axis_name": "Time", + "y_axis_name": "Count", + "style": "line", + "gradient": true, + "height": 300 + } +} +``` + +- `series[].data` — array of `[timestamp_ms, value]` tuples +- `series[].color` — hex color (optional, auto-assigned from Kumo palette) +- `style` — `"line"` (default) or `"bar"` +- `gradient` — fill gradient beneath lines (default false) +- `height` — chart height in pixels (default 350) + +### Chart (Custom) + +For pie charts, gauges, or any ECharts visualization: + +```json +{ + "type": "chart", + "config": { + "chart_type": "custom", + "options": { + "series": [ + { + "type": "pie", + "data": [ + { "value": 335, "name": "Published" }, + { "value": 234, "name": "Draft" }, + { "value": 120, "name": "Scheduled" } + ] + } + ] + }, + "height": 300 + } +} +``` + +- `options` — raw ECharts option object passed through to `chart.setOption()` + +### Code + +```json +{ + "type": "code", + "code": "const greeting = \"Hello!\";\nconsole.log(greeting);", + "language": "ts" +} +``` + +- `language` — `"ts"`, `"tsx"`, `"jsonc"`, `"bash"`, or `"css"` (defaults to `"ts"`) + +### Meter + +```json +{ + "type": "meter", + "label": "Storage used", + "value": 65, + "custom_value": "6.5 GB / 10 GB" +} +``` + +- `value` — numeric value (default range 0-100) +- `max` / `min` — custom range (defaults to 0-100) +- `custom_value` — display string instead of percentage (e.g. "750 / 1,000") + +### Banner + +```json +{ + "type": "banner", + "title": "API key invalid", + "description": "Please check your API key in settings.", + "variant": "error" +} +``` + +- `variant` — `"default"` (info, default), `"alert"` (warning), or `"error"` +- At least one of `title` or `description` is required + +## Conditional Fields + +Show/hide fields based on other field values. Evaluated client-side, no round-trip. + +```json +{ + "type": "toggle", + "action_id": "auth_enabled", + "label": "Enable Authentication" +} +``` + +```json +{ + "type": "secret_input", + "action_id": "api_key", + "label": "API Key", + "condition": { "field": "auth_enabled", "eq": true } +} +``` + +## Builder Helpers + +`@emdash-cms/blocks` provides TypeScript helpers: + +```typescript +import { blocks, elements } from "@emdash-cms/blocks"; + +const { header, form, section, stats, timeseriesChart, customChart, banner: bannerBlock } = blocks; +const { textInput, toggle, select, button } = elements; + +return { + blocks: [ + header("Settings"), + form({ + blockId: "settings", + fields: [ + textInput("site_title", "Site Title", { initialValue: "My Site" }), + toggle("generate_sitemap", "Generate Sitemap", { initialValue: true }), + select("robots", "Default Robots", [ + { label: "Index, Follow", value: "index,follow" }, + { label: "No Index", value: "noindex,follow" }, + ]), + ], + submit: { label: "Save", actionId: "save" }, + }), + // Timeseries chart + timeseriesChart({ + series: [ + { + name: "Page Views", + data: [ + [Date.now() - 3600000, 100], + [Date.now(), 150], + ], + }, + ], + yAxisName: "Views", + gradient: true, + }), + // Pie chart via custom ECharts options + customChart({ + options: { + series: [ + { + type: "pie", + data: [ + { value: 335, name: "Published" }, + { value: 234, name: "Draft" }, + ], + }, + ], + }, + }), + ], +}; +``` + +## Button Confirmations + +```json +{ + "type": "button", + "text": "Delete All", + "action_id": "delete_all", + "style": "danger", + "confirm": { + "title": "Are you sure?", + "text": "This cannot be undone.", + "confirm": "Delete", + "deny": "Cancel" + } +} +``` + +## Toast Responses + +Return a `toast` alongside blocks to show a notification: + +```typescript +return { + blocks: [ + /* ... */ + ], + toast: { message: "Settings saved", type: "success" }, // "success" | "error" | "info" +}; +``` diff --git a/.agents/skills/creating-plugins/references/hooks.md b/.agents/skills/creating-plugins/references/hooks.md new file mode 100644 index 0000000..c143660 --- /dev/null +++ b/.agents/skills/creating-plugins/references/hooks.md @@ -0,0 +1,412 @@ +# Hooks Reference + +Hooks let plugins run code in response to events. Declared in `definePlugin({ hooks })`. + +## Signature + +```typescript +async (event: EventType, ctx: PluginContext) => ReturnType; +``` + +## Configuration + +Simple handler or full config: + +```typescript +// Simple +hooks: { + "content:afterSave": async (event, ctx) => { + ctx.log.info("Saved"); + } +} + +// Full config +hooks: { + "content:afterSave": { + priority: 100, // Lower runs first (default: 100) + timeout: 5000, // Max execution time ms (default: 5000) + dependencies: [], // Plugin IDs that must run first + errorPolicy: "abort", // "abort" | "continue" + handler: async (event, ctx) => { + ctx.log.info("Saved"); + } + } +} +``` + +## Lifecycle Hooks + +### `plugin:install` + +Runs once on first install. Use to seed defaults. + +```typescript +"plugin:install": async (_event, ctx) => { + await ctx.kv.set("settings:enabled", true); + await ctx.storage.items!.put("default", { name: "Default" }); +} +``` + +Event: `{}` +Returns: `void` + +### `plugin:activate` + +Runs when plugin is enabled (after install or re-enable). + +```typescript +"plugin:activate": async (_event, ctx) => { + ctx.log.info("Activated"); +} +``` + +Event: `{}` +Returns: `void` + +### `plugin:deactivate` + +Runs when plugin is disabled (not removed). + +```typescript +"plugin:deactivate": async (_event, ctx) => { + ctx.log.info("Deactivated"); +} +``` + +Event: `{}` +Returns: `void` + +### `plugin:uninstall` + +Runs when plugin is removed. Only delete data if `event.deleteData` is true. + +```typescript +"plugin:uninstall": async (event, ctx) => { + if (event.deleteData) { + const result = await ctx.storage.items!.query({ limit: 1000 }); + await ctx.storage.items!.deleteMany(result.items.map(i => i.id)); + } +} +``` + +Event: `{ deleteData: boolean }` +Returns: `void` + +## Content Hooks + +### `content:beforeSave` + +Runs before save. Return modified content, void to keep unchanged, or throw to cancel. + +```typescript +"content:beforeSave": async (event, ctx) => { + const { content, collection, isNew } = event; + + if (collection === "posts" && !content.title) { + throw new Error("Posts require a title"); + } + + // Transform + if (content.slug) { + content.slug = content.slug.toLowerCase().replace(/\s+/g, "-"); + } + + return content; +} +``` + +Event: `{ content: Record, collection: string, isNew: boolean }` +Returns: `Record | void` + +### `content:afterSave` + +Runs after successful save. Side effects only — logging, notifications, syncing. + +```typescript +"content:afterSave": async (event, ctx) => { + const { content, collection, isNew } = event; + ctx.log.info(`${isNew ? "Created" : "Updated"} ${collection}/${content.id}`); +} +``` + +Event: `{ content: Record, collection: string, isNew: boolean }` +Returns: `void` + +### `content:beforeDelete` + +Runs before delete. Return `false` to cancel, `true` or void to allow. + +```typescript +"content:beforeDelete": async (event, ctx) => { + if (event.collection === "pages" && event.id === "home") { + ctx.log.warn("Cannot delete home page"); + return false; + } + return true; +} +``` + +Event: `{ id: string, collection: string }` +Returns: `boolean | void` + +### `content:afterDelete` + +Runs after successful delete. + +```typescript +"content:afterDelete": async (event, ctx) => { + ctx.log.info(`Deleted ${event.collection}/${event.id}`); + await ctx.storage.cache!.delete(`${event.collection}:${event.id}`); +} +``` + +Event: `{ id: string, collection: string }` +Returns: `void` + +## Media Hooks + +### `media:beforeUpload` + +Runs before upload. Return modified file info, void to keep, or throw to cancel. + +```typescript +"media:beforeUpload": async (event, ctx) => { + const { file } = event; + + if (!file.type.startsWith("image/")) { + throw new Error("Only images allowed"); + } + + if (file.size > 10 * 1024 * 1024) { + throw new Error("Max 10MB"); + } + + return { ...file, name: `${Date.now()}-${file.name}` }; +} +``` + +Event: `{ file: { name: string, type: string, size: number } }` +Returns: `{ name: string, type: string, size: number } | void` + +### `media:afterUpload` + +Runs after successful upload. + +```typescript +"media:afterUpload": async (event, ctx) => { + ctx.log.info(`Uploaded ${event.media.filename}`, { id: event.media.id }); +} +``` + +Event: `{ media: { id: string, filename: string, mimeType: string, size: number | null, url: string, createdAt: string } }` +Returns: `void` + +## Email Hooks + +Email hooks require specific capabilities. Without the required capability, hooks are silently skipped. + +### `email:beforeSend` + +**Requires:** `email:intercept` capability. + +Runs before email delivery. Return modified message, or `false` to cancel delivery. Handlers are chained — each receives the output of the previous one. + +```typescript +definePlugin({ + id: "email-footer", + capabilities: ["email:intercept"], + hooks: { + "email:beforeSend": async (event, ctx) => { + return { ...event.message, text: event.message.text + "\n\n-- Sent via EmDash" }; + }, + }, +}); +``` + +Event: `{ message: EmailMessage, source: string }` +Returns: `EmailMessage | false` + +### `email:deliver` + +**Requires:** `email:provide` capability. **Exclusive hook** — exactly one provider is active. + +Implements email transport (e.g. Resend, SMTP, SES). Selected by the admin in Settings > Email. + +```typescript +definePlugin({ + id: "emdash-resend", + capabilities: ["email:provide", "network:fetch"], + allowedHosts: ["api.resend.com"], + hooks: { + "email:deliver": { + exclusive: true, + handler: async ({ message }, ctx) => { + const apiKey = await ctx.kv.get("settings:apiKey"); + await ctx.http!.fetch("https://api.resend.com/emails", { + method: "POST", + headers: { Authorization: `Bearer ${apiKey}` }, + body: JSON.stringify({ to: message.to, subject: message.subject, text: message.text }), + }); + }, + }, + }, +}); +``` + +Event: `{ message: EmailMessage, source: string }` +Returns: `void` + +### `email:afterSend` + +**Requires:** `email:intercept` capability. + +Runs after successful delivery. Fire-and-forget — errors are logged but don't propagate. + +```typescript +definePlugin({ + id: "email-logger", + capabilities: ["email:intercept"], + hooks: { + "email:afterSend": async (event, ctx) => { + ctx.log.info(`Email sent to ${event.message.to}`, { source: event.source }); + }, + }, +}); +``` + +Event: `{ message: EmailMessage, source: string }` +Returns: `void` + +## Cron Hook + +### `cron` + +Runs on a schedule. Configure schedules via `ctx.cron.schedule()` in `plugin:activate`. + +```typescript +definePlugin({ + id: "cleanup", + hooks: { + "plugin:activate": async (_event, ctx) => { + await ctx.cron!.schedule("daily-cleanup", { schedule: "0 2 * * *" }); + }, + cron: async (event, ctx) => { + if (event.name === "daily-cleanup") { + // ... cleanup logic + } + }, + }, +}); +``` + +Event: `{ name: string, data?: Record }` +Returns: `void` + +## Public Page Hooks + +Public page hooks let plugins contribute to the rendered output of public site pages. Templates opt in to these contributions with ``, ``, and `` components. + +### `page:metadata` + +Contributes typed metadata to `` — meta tags, OG properties, canonical/alternate links, and JSON-LD. Works in both trusted and sandboxed modes. + +Returns structured contributions that core validates, dedupes (first-wins), and renders. Plugins never emit raw HTML through this hook. + +```typescript +"page:metadata": async (event, ctx) => { + if (event.page.kind !== "content") return null; + + return [ + { kind: "meta", name: "author", content: "My Blog" }, + { + kind: "jsonld", + id: `schema:${event.page.content?.collection}:${event.page.content?.id}`, + graph: { + "@context": "https://schema.org", + "@type": "BlogPosting", + headline: event.page.title, + description: event.page.description, + }, + }, + ]; +} +``` + +Event: `{ page: PublicPageContext }` +Returns: `PageMetadataContribution | PageMetadataContribution[] | null` + +Contribution types: + +- `{ kind: "meta", name: string, content: string, key?: string }` — `` +- `{ kind: "property", property: string, content: string, key?: string }` — `` (OpenGraph) +- `{ kind: "link", rel: "canonical" | "alternate", href: string, hreflang?: string, key?: string }` — `` tag (HTTP/HTTPS URLs only) +- `{ kind: "jsonld", id?: string, graph: object | object[] }` — ` + + + + + +
    + +
    + + + + + + + + + + + + + diff --git a/src/live.config.ts b/src/live.config.ts new file mode 100644 index 0000000..c8c819d --- /dev/null +++ b/src/live.config.ts @@ -0,0 +1,13 @@ +/** + * EmDash Live Content Collections + * + * Defines the _emdash collection that handles all content types from the database. + * Query specific types using getEmDashCollection() and getEmDashEntry(). + */ + +import { defineLiveCollection } from "astro:content"; +import { emdashLoader } from "emdash/runtime"; + +export const collections = { + _emdash: defineLiveCollection({ loader: emdashLoader() }), +}; diff --git a/src/pages/404.astro b/src/pages/404.astro new file mode 100644 index 0000000..0078a14 --- /dev/null +++ b/src/pages/404.astro @@ -0,0 +1,33 @@ +--- +import Base from "../layouts/Base.astro"; +--- + + +
    +

    404

    +

    The page you're looking for doesn't exist.

    + Go back home +
    + + + diff --git a/src/pages/category/[slug].astro b/src/pages/category/[slug].astro new file mode 100644 index 0000000..4df3db7 --- /dev/null +++ b/src/pages/category/[slug].astro @@ -0,0 +1,117 @@ +--- +import { getTerm, getEmDashCollection, getEntryTerms } from "emdash"; +import Base from "../../layouts/Base.astro"; +import PostCard from "../../components/PostCard.astro"; +import { getReadingTime } from "../../utils/reading-time"; + +const { slug } = Astro.params; +const term = slug ? await getTerm("category", slug) : null; + +if (!term) { + return Astro.redirect("/404"); +} + +const { entries: posts } = await getEmDashCollection("posts", { + where: { category: term.slug }, + orderBy: { published_at: "desc" }, +}); + +// Fetch tags for display on each post card +const filteredPosts = await Promise.all( + posts.map(async (post) => { + const tags = await getEntryTerms("posts", post.data.id, "tag"); + return { post, tags }; + }) +); +--- + + +
    +
    + Category +

    {term.label}

    +

    + {filteredPosts.length} + {filteredPosts.length === 1 ? "post" : "posts"} +

    +
    + + { + filteredPosts.length === 0 ? ( +

    No posts in this category yet.

    + ) : ( +
    + {filteredPosts.map(({ post, tags }) => ( + ({ slug: t.slug, label: t.label }))} + /> + ))} +
    + ) + } +
    + + + diff --git a/src/pages/index.astro b/src/pages/index.astro new file mode 100644 index 0000000..4c72f48 --- /dev/null +++ b/src/pages/index.astro @@ -0,0 +1,448 @@ +--- +import { getEmDashCollection, getEntryTerms } from "emdash"; +import { Image } from "emdash/ui"; +import Base from "../layouts/Base.astro"; +import PostCard from "../components/PostCard.astro"; +import { getReadingTime } from "../utils/reading-time"; + +const { entries: posts, cacheHint } = await getEmDashCollection("posts"); + +Astro.cache.set(cacheHint); + +const sortedPosts = posts.toSorted((a, b) => { + const dateA = a.data.publishedAt?.getTime() ?? 0; + const dateB = b.data.publishedAt?.getTime() ?? 0; + return dateB - dateA; +}); + +// Find the first post with a featured image for the hero +const featuredPost = sortedPosts.find((p) => p.data.featured_image); +const featuredIndex = featuredPost ? sortedPosts.indexOf(featuredPost) : -1; + +// Get remaining posts (exclude featured if found, limit to 6 for grid) +const gridPosts = sortedPosts.filter((_, i) => i !== featuredIndex).slice(0, 6); + +// Total posts shown = featured (if any) + grid posts +const totalShown = (featuredPost ? 1 : 0) + gridPosts.length; +const hasMorePosts = sortedPosts.length > totalShown; + +// Fetch tags for featured post (bylines are already hydrated by getEmDashCollection) +let featuredTags: Array<{ slug: string; label: string }> = []; +const featuredBylines = featuredPost?.data.bylines ?? []; +if (featuredPost) { + const tags = await getEntryTerms("posts", featuredPost.data.id, "tag"); + featuredTags = tags.map((t) => ({ slug: t.slug, label: t.label })); +} + +// Fetch tags for grid posts (bylines are already hydrated by getEmDashCollection) +const gridPostsWithTags = await Promise.all( + gridPosts.map(async (post) => { + const tags = await getEntryTerms("posts", post.data.id, "tag"); + const bylines = post.data.bylines ?? []; + return { + post, + tags: tags.map((t) => ({ slug: t.slug, label: t.label })), + bylines, + }; + }) +); + +// Format date helper +function formatDate(date: Date | null | undefined) { + if (!date) return null; + return date.toLocaleDateString("en-US", { + year: "numeric", + month: "long", + day: "numeric", + }); +} +--- + + + { + posts.length === 0 ? ( +
    +

    No posts yet

    +

    Create your first post in the admin panel.

    + + Create a post + +
    + ) : ( +
    + {/* Featured Post - Side by side */} + {featuredPost && ( + + )} + + {/* Latest Posts */} + {gridPostsWithTags.length > 0 && ( +
    +
    +

    Latest

    + {hasMorePosts && ( + + View all + + )} +
    +
    + {gridPostsWithTags.map(({ post, tags, bylines }) => ( + + ))} +
    +
    + )} +
    + ) + } + + + diff --git a/src/pages/pages/[slug].astro b/src/pages/pages/[slug].astro new file mode 100644 index 0000000..20cb86d --- /dev/null +++ b/src/pages/pages/[slug].astro @@ -0,0 +1,108 @@ +--- +import { getEmDashEntry } from "emdash"; +import { PortableText } from "emdash/ui"; +import Base from "../../layouts/Base.astro"; + +const { slug } = Astro.params; + +if (!slug) { + return Astro.redirect("/404"); +} + +const { entry: page, cacheHint } = await getEmDashEntry("pages", slug); + +if (!page) { + return Astro.redirect("/404"); +} + +Astro.cache.set(cacheHint); +--- + + +
    + + +
    + +
    +
    + + + diff --git a/src/pages/posts/[slug].astro b/src/pages/posts/[slug].astro new file mode 100644 index 0000000..7e9b322 --- /dev/null +++ b/src/pages/posts/[slug].astro @@ -0,0 +1,958 @@ +--- +import { + getEmDashEntry, + getEmDashCollection, + getEntryTerms, + getSeoMeta, +} from "emdash"; +import { + Image, + PortableText, + Comments, + CommentForm, + WidgetArea, +} from "emdash/ui"; +import Base from "../../layouts/Base.astro"; +import PostCard from "../../components/PostCard.astro"; +import { getReadingTime } from "../../utils/reading-time"; + +const { slug } = Astro.params; + +if (!slug) { + return Astro.redirect("/404"); +} + +const { entry: post, cacheHint } = await getEmDashEntry("posts", slug); + +if (!post) { + return Astro.redirect("/404"); +} + +Astro.cache.set(cacheHint); + +// Get featured image URL for OG fallback +// The image may have src (external) or meta.storageKey (local) +function getImageUrl(img: unknown): string | undefined { + if (!img || typeof img !== "object") return undefined; + const image = img as Record; + // Check for direct src + if (typeof image.src === "string" && image.src) { + return image.src.startsWith("http") + ? image.src + : `${Astro.url.origin}${image.src}`; + } + // Build from storageKey for local images + const meta = image.meta as Record | undefined; + const storageKey = + (typeof meta?.storageKey === "string" ? meta.storageKey : undefined) || + (typeof image.id === "string" ? image.id : undefined); + if (storageKey) { + return `${Astro.url.origin}/_emdash/api/media/file/${storageKey}`; + } + return undefined; +} +const featuredImageUrl = getImageUrl(post.data.featured_image); + +// Generate SEO meta from content +const seo = getSeoMeta(post, { + siteTitle: "My Blog", + siteUrl: Astro.url.origin, + path: `/posts/${slug}`, + defaultOgImage: featuredImageUrl, +}); + +// Get tags for this post +// Note: post.id is the slug, post.data.id is the database ULID +const tags = await getEntryTerms("posts", post.data.id, "tag"); + +// Bylines are already hydrated by getEmDashEntry +const bylines = post.data.bylines ?? []; + +// Get reading time +const readingTime = getReadingTime(post.data.content); + +// Get other posts for "More posts" section, with their tags +// Fetch a few extra in case the current post is among them +const { entries: recentPosts } = await getEmDashCollection("posts", { + orderBy: { published_at: "desc" }, + limit: 4, +}); +const otherPosts = recentPosts.filter((p) => p.id !== post.id).slice(0, 3); + +// Fetch tags for related posts (bylines are already hydrated by getEmDashCollection) +const otherPostsWithTags = await Promise.all( + otherPosts.map(async (p) => { + const postTags = await getEntryTerms("posts", p.data.id, "tag"); + const postBylines = p.data.bylines ?? []; + return { post: p, tags: postTags, bylines: postBylines }; + }) +); + +const publishDate = + post.data.publishedAt?.toLocaleDateString("en-US", { + year: "numeric", + month: "long", + day: "numeric", + }) ?? null; +--- + + +
    + {/* Hero: Full-width featured image */} + { + post.data.featured_image && ( +
    + +
    + ) + } + + {/* Three-column layout */} +
    + {/* Left gutter: Meta information */} + + + {/* Main content */} +
    +
    + +

    {post.data.title}

    + { + post.data.excerpt && ( +

    {post.data.excerpt}

    + ) + } +
    + +
    + +
    + +
    + + +
    +
    + + {/* Right gutter: TOC + Sidebar widgets */} + +
    +
    + + { + otherPostsWithTags.length > 0 && ( + + ) + } + + + + + diff --git a/src/pages/posts/index.astro b/src/pages/posts/index.astro new file mode 100644 index 0000000..2635592 --- /dev/null +++ b/src/pages/posts/index.astro @@ -0,0 +1,268 @@ +--- +import { getEmDashCollection, getEntryTerms } from "emdash"; +import Base from "../../layouts/Base.astro"; +import { getReadingTime } from "../../utils/reading-time"; + +const { entries: posts, cacheHint } = await getEmDashCollection("posts"); + +Astro.cache.set(cacheHint); + +const sortedPosts = posts.toSorted((a, b) => { + const dateA = a.data.publishedAt?.getTime() ?? 0; + const dateB = b.data.publishedAt?.getTime() ?? 0; + return dateB - dateA; +}); + +// Fetch tags for each post (bylines are already hydrated by getEmDashCollection) +const postsWithTags = await Promise.all( + sortedPosts.map(async (post) => { + const tags = await getEntryTerms("posts", post.data.id, "tag"); + const bylines = post.data.bylines ?? []; + return { post, tags, bylines }; + }) +); + +const formatDate = (date: Date) => + date.toLocaleDateString("en-US", { + year: "numeric", + month: "long", + day: "numeric", + }); +--- + + + + + + diff --git a/src/pages/rss.xml.ts b/src/pages/rss.xml.ts new file mode 100644 index 0000000..a944a74 --- /dev/null +++ b/src/pages/rss.xml.ts @@ -0,0 +1,70 @@ +import type { APIRoute } from "astro"; +import { getEmDashCollection } from "emdash"; + +const siteTitle = "My Blog"; +const siteDescription = "A blog about software, design, and the occasional stray thought."; + +export const GET: APIRoute = async ({ site, url }) => { + const siteUrl = site?.toString() || url.origin; + + const { entries: posts } = await getEmDashCollection("posts", { + orderBy: { published_at: "desc" }, + limit: 20, + }); + + const items = posts + .map((post) => { + if (!post.data.publishedAt) return null; + const pubDate = post.data.publishedAt.toUTCString(); + + const postUrl = `${siteUrl}/posts/${post.id}`; + const title = escapeXml(post.data.title || "Untitled"); + const description = escapeXml(post.data.excerpt || ""); + + return ` + ${title} + ${postUrl} + ${postUrl} + ${pubDate} + ${description} + `; + }) + .filter(Boolean) + .join("\n"); + + const rss = ` + + + ${escapeXml(siteTitle)} + ${escapeXml(siteDescription)} + ${siteUrl} + + en-us + ${new Date().toUTCString()} +${items} + +`; + + return new Response(rss, { + headers: { + "Content-Type": "application/rss+xml; charset=utf-8", + "Cache-Control": "public, max-age=3600", + }, + }); +}; + +const XML_ESCAPE_PATTERNS = [ + [/&/g, "&"], + [//g, ">"], + [/"/g, """], + [/'/g, "'"], +] as const; + +function escapeXml(str: string): string { + let result = str; + for (const [pattern, replacement] of XML_ESCAPE_PATTERNS) { + result = result.replace(pattern, replacement); + } + return result; +} diff --git a/src/pages/search.astro b/src/pages/search.astro new file mode 100644 index 0000000..fd29606 --- /dev/null +++ b/src/pages/search.astro @@ -0,0 +1,141 @@ +--- +export const prerender = false; + +import { getEmDashCollection } from "emdash"; +import Base from "../layouts/Base.astro"; +import PostCard from "../components/PostCard.astro"; +import { getReadingTime, extractText } from "../utils/reading-time"; + +const query = Astro.url.searchParams.get("q")?.trim() || ""; + +const { entries: allPosts } = await getEmDashCollection("posts"); + +// Simple search: match query against title, excerpt, and content +function matchesQuery(post: (typeof allPosts)[0], q: string): boolean { + if (!q) return false; + const lower = q.toLowerCase(); + const title = (post.data.title || "").toLowerCase(); + const excerpt = (post.data.excerpt || "").toLowerCase(); + // Extract plain text from portable text blocks (avoids matching on _type, _key, etc.) + const content = extractText(post.data.content).toLowerCase(); + return ( + title.includes(lower) || excerpt.includes(lower) || content.includes(lower) + ); +} + +const results = query ? allPosts.filter((p) => matchesQuery(p, query)) : []; +--- + + +
    +

    Search

    + +
    + + +
    + + { + query && ( +

    + {results.length === 0 + ? `No results for "${query}"` + : `${results.length} result${results.length === 1 ? "" : "s"} for "${query}"`} +

    + ) + } + + { + results.length > 0 && ( +
    + {results.map((post) => ( + + ))} +
    + ) + } + + {!query &&

    Enter a search term to find posts.

    } +
    + + + diff --git a/src/pages/tag/[slug].astro b/src/pages/tag/[slug].astro new file mode 100644 index 0000000..2f42531 --- /dev/null +++ b/src/pages/tag/[slug].astro @@ -0,0 +1,120 @@ +--- +import { getTerm, getEmDashCollection, getEntryTerms } from "emdash"; +import Base from "../../layouts/Base.astro"; +import PostCard from "../../components/PostCard.astro"; +import { getReadingTime } from "../../utils/reading-time"; + +const { slug } = Astro.params; +const term = slug ? await getTerm("tag", slug) : null; + +if (!term) { + return Astro.redirect("/404"); +} + +const { entries: posts } = await getEmDashCollection("posts", { + where: { tag: term.slug }, + orderBy: { published_at: "desc" }, +}); + +// Fetch tags for display on each post card +const filteredPosts = await Promise.all( + posts.map(async (post) => { + const tags = await getEntryTerms("posts", post.data.id, "tag"); + return { post, tags }; + }) +); +--- + + +
    +
    + Tag +

    {term.label}

    +

    + {filteredPosts.length} + {filteredPosts.length === 1 ? "post" : "posts"} +

    +
    + + { + filteredPosts.length === 0 ? ( +

    No posts with this tag yet.

    + ) : ( +
    + {filteredPosts.map(({ post, tags }) => ( + ({ slug: t.slug, label: t.label }))} + /> + ))} +
    + ) + } +
    + + + diff --git a/src/styles/theme.css b/src/styles/theme.css new file mode 100644 index 0000000..ba4cba2 --- /dev/null +++ b/src/styles/theme.css @@ -0,0 +1,110 @@ +/* + theme.css — override any :root variable here to retheme the blog. + + This is the only file you need to edit to customize the site's visual + appearance. All defaults are listed below as comments. Uncomment and + change any value to override it. + + Note: this template defines explicit dark mode colors in Base.astro. + Overriding light-mode --color-* variables here won't affect dark mode. + To customize dark mode, also override --color-* variables inside a + @media (prefers-color-scheme: dark) block and/or in the :root.dark rule. +*/ + +:root { + /* --- Colors --- + --color-bg: #ffffff; + --color-bg-subtle: #fafafa; + --color-text: #1a1a1a; + --color-text-secondary: #525252; + --color-muted: #8b8b8b; + --color-border: #e5e5e5; + --color-border-subtle: #f0f0f0; + --color-surface: #f7f7f7; + --color-accent: #0066cc; + --color-accent-hover: #0052a3; + --color-on-accent: white; + --color-accent-ring: color-mix(in srgb, var(--color-accent) 25%, transparent); + */ + + /* --- Fonts --- + --font-sans: 'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; + --font-mono: 'JetBrains Mono', ui-monospace, SFMono-Regular, Menlo, monospace; + */ + + /* --- Type scale --- + --font-size-xs: 0.8125rem; + --font-size-sm: 0.875rem; + --font-size-base: 1rem; + --font-size-lg: 1.125rem; + --font-size-xl: 1.25rem; + --font-size-2xl: 1.5rem; + --font-size-3xl: 2rem; + --font-size-4xl: 2.5rem; + --font-size-5xl: 3.5rem; + */ + + /* --- Line heights --- + --leading-tight: 1.15; + --leading-snug: 1.3; + --leading-normal: 1.5; + --leading-relaxed: 1.7; + */ + + /* --- Letter spacing --- + --tracking-tight: -0.03em; used on h1 and large titles + --tracking-snug: -0.02em; used on h2–h6, site/card titles + --tracking-wide: 0.06em; used on meta labels, TOC/widget titles + --tracking-wider: 0.08em; used on footer headings, section labels + */ + + /* --- Spacing --- + --spacing-1: 0.25rem; + --spacing-2: 0.5rem; + --spacing-3: 0.75rem; + --spacing-4: 1rem; + --spacing-5: 1.25rem; + --spacing-6: 1.5rem; + --spacing-8: 2rem; + --spacing-10: 2.5rem; + --spacing-12: 3rem; + --spacing-16: 4rem; + --spacing-20: 5rem; + --spacing-24: 6rem; + */ + + /* --- Layout --- + --content-width: 680px; article/page body column width + --wide-width: 1200px; max container width (home, archives) + --gutter-width: 200px; right sidebar column (TOC) on article pages + --meta-col-width: 180px; left meta column on article pages + --nav-height: 64px; sticky header height + --search-input-width: 180px; nav search box width + */ + + /* --- Borders & radius --- + --radius: 4px; + --radius-lg: 8px; + */ + + /* --- Transitions --- + --transition-fast: 120ms ease; + --transition-base: 180ms ease; + */ + + /* --- Avatars --- + --avatar-size-xs: 18px; card byline avatars + --avatar-size-sm: 20px; post list byline avatars + --avatar-size-md: 24px; featured post byline avatars + --avatar-size-lg: 32px; single post byline avatars + */ + + /* --- Shadows --- + --shadow-dropdown: 0 8px 30px rgba(0, 0, 0, 0.12); + --shadow-btn-active: 0 1px 2px rgba(0, 0, 0, 0.05); + */ + + /* --- Misc --- + --tag-padding-y: 2px; vertical padding on tag pills + */ +} diff --git a/src/utils/reading-time.ts b/src/utils/reading-time.ts new file mode 100644 index 0000000..8df86a9 --- /dev/null +++ b/src/utils/reading-time.ts @@ -0,0 +1,44 @@ +import type { PortableTextBlock } from "emdash"; + +const WORDS_PER_MINUTE = 200; +const WHITESPACE_REGEX = /\s+/; + +/** + * Extract plain text from Portable Text blocks + */ +export function extractText(blocks: PortableTextBlock[] | undefined): string { + if (!blocks || !Array.isArray(blocks)) return ""; + + return blocks + .filter( + ( + block, + ): block is PortableTextBlock & { + children: Array<{ _type: string; text?: string }>; + } => block._type === "block" && Array.isArray(block.children), + ) + .map((block) => + block.children + .filter((child) => child._type === "span" && typeof child.text === "string") + .map((span) => span.text) + .join(""), + ) + .join(" "); +} + +/** + * Calculate reading time in minutes from Portable Text content + */ +export function getReadingTime(content: PortableTextBlock[] | undefined): number { + const text = extractText(content); + const wordCount = text.split(WHITESPACE_REGEX).filter(Boolean).length; + const minutes = Math.ceil(wordCount / WORDS_PER_MINUTE); + return Math.max(1, minutes); +} + +/** + * Format reading time for display + */ +export function formatReadingTime(minutes: number): string { + return `${minutes} min read`; +} diff --git a/tsconfig.json b/tsconfig.json new file mode 100644 index 0000000..0217fb1 --- /dev/null +++ b/tsconfig.json @@ -0,0 +1,13 @@ +{ + "extends": "astro/tsconfigs/base", + "compilerOptions": { + "types": [ + "node" + ] + }, + "include": [ + "src", + ".astro/types.d.ts", + "emdash-env.d.ts" + ] +} \ No newline at end of file