first commit
This commit is contained in:
Matt Kane
122
skills/adversarial-reviewer/SKILL.md
Normal file
122
skills/adversarial-reviewer/SKILL.md
Normal file
@@ -0,0 +1,122 @@
|
||||
---
|
||||
name: adversarial-reviewer
|
||||
description: Adversarial code review that assumes bugs exist and hunts for them. Use when asked to review code, find bugs, audit for correctness, stress-test a PR, or when someone says "tear this apart" or "what's wrong with this". Give no benefit of the doubt — every line is guilty until proven innocent.
|
||||
---
|
||||
|
||||
# Adversarial Code Reviewer
|
||||
|
||||
You are a hostile reviewer. Your job is to find bugs, not to be helpful. Assume the code is broken and prove yourself right.
|
||||
|
||||
## Mindset
|
||||
|
||||
- **Guilty until proven innocent.** Every line of code is a suspect.
|
||||
- **No compliments.** Don't say what's good. Say what's wrong.
|
||||
- **No "potential issue" hedging.** If something looks wrong, say it's wrong. Be direct.
|
||||
- **Prove it.** Construct concrete inputs, sequences, or race conditions that trigger the bug. Don't hand-wave.
|
||||
- **Silence means approval.** If you don't mention something, that IS your approval. Don't waste tokens on "this looks fine".
|
||||
|
||||
## Review Checklist
|
||||
|
||||
Work through these categories in order. Skip a category only when it genuinely doesn't apply.
|
||||
|
||||
### 1. Logic Errors
|
||||
|
||||
- Off-by-one in loops, slices, ranges, pagination
|
||||
- Inverted or missing conditions (especially negation — `!` is easy to miss)
|
||||
- Fallthrough in switch/match without break
|
||||
- Short-circuit evaluation hiding side effects
|
||||
- Wrong operator (`=` vs `==`, `&&` vs `||`, `&` vs `&&`)
|
||||
- Integer overflow, floating point comparison, implicit coercion
|
||||
|
||||
### 2. Edge Cases & Boundaries
|
||||
|
||||
- Empty inputs: empty string, empty array, null, undefined, 0, NaN
|
||||
- Single-element collections
|
||||
- Maximum values, minimum values, negative numbers
|
||||
- Unicode, multi-byte characters, RTL text
|
||||
- Concurrent calls with identical arguments
|
||||
- What happens when it's called twice? What about zero times?
|
||||
|
||||
### 3. Error Handling
|
||||
|
||||
- Catch blocks that swallow errors silently
|
||||
- Missing error handling on async operations
|
||||
- Error handling that catches too broadly (bare `catch` / `catch(e)`)
|
||||
- Cleanup/finally blocks missing or incomplete
|
||||
- Error messages that leak internals to users
|
||||
- Thrown errors that aren't Error instances
|
||||
|
||||
### 4. State & Concurrency
|
||||
|
||||
- Shared mutable state without synchronization
|
||||
- TOCTOU (time-of-check-to-time-of-use) races
|
||||
- Stale closures capturing variables that mutate
|
||||
- Event handler registration without cleanup
|
||||
- Assumptions about execution order of async operations
|
||||
|
||||
### 5. Security
|
||||
|
||||
- Unsanitized user input reaching SQL, HTML, shell, or file paths
|
||||
- Missing or incorrect authorization checks
|
||||
- Information leakage in error responses
|
||||
- CSRF, open redirect, path traversal
|
||||
- Secrets in code, logs, or error messages
|
||||
- Timing attacks on comparison operations
|
||||
|
||||
### 6. Data Integrity
|
||||
|
||||
- Missing validation at system boundaries
|
||||
- Type coercion hiding bad data
|
||||
- Partial writes without transactions
|
||||
- Missing uniqueness constraints
|
||||
- Cascading deletes that orphan or destroy data
|
||||
- Schema mismatches between code and database
|
||||
|
||||
### 7. Resource Management
|
||||
|
||||
- Missing cleanup: file handles, connections, timers, listeners
|
||||
- Unbounded growth: caches without eviction, arrays without limits
|
||||
- Memory leaks from retained references
|
||||
- Missing timeouts on network operations
|
||||
- Retry loops without backoff or limits
|
||||
|
||||
## Output Format
|
||||
|
||||
For each bug found:
|
||||
|
||||
```
|
||||
**BUG: [short title]**
|
||||
File: path/to/file.ts:42
|
||||
Category: [from checklist above]
|
||||
Severity: CRITICAL | HIGH | MEDIUM | LOW
|
||||
|
||||
[What's wrong — one or two sentences, no filler]
|
||||
|
||||
Trigger: [concrete scenario that hits this bug]
|
||||
|
||||
Fix: [minimal code change or approach — don't rewrite the function]
|
||||
```
|
||||
|
||||
Order findings by severity (CRITICAL first).
|
||||
|
||||
## Severity Guide
|
||||
|
||||
- **CRITICAL**: Data loss, security vulnerability, crash in production
|
||||
- **HIGH**: Wrong behavior users will hit in normal usage
|
||||
- **MEDIUM**: Wrong behavior in edge cases, resource leaks under load
|
||||
- **LOW**: Cosmetic logic issues, unnecessary work, misleading names that could cause future bugs
|
||||
|
||||
## What This Review Is NOT
|
||||
|
||||
- Not a style review. Don't comment on formatting, naming conventions, or "I'd do it differently".
|
||||
- Not a feature review. Don't suggest additions, improvements, or refactors.
|
||||
- Not a test review. Don't say "this needs more tests" — say what's broken.
|
||||
- Not a compliment sandwich. There is no sandwich. There is only bugs.
|
||||
|
||||
## Process
|
||||
|
||||
1. Read ALL the code under review before writing anything. Form a mental model of the data flow.
|
||||
2. Trace the unhappy paths. What happens when things go wrong?
|
||||
3. Look for implicit assumptions. What does this code believe about its inputs that isn't enforced?
|
||||
4. Check the boundaries between components. Where does trust transfer happen?
|
||||
5. Write up findings. If you found nothing, say "No bugs found" and stop. Don't manufacture issues to seem thorough.
|
||||
139
skills/agent-browser/SKILL.md
Normal file
139
skills/agent-browser/SKILL.md
Normal file
@@ -0,0 +1,139 @@
|
||||
---
|
||||
name: agent-browser
|
||||
description: Browser automation for testing and verification. Use when you need to interact with web UIs, verify visual changes, fill forms, or capture screenshots.
|
||||
---
|
||||
|
||||
# Agent Browser Skill
|
||||
|
||||
Fast browser automation CLI for AI agents. Use this to verify web UI changes, test interactions, and capture screenshots.
|
||||
|
||||
## When to Use
|
||||
|
||||
- Verify visual changes after modifying frontend code
|
||||
- Test form interactions and user flows
|
||||
- Capture screenshots for documentation or debugging
|
||||
- Inspect rendered HTML/accessibility tree
|
||||
- Debug why something isn't working in the browser
|
||||
|
||||
## Core Workflow
|
||||
|
||||
### 1. Open a URL
|
||||
|
||||
```bash
|
||||
agent-browser open http://localhost:4321/
|
||||
```
|
||||
|
||||
### 2. Take a Snapshot
|
||||
|
||||
The snapshot command returns an accessibility tree with refs (`@e1`, `@e2`, etc.) that you can use for interactions:
|
||||
|
||||
```bash
|
||||
agent-browser snapshot -i # -i = interactive elements only (recommended)
|
||||
agent-browser snapshot -c # -c = compact (removes empty structural elements)
|
||||
agent-browser snapshot -i -c # Both flags work together
|
||||
```
|
||||
|
||||
### 3. Interact Using Refs
|
||||
|
||||
Use the `@ref` values from the snapshot to interact with elements:
|
||||
|
||||
```bash
|
||||
agent-browser click @e5 # Click element
|
||||
agent-browser fill @e3 "hello" # Clear and type
|
||||
agent-browser type @e3 "world" # Type without clearing
|
||||
agent-browser select @e7 "option" # Select dropdown
|
||||
agent-browser check @e9 # Check checkbox
|
||||
```
|
||||
|
||||
### 4. Screenshot
|
||||
|
||||
```bash
|
||||
agent-browser screenshot # Viewport only
|
||||
agent-browser screenshot --full # Full page
|
||||
agent-browser screenshot output.png # Save to file
|
||||
```
|
||||
|
||||
ALWAYS check the image size before attempting to load. If it is larger than 2MB, process it using a tool such as sips or ImageMagick to reduce the size. Large files cannot be loaded by your tools.
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### Form Verification
|
||||
|
||||
```bash
|
||||
agent-browser open http://localhost:4321/_emdash/api/setup/dev-bypass?redirect=/_emdash/admin/content/posts/new
|
||||
agent-browser snapshot -i # Check what fields are visible
|
||||
agent-browser fill @e3 "Test Title"
|
||||
agent-browser fill @e5 "Test content here"
|
||||
agent-browser click @e7 # Save button
|
||||
```
|
||||
|
||||
### Get Element Info
|
||||
|
||||
```bash
|
||||
agent-browser get text @e1 # Get text content
|
||||
agent-browser get html @e1 # Get inner HTML
|
||||
agent-browser get value @e2 # Get input value
|
||||
agent-browser get url # Current URL
|
||||
agent-browser get title # Page title
|
||||
agent-browser get count "button" # Count matching elements
|
||||
```
|
||||
|
||||
### Check Element State
|
||||
|
||||
```bash
|
||||
agent-browser is visible @e1
|
||||
agent-browser is enabled @e2
|
||||
agent-browser is checked @e3
|
||||
```
|
||||
|
||||
### Find by Role/Label
|
||||
|
||||
```bash
|
||||
agent-browser find role button click --name "Submit"
|
||||
agent-browser find label "Email" fill "test@example.com"
|
||||
agent-browser find placeholder "Search..." type "query"
|
||||
```
|
||||
|
||||
## Sessions
|
||||
|
||||
Sessions keep browser state (cookies, storage) between commands:
|
||||
|
||||
```bash
|
||||
# Use named session (persists until closed)
|
||||
agent-browser --session mytest open http://localhost:4321
|
||||
agent-browser --session mytest snapshot -i
|
||||
|
||||
# Or set via environment
|
||||
export AGENT_BROWSER_SESSION=mytest
|
||||
agent-browser open http://localhost:3000
|
||||
```
|
||||
|
||||
## Useful Options
|
||||
|
||||
| Option | Description |
|
||||
| ------------------ | ----------------------------------- |
|
||||
| `--session <name>` | Isolated browser session |
|
||||
| `--headed` | Show browser window (not headless) |
|
||||
| `--json` | JSON output for programmatic use |
|
||||
| `--full` | Full page screenshot |
|
||||
| `-i` | Snapshot: interactive elements only |
|
||||
| `-c` | Snapshot: compact output |
|
||||
| `-d <n>` | Snapshot: limit tree depth |
|
||||
|
||||
## Debugging
|
||||
|
||||
```bash
|
||||
agent-browser --headed open http://localhost:3000 # See what's happening
|
||||
agent-browser console # View console logs
|
||||
agent-browser errors # View page errors
|
||||
agent-browser highlight @e5 # Highlight element
|
||||
agent-browser eval "document.title" # Run JS
|
||||
```
|
||||
|
||||
## Tips
|
||||
|
||||
1. **Always snapshot first** - Get refs before interacting
|
||||
2. **Use `-i` flag** - Interactive-only snapshots are much cleaner
|
||||
3. **Wait when needed** - Use `wait <ms>` or `wait <selector>` after actions that trigger loading
|
||||
4. **Sessions for auth** - Use named sessions to persist login state
|
||||
5. **Headed for debugging** - Use `--headed` when things aren't working as expected
|
||||
150
skills/building-emdash-site/SKILL.md
Normal file
150
skills/building-emdash-site/SKILL.md
Normal file
@@ -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 `<img src={post.data.featured_image} />` renders `[object Object]`. Use `<Image image={post.data.featured_image} />` 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 |
|
||||
193
skills/building-emdash-site/references/configuration.md
Normal file
193
skills/building-emdash-site/references/configuration.md
Normal file
@@ -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 "@emdashcms/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-02-24",
|
||||
"compatibility_flags": ["nodejs_compat"],
|
||||
"assets": { "directory": "./dist" },
|
||||
"d1_databases": [
|
||||
{
|
||||
"binding": "DB",
|
||||
"database_name": "my-site",
|
||||
"database_id": "", // 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 "@emdashcms/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
|
||||
/// <reference types="emdash/locals" />
|
||||
|
||||
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": "workspace:*",
|
||||
"@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 `@emdashcms/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.
|
||||
388
skills/building-emdash-site/references/querying-and-rendering.md
Normal file
388
skills/building-emdash-site/references/querying-and-rendering.md
Normal file
@@ -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<T> {
|
||||
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";
|
||||
---
|
||||
<PortableText value={post.data.content} />
|
||||
```
|
||||
|
||||
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,
|
||||
};
|
||||
---
|
||||
<PortableText value={page.data.content} components={{ type: customTypes }} />
|
||||
```
|
||||
|
||||
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 */}
|
||||
<Image image={post.data.featured_image} />
|
||||
|
||||
{/* Also works with explicit props */}
|
||||
{post.data.featured_image?.src && (
|
||||
<img src={post.data.featured_image.src} alt={post.data.featured_image.alt || ""} />
|
||||
)}
|
||||
```
|
||||
|
||||
**Common mistake:**
|
||||
|
||||
```astro
|
||||
{/* WRONG -- image is an object, not a string */}
|
||||
<img src={post.data.featured_image} />
|
||||
```
|
||||
|
||||
## Visual Editing Attributes
|
||||
|
||||
Entries include `edit` attributes for inline editing. Spread them onto the element that displays the field:
|
||||
|
||||
```astro
|
||||
<h1 {...post.edit.title}>{post.data.title}</h1>
|
||||
<p {...post.edit.excerpt}>{post.data.excerpt}</p>
|
||||
<div {...post.edit.featured_image}>
|
||||
<Image image={post.data.featured_image} />
|
||||
</div>
|
||||
```
|
||||
|
||||
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;
|
||||
});
|
||||
---
|
||||
<Base title="Posts">
|
||||
{sortedPosts.map(post => (
|
||||
<article>
|
||||
{post.data.featured_image && <Image image={post.data.featured_image} />}
|
||||
<a href={`/posts/${post.id}`}>{post.data.title}</a>
|
||||
{post.data.excerpt && <p>{post.data.excerpt}</p>}
|
||||
</article>
|
||||
))}
|
||||
</Base>
|
||||
```
|
||||
|
||||
### 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");
|
||||
---
|
||||
<Base title={seo.title} description={seo.description}>
|
||||
<article>
|
||||
{post.data.featured_image && (
|
||||
<div {...post.edit.featured_image}>
|
||||
<Image image={post.data.featured_image} />
|
||||
</div>
|
||||
)}
|
||||
<h1 {...post.edit.title}>{post.data.title}</h1>
|
||||
<PortableText value={post.data.content} />
|
||||
{tags.length > 0 && (
|
||||
<div>
|
||||
{tags.map(t => <a href={`/tag/${t.slug}`}>{t.label}</a>)}
|
||||
</div>
|
||||
)}
|
||||
</article>
|
||||
</Base>
|
||||
```
|
||||
|
||||
### 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" },
|
||||
});
|
||||
---
|
||||
<Base title={`${term.label} posts`}>
|
||||
<h1>{term.label}</h1>
|
||||
{posts.map(post => (
|
||||
<a href={`/posts/${post.id}`}>{post.data.title}</a>
|
||||
))}
|
||||
</Base>
|
||||
```
|
||||
|
||||
### 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 ` <item>
|
||||
<title>${escapeXml(post.data.title)}</title>
|
||||
<link>${postUrl}</link>
|
||||
<guid isPermaLink="true">${postUrl}</guid>
|
||||
<pubDate>${post.data.publishedAt!.toUTCString()}</pubDate>
|
||||
<description>${escapeXml(post.data.excerpt || "")}</description>
|
||||
</item>`;
|
||||
})
|
||||
.join("\n");
|
||||
|
||||
return new Response(
|
||||
`<?xml version="1.0" encoding="UTF-8"?>
|
||||
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">
|
||||
<channel>
|
||||
<title>${escapeXml(siteTitle)}</title>
|
||||
<link>${siteUrl}</link>
|
||||
<atom:link href="${siteUrl}/rss.xml" rel="self" type="application/rss+xml"/>
|
||||
<language>en-us</language>
|
||||
<lastBuildDate>${new Date().toUTCString()}</lastBuildDate>
|
||||
${items}
|
||||
</channel>
|
||||
</rss>`,
|
||||
{
|
||||
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, """)
|
||||
.replace(/'/g, "'");
|
||||
}
|
||||
```
|
||||
|
||||
### 404 page (`/404.astro`)
|
||||
|
||||
```astro
|
||||
---
|
||||
import Base from "../layouts/Base.astro";
|
||||
---
|
||||
<Base title="Not Found">
|
||||
<h1>Page not found</h1>
|
||||
<p>The page you're looking for doesn't exist.</p>
|
||||
<a href="/">Go home</a>
|
||||
</Base>
|
||||
```
|
||||
|
||||
### Empty state
|
||||
|
||||
When a collection has no content, show a helpful empty state:
|
||||
|
||||
```astro
|
||||
{posts.length === 0 ? (
|
||||
<section>
|
||||
<h2>No posts yet</h2>
|
||||
<p>Create your first post in the admin panel.</p>
|
||||
<a href="/_emdash/admin/content/posts/new">Create a post</a>
|
||||
</section>
|
||||
) : (
|
||||
/* ... 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 => (
|
||||
<a href={`/posts/${post.id}`}>{post.data.title}</a>
|
||||
))}
|
||||
{nextCursor && <a href={`?cursor=${nextCursor}`}>Next page</a>}
|
||||
```
|
||||
|
||||
`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",
|
||||
});
|
||||
```
|
||||
469
skills/building-emdash-site/references/schema-and-seed.md
Normal file
469
skills/building-emdash-site/references/schema-and-seed.md
Normal file
@@ -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
|
||||
```
|
||||
495
skills/building-emdash-site/references/site-features.md
Normal file
495
skills/building-emdash-site/references/site-features.md
Normal file
@@ -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");
|
||||
---
|
||||
<nav>
|
||||
{primaryMenu?.items.map(item => (
|
||||
<a href={item.url} target={item.target}>{item.label}</a>
|
||||
))}
|
||||
</nav>
|
||||
```
|
||||
|
||||
### Nested menus (dropdowns)
|
||||
|
||||
```astro
|
||||
{primaryMenu?.items.map(item => (
|
||||
<li>
|
||||
<a href={item.url}>{item.label}</a>
|
||||
{item.children.length > 0 && (
|
||||
<ul class="submenu">
|
||||
{item.children.map(child => (
|
||||
<li><a href={child.url}>{child.label}</a></li>
|
||||
))}
|
||||
</ul>
|
||||
)}
|
||||
</li>
|
||||
))}
|
||||
```
|
||||
|
||||
### 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 => (
|
||||
<a href={`/tag/${t.slug}`}>{t.label}</a>
|
||||
))}
|
||||
```
|
||||
|
||||
### 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";
|
||||
---
|
||||
<aside>
|
||||
<WidgetArea name="sidebar" />
|
||||
</aside>
|
||||
```
|
||||
|
||||
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 => (
|
||||
<div class="widget">
|
||||
{widget.title && <h3>{widget.title}</h3>}
|
||||
{widget.type === "content" && widget.content && (
|
||||
<PortableText value={widget.content} />
|
||||
)}
|
||||
</div>
|
||||
))}
|
||||
```
|
||||
|
||||
## Search
|
||||
|
||||
### LiveSearch component (instant search)
|
||||
|
||||
```astro
|
||||
---
|
||||
import LiveSearch from "emdash/ui/search";
|
||||
---
|
||||
<LiveSearch
|
||||
placeholder="Search..."
|
||||
collections={["posts", "pages"]}
|
||||
/>
|
||||
```
|
||||
|
||||
Customizable CSS classes:
|
||||
|
||||
```astro
|
||||
<LiveSearch
|
||||
placeholder="Search..."
|
||||
class="site-search"
|
||||
inputClass="site-search-input"
|
||||
resultsClass="site-search-results"
|
||||
resultClass="site-search-result"
|
||||
collections={["posts", "pages"]}
|
||||
expandOnFocus={{ collapsed: "180px", expanded: "280px" }}
|
||||
/>
|
||||
```
|
||||
|
||||
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 `<mark>` highlights), `score`.
|
||||
|
||||
### Search page
|
||||
|
||||
```astro
|
||||
---
|
||||
import LiveSearch from "emdash/ui/search";
|
||||
import Base from "../layouts/Base.astro";
|
||||
|
||||
const query = Astro.url.searchParams.get("q") || "";
|
||||
---
|
||||
<Base title="Search">
|
||||
<h1>Search</h1>
|
||||
<LiveSearch
|
||||
placeholder="Search posts..."
|
||||
collections={["posts", "pages"]}
|
||||
/>
|
||||
</Base>
|
||||
```
|
||||
|
||||
### Keyboard shortcut
|
||||
|
||||
Add Cmd+K / Ctrl+K to focus search:
|
||||
|
||||
```html
|
||||
<script>
|
||||
document.addEventListener("keydown", (e) => {
|
||||
if ((e.metaKey || e.ctrlKey) && e.key === "k") {
|
||||
e.preventDefault();
|
||||
document.querySelector(".site-search-input")?.focus();
|
||||
}
|
||||
});
|
||||
</script>
|
||||
```
|
||||
|
||||
### 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 `<head>`:
|
||||
|
||||
```astro
|
||||
<title>{seo.title}</title>
|
||||
<meta name="description" content={seo.description} />
|
||||
<link rel="canonical" href={seo.canonical} />
|
||||
<meta property="og:image" content={seo.ogImage} />
|
||||
{seo.robots && <meta name="robots" content={seo.robots} />}
|
||||
```
|
||||
|
||||
## Comments
|
||||
|
||||
Built-in comments system:
|
||||
|
||||
```astro
|
||||
---
|
||||
import { Comments, CommentForm } from "emdash/ui";
|
||||
---
|
||||
<Comments collection="posts" contentId={post.data.id} threaded />
|
||||
<CommentForm collection="posts" contentId={post.data.id} />
|
||||
```
|
||||
|
||||
Comments are enabled per-collection in the seed: `"commentsEnabled": true`.
|
||||
|
||||
## Page Contributions (Plugin Head/Body Injection)
|
||||
|
||||
Plugins can inject content into the `<head>` and `<body>` 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 },
|
||||
});
|
||||
---
|
||||
<html>
|
||||
<head>
|
||||
<!-- your meta tags -->
|
||||
<EmDashHead page={pageCtx} />
|
||||
</head>
|
||||
<body>
|
||||
<EmDashBodyStart page={pageCtx} />
|
||||
<!-- your content -->
|
||||
<EmDashBodyEnd page={pageCtx} />
|
||||
</body>
|
||||
</html>
|
||||
```
|
||||
|
||||
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 && (
|
||||
<span>{post.data.byline.displayName}</span>
|
||||
)}
|
||||
|
||||
{/* All credits (includes roleLabel for co-authors, guest essays, etc.) */}
|
||||
{post.data.bylines?.map(credit => (
|
||||
<span>
|
||||
{credit.byline.displayName}
|
||||
{credit.roleLabel && <em> ({credit.roleLabel})</em>}
|
||||
</span>
|
||||
))}
|
||||
```
|
||||
|
||||
- `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
|
||||
<!-- In <head>, before styles load -->
|
||||
<script is:inline>
|
||||
(function () {
|
||||
var c = document.cookie;
|
||||
var i = c.indexOf("theme=");
|
||||
var theme = i >= 0 ? c.slice(i + 6).split(";")[0] : null;
|
||||
if (theme === "dark" || theme === "light") {
|
||||
document.documentElement.classList.add(theme);
|
||||
} else if (window.matchMedia("(prefers-color-scheme: dark)").matches) {
|
||||
document.documentElement.classList.add("dark");
|
||||
}
|
||||
})();
|
||||
</script>
|
||||
```
|
||||
|
||||
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,
|
||||
});
|
||||
---
|
||||
<!doctype html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="UTF-8" />
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
|
||||
<title>{title}</title>
|
||||
{description && <meta name="description" content={description} />}
|
||||
<EmDashHead page={pageCtx} />
|
||||
</head>
|
||||
<body>
|
||||
<EmDashBodyStart page={pageCtx} />
|
||||
<header>
|
||||
<nav>
|
||||
<a href="/">My Site</a>
|
||||
<LiveSearch placeholder="Search..." collections={["posts", "pages"]} />
|
||||
{menu?.items.map(item => (
|
||||
<a href={item.url}>{item.label}</a>
|
||||
))}
|
||||
</nav>
|
||||
</header>
|
||||
<main>
|
||||
<slot />
|
||||
</main>
|
||||
<footer>
|
||||
<WidgetArea name="footer" />
|
||||
</footer>
|
||||
<EmDashBodyEnd page={pageCtx} />
|
||||
</body>
|
||||
</html>
|
||||
```
|
||||
457
skills/creating-plugins/SKILL.md
Normal file
457
skills/creating-plugins/SKILL.md
Normal file
@@ -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/<id>/<route>` |
|
||||
| **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<string, unknown>;
|
||||
|
||||
const count = await ctx.storage.submissions.count({ formId });
|
||||
const max = (await ctx.kv.get<number>("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<string, StorageCollection>; // 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)
|
||||
191
skills/creating-plugins/references/admin-ui.md
Normal file
191
skills/creating-plugins/references/admin-ui.md
Normal file
@@ -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/<plugin-id>/<path>`.
|
||||
|
||||
## Pages
|
||||
|
||||
React components. Use `usePluginAPI()` to call plugin routes.
|
||||
|
||||
```typescript
|
||||
// src/components/SettingsPage.tsx
|
||||
import { useState, useEffect } from "react";
|
||||
import { usePluginAPI } from "@emdashcms/admin";
|
||||
|
||||
export function SettingsPage() {
|
||||
const api = usePluginAPI();
|
||||
const [settings, setSettings] = useState<Record<string, unknown>>({});
|
||||
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 (
|
||||
<div>
|
||||
<h1>Settings</h1>
|
||||
<label>
|
||||
Site Title
|
||||
<input
|
||||
type="text"
|
||||
value={settings.siteTitle || ""}
|
||||
onChange={(e) => setSettings({ ...settings, siteTitle: e.target.value })}
|
||||
/>
|
||||
</label>
|
||||
<button onClick={handleSave} disabled={saving}>
|
||||
{saving ? "Saving..." : "Save"}
|
||||
</button>
|
||||
</div>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
## Widgets
|
||||
|
||||
Dashboard cards with at-a-glance info.
|
||||
|
||||
```typescript
|
||||
// src/components/StatusWidget.tsx
|
||||
import { useState, useEffect } from "react";
|
||||
import { usePluginAPI } from "@emdashcms/admin";
|
||||
|
||||
export function StatusWidget() {
|
||||
const api = usePluginAPI();
|
||||
const [data, setData] = useState({ count: 0 });
|
||||
|
||||
useEffect(() => {
|
||||
api.get("status").then(setData);
|
||||
}, []);
|
||||
|
||||
return (
|
||||
<div className="widget-content">
|
||||
<div className="score">{data.count}</div>
|
||||
</div>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
### 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/<id>/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 `@emdashcms/admin`:
|
||||
|
||||
```typescript
|
||||
import { Card, Button, Input, Select, Toggle, Table, Loading, Alert } from "@emdashcms/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", "@emdashcms/admin"],
|
||||
};
|
||||
```
|
||||
|
||||
Keep React and `@emdashcms/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" }],
|
||||
};
|
||||
}
|
||||
```
|
||||
265
skills/creating-plugins/references/api-routes.md
Normal file
265
skills/creating-plugins/references/api-routes.md
Normal file
@@ -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/<plugin-id>/<route-name>`.
|
||||
|
||||
## 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<TInput = unknown> extends PluginContext {
|
||||
input: TInput; // Validated input
|
||||
request: Request; // Original request
|
||||
plugin: { id: string; version: string };
|
||||
storage: Record<string, StorageCollection>;
|
||||
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<string, unknown> = {};
|
||||
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<string>("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 "@emdashcms/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.
|
||||
415
skills/creating-plugins/references/block-kit.md
Normal file
415
skills/creating-plugins/references/block-kit.md
Normal file
@@ -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
|
||||
|
||||
`@emdashcms/blocks` provides TypeScript helpers:
|
||||
|
||||
```typescript
|
||||
import { blocks, elements } from "@emdashcms/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"
|
||||
};
|
||||
```
|
||||
412
skills/creating-plugins/references/hooks.md
Normal file
412
skills/creating-plugins/references/hooks.md
Normal file
@@ -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<string, unknown>, collection: string, isNew: boolean }`
|
||||
Returns: `Record<string, unknown> | 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<string, unknown>, 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<string, unknown> }`
|
||||
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 `<EmDashHead>`, `<EmDashBodyStart>`, and `<EmDashBodyEnd>` components.
|
||||
|
||||
### `page:metadata`
|
||||
|
||||
Contributes typed metadata to `<head>` — 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 }` — `<meta name="..." content="...">`
|
||||
- `{ kind: "property", property: string, content: string, key?: string }` — `<meta property="..." content="...">` (OpenGraph)
|
||||
- `{ kind: "link", rel: "canonical" | "alternate", href: string, hreflang?: string, key?: string }` — `<link>` tag (HTTP/HTTPS URLs only)
|
||||
- `{ kind: "jsonld", id?: string, graph: object | object[] }` — `<script type="application/ld+json">`
|
||||
|
||||
Dedupe rules: first contribution wins per key. Canonical is singleton.
|
||||
|
||||
### `page:fragments` (Trusted Only)
|
||||
|
||||
Contributes raw HTML, scripts, or markup to `head`, `body:start`, or `body:end`. **Trusted plugins only.** Sandboxed plugins cannot register this hook — the manifest schema rejects it.
|
||||
|
||||
```typescript
|
||||
"page:fragments": async (event, ctx) => {
|
||||
return [
|
||||
{
|
||||
kind: "external-script",
|
||||
placement: "head",
|
||||
src: "https://www.googletagmanager.com/gtm.js?id=GTM-XXXXX",
|
||||
async: true,
|
||||
},
|
||||
{
|
||||
kind: "html",
|
||||
placement: "body:start",
|
||||
html: '<noscript><iframe src="https://www.googletagmanager.com/ns.html?id=GTM-XXXXX" height="0" width="0" style="display:none;visibility:hidden"></iframe></noscript>',
|
||||
},
|
||||
];
|
||||
}
|
||||
```
|
||||
|
||||
Event: `{ page: PublicPageContext }`
|
||||
Returns: `PageFragmentContribution | PageFragmentContribution[] | null`
|
||||
|
||||
Contribution types:
|
||||
|
||||
- `{ kind: "external-script", placement, src, async?, defer?, attributes?, key? }`
|
||||
- `{ kind: "inline-script", placement, code, attributes?, key? }`
|
||||
- `{ kind: "html", placement, html, key? }`
|
||||
|
||||
Placements: `"head"`, `"body:start"`, `"body:end"`
|
||||
|
||||
## Execution Order
|
||||
|
||||
1. Lower `priority` values run first
|
||||
2. Equal priorities: plugin registration order
|
||||
3. `dependencies` array forces ordering regardless of priority
|
||||
|
||||
## Error Handling
|
||||
|
||||
- `errorPolicy: "abort"` (default) — pipeline stops, operation may fail
|
||||
- `errorPolicy: "continue"` — error logged, remaining hooks still run
|
||||
|
||||
Use `"continue"` for non-critical operations (analytics, notifications, external syncs).
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Hook | Trigger | Capability Required | Return |
|
||||
| ---------------------- | -------------------- | ------------------- | ---------------------------- |
|
||||
| `plugin:install` | First install | — | `void` |
|
||||
| `plugin:activate` | Plugin enabled | — | `void` |
|
||||
| `plugin:deactivate` | Plugin disabled | — | `void` |
|
||||
| `plugin:uninstall` | Plugin removed | — | `void` |
|
||||
| `content:beforeSave` | Before save | — | Modified content or `void` |
|
||||
| `content:afterSave` | After save | — | `void` |
|
||||
| `content:beforeDelete` | Before delete | — | `false` to cancel |
|
||||
| `content:afterDelete` | After delete | — | `void` |
|
||||
| `media:beforeUpload` | Before upload | — | Modified file info or `void` |
|
||||
| `media:afterUpload` | After upload | — | `void` |
|
||||
| `email:beforeSend` | Before email send | `email:intercept` | Modified message or `false` |
|
||||
| `email:deliver` | Email delivery | `email:provide` | `void` (exclusive) |
|
||||
| `email:afterSend` | After email send | `email:intercept` | `void` |
|
||||
| `cron` | Scheduled task fires | — | `void` |
|
||||
| `page:metadata` | Page render | — | Metadata contributions |
|
||||
| `page:fragments` | Page render | — (trusted only) | Fragment contributions |
|
||||
251
skills/creating-plugins/references/portable-text-blocks.md
Normal file
251
skills/creating-plugins/references/portable-text-blocks.md
Normal file
@@ -0,0 +1,251 @@
|
||||
# Portable Text Block Types
|
||||
|
||||
**Trusted plugins only.** PT blocks require Astro components for site-side rendering (`componentsEntry`), loaded at build time from an npm package. Sandboxed/marketplace plugins cannot define PT blocks.
|
||||
|
||||
Plugins can add custom block types to the Portable Text editor. These appear in the slash command menu and can be inserted into any `portableText` field.
|
||||
|
||||
## Declaring Block Types
|
||||
|
||||
In `definePlugin()`, declare blocks under `admin.portableTextBlocks`:
|
||||
|
||||
```typescript
|
||||
admin: {
|
||||
portableTextBlocks: [
|
||||
{
|
||||
type: "youtube",
|
||||
label: "YouTube Video",
|
||||
icon: "video",
|
||||
placeholder: "Paste YouTube URL...",
|
||||
fields: [
|
||||
{ type: "text_input", action_id: "id", label: "YouTube URL" },
|
||||
{ type: "text_input", action_id: "title", label: "Title" },
|
||||
{ type: "text_input", action_id: "poster", label: "Poster Image URL" },
|
||||
],
|
||||
},
|
||||
{
|
||||
type: "codepen",
|
||||
label: "CodePen",
|
||||
icon: "code",
|
||||
placeholder: "Paste CodePen URL...",
|
||||
},
|
||||
],
|
||||
}
|
||||
```
|
||||
|
||||
### Block Config Fields
|
||||
|
||||
| Field | Type | Description |
|
||||
| ------------- | -------- | ----------------------------------------------- |
|
||||
| `type` | `string` | Block type name (used in PT `_type`). Required. |
|
||||
| `label` | `string` | Display name in slash command menu. Required. |
|
||||
| `icon` | `string` | Icon key. Optional. |
|
||||
| `description` | `string` | Description in slash command menu. Optional. |
|
||||
| `placeholder` | `string` | Input placeholder text. Optional. |
|
||||
| `fields` | `array` | Block Kit form fields for editing UI. Optional. |
|
||||
|
||||
### Icons
|
||||
|
||||
Named icons: `video`, `code`, `link`, `link-external`. Unknown or missing falls back to a generic cube icon.
|
||||
|
||||
### Fields
|
||||
|
||||
When `fields` is declared, the editor renders a Block Kit form for editing. When omitted, a simple URL input is shown.
|
||||
|
||||
Fields use Block Kit element syntax:
|
||||
|
||||
```typescript
|
||||
fields: [
|
||||
{
|
||||
type: "text_input",
|
||||
action_id: "id",
|
||||
label: "URL",
|
||||
placeholder: "https://...",
|
||||
},
|
||||
{ type: "text_input", action_id: "title", label: "Title" },
|
||||
{ type: "text_input", action_id: "poster", label: "Poster Image" },
|
||||
{ type: "number_input", action_id: "start", label: "Start Time (seconds)" },
|
||||
{ type: "toggle", action_id: "autoplay", label: "Autoplay" },
|
||||
{
|
||||
type: "select",
|
||||
action_id: "size",
|
||||
label: "Size",
|
||||
options: [
|
||||
{ label: "Small", value: "small" },
|
||||
{ label: "Medium", value: "medium" },
|
||||
{ label: "Large", value: "large" },
|
||||
],
|
||||
},
|
||||
];
|
||||
```
|
||||
|
||||
See [Block Kit reference](./block-kit.md) for all element types.
|
||||
|
||||
The `action_id` of each field becomes a key in the Portable Text block data. The field with `action_id: "id"` is treated as the primary identifier (typically the URL).
|
||||
|
||||
### Data Flow
|
||||
|
||||
1. User types `/` in the editor and selects a block type
|
||||
2. Modal opens with Block Kit form (or simple URL input if no fields)
|
||||
3. User fills in fields and submits
|
||||
4. Block is inserted with `_type` set to the block type and field values as properties
|
||||
5. Editing an existing block re-opens the modal pre-populated
|
||||
|
||||
Portable Text output:
|
||||
|
||||
```json
|
||||
{
|
||||
"_type": "youtube",
|
||||
"_key": "abc123",
|
||||
"id": "https://youtube.com/watch?v=dQw4w9WgXcQ",
|
||||
"title": "Never Gonna Give You Up",
|
||||
"poster": "https://img.youtube.com/vi/dQw4w9WgXcQ/0.jpg"
|
||||
}
|
||||
```
|
||||
|
||||
## Site-Side Rendering
|
||||
|
||||
To render block types on the site, export Astro components from a `componentsEntry`.
|
||||
|
||||
### Component File
|
||||
|
||||
```typescript
|
||||
// src/astro/index.ts
|
||||
import YouTube from "./YouTube.astro";
|
||||
import CodePen from "./CodePen.astro";
|
||||
|
||||
// This export name is required
|
||||
export const blockComponents = {
|
||||
youtube: YouTube,
|
||||
codepen: CodePen,
|
||||
};
|
||||
```
|
||||
|
||||
### Astro Component
|
||||
|
||||
```astro
|
||||
---
|
||||
// src/astro/YouTube.astro
|
||||
const { id, title, poster } = Astro.props.node;
|
||||
|
||||
// Extract video ID from URL
|
||||
const videoId = id?.match(/(?:v=|youtu\.be\/)([^&]+)/)?.[1] ?? id;
|
||||
---
|
||||
|
||||
<div class="youtube-embed">
|
||||
<iframe
|
||||
src={`https://www.youtube-nocookie.com/embed/${videoId}`}
|
||||
title={title || "YouTube Video"}
|
||||
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
|
||||
allowfullscreen
|
||||
></iframe>
|
||||
</div>
|
||||
```
|
||||
|
||||
Component receives `Astro.props.node` with the full block data.
|
||||
|
||||
### Plugin Descriptor
|
||||
|
||||
Set `componentsEntry` in the descriptor:
|
||||
|
||||
```typescript
|
||||
export function myPlugin(options = {}): PluginDescriptor {
|
||||
return {
|
||||
id: "my-plugin",
|
||||
entrypoint: "@my-org/my-plugin",
|
||||
componentsEntry: "@my-org/my-plugin/astro",
|
||||
version: "1.0.0",
|
||||
options,
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
### Package Exports
|
||||
|
||||
Add the `./astro` export:
|
||||
|
||||
```json
|
||||
{
|
||||
"exports": {
|
||||
".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" },
|
||||
"./admin": { "types": "./dist/admin.d.ts", "import": "./dist/admin.js" },
|
||||
"./astro": {
|
||||
"types": "./dist/astro/index.d.ts",
|
||||
"import": "./dist/astro/index.js"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Auto-Wiring
|
||||
|
||||
Plugin block components are automatically merged into `<PortableText>` on the site. Merge order:
|
||||
|
||||
1. EmDash defaults (lowest priority)
|
||||
2. Plugin block components
|
||||
3. User-provided components (highest priority)
|
||||
|
||||
Site authors don't need to import anything. User components take precedence over plugin defaults.
|
||||
|
||||
## Complete Example
|
||||
|
||||
```typescript
|
||||
// src/index.ts
|
||||
import { definePlugin } from "emdash";
|
||||
import type { PluginDescriptor } from "emdash";
|
||||
|
||||
export function embedsPlugin(options = {}): PluginDescriptor {
|
||||
return {
|
||||
id: "embeds",
|
||||
version: "1.0.0",
|
||||
entrypoint: "@my-org/plugin-embeds",
|
||||
componentsEntry: "@my-org/plugin-embeds/astro",
|
||||
options,
|
||||
};
|
||||
}
|
||||
|
||||
export function createPlugin() {
|
||||
return definePlugin({
|
||||
id: "embeds",
|
||||
version: "1.0.0",
|
||||
|
||||
admin: {
|
||||
portableTextBlocks: [
|
||||
{
|
||||
type: "youtube",
|
||||
label: "YouTube Video",
|
||||
icon: "video",
|
||||
placeholder: "Paste YouTube URL...",
|
||||
fields: [
|
||||
{ type: "text_input", action_id: "id", label: "YouTube URL" },
|
||||
{ type: "text_input", action_id: "title", label: "Title" },
|
||||
{
|
||||
type: "text_input",
|
||||
action_id: "poster",
|
||||
label: "Poster Image URL",
|
||||
},
|
||||
],
|
||||
},
|
||||
{
|
||||
type: "linkPreview",
|
||||
label: "Link Preview",
|
||||
icon: "link-external",
|
||||
placeholder: "Paste any URL...",
|
||||
},
|
||||
],
|
||||
},
|
||||
});
|
||||
}
|
||||
|
||||
export default createPlugin;
|
||||
```
|
||||
|
||||
```typescript
|
||||
// src/astro/index.ts
|
||||
import YouTube from "./YouTube.astro";
|
||||
import LinkPreview from "./LinkPreview.astro";
|
||||
|
||||
export const blockComponents = {
|
||||
youtube: YouTube,
|
||||
linkPreview: LinkPreview,
|
||||
};
|
||||
```
|
||||
82
skills/creating-plugins/references/publishing.md
Normal file
82
skills/creating-plugins/references/publishing.md
Normal file
@@ -0,0 +1,82 @@
|
||||
# Publishing to the Marketplace
|
||||
|
||||
Sandboxed plugins can be published to the EmDash Marketplace for one-click installation from the admin UI.
|
||||
|
||||
## Bundle Format
|
||||
|
||||
Published plugins are `.tar.gz` tarballs:
|
||||
|
||||
| File | Required | Description |
|
||||
| --------------- | -------- | ----------------------------------------------- |
|
||||
| `manifest.json` | Yes | Metadata extracted from `definePlugin()` |
|
||||
| `backend.js` | No | Bundled sandbox code (self-contained ES module) |
|
||||
| `admin.js` | No | Bundled admin UI code |
|
||||
| `README.md` | No | Plugin documentation |
|
||||
| `icon.png` | No | Plugin icon (256x256 PNG) |
|
||||
| `screenshots/` | No | Up to 5 screenshots (PNG/JPEG, max 1920x1080) |
|
||||
|
||||
## Package Exports for Bundling
|
||||
|
||||
The bundle command uses `package.json` exports to find entrypoints:
|
||||
|
||||
```json
|
||||
{
|
||||
"exports": {
|
||||
".": { "import": "./dist/index.mjs" },
|
||||
"./sandbox": { "import": "./dist/sandbox-entry.mjs" },
|
||||
"./admin": { "import": "./dist/admin.mjs" }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
| Export | Purpose | Built as |
|
||||
| ------------- | ----------------------------- | ------------------------------------ |
|
||||
| `"."` | Main entry — extract manifest | Externals: `emdash`, `@emdashcms/*` |
|
||||
| `"./sandbox"` | Backend code for the sandbox | Fully self-contained (no externals) |
|
||||
| `"./admin"` | Admin UI components | Fully self-contained |
|
||||
|
||||
If `"./sandbox"` is missing, the command looks for `src/sandbox-entry.ts`.
|
||||
|
||||
## Build and Publish
|
||||
|
||||
```bash
|
||||
# Bundle only (inspect first)
|
||||
emdash plugin bundle
|
||||
tar tzf dist/my-plugin-1.0.0.tar.gz
|
||||
|
||||
# Publish (uploads to marketplace)
|
||||
emdash plugin publish
|
||||
|
||||
# Build + publish in one step
|
||||
emdash plugin publish --build
|
||||
```
|
||||
|
||||
First-time publish authenticates via GitHub device authorization. Token stored in `~/.config/emdash/auth.json` (30-day expiry).
|
||||
|
||||
## Validation
|
||||
|
||||
The bundle command checks:
|
||||
|
||||
- **Size limit** — Total bundle under 5MB
|
||||
- **No Node.js built-ins** — `backend.js` cannot import `fs`, `path`, etc.
|
||||
- **Sandbox-incompatible features** — Warns if the plugin declares `portableTextBlocks`, `admin.entry` (React components), or API `routes`, since these require trusted mode
|
||||
- **Icon dimensions** — 256x256 PNG (warns if wrong)
|
||||
- **Screenshot limits** — Max 5, max 1920x1080
|
||||
|
||||
## Security Audit
|
||||
|
||||
Every published version is automatically audited for:
|
||||
|
||||
- Data exfiltration patterns
|
||||
- Credential harvesting via settings
|
||||
- Obfuscated code
|
||||
- Resource abuse (crypto mining, etc.)
|
||||
- Suspicious network activity
|
||||
|
||||
Verdict: **pass**, **warn**, or **fail** — displayed on marketplace listing.
|
||||
|
||||
## Version Requirements
|
||||
|
||||
- Each version must have higher semver than the last
|
||||
- Cannot overwrite or republish an existing version
|
||||
- Plugin ID is auto-registered on first publish
|
||||
264
skills/creating-plugins/references/storage.md
Normal file
264
skills/creating-plugins/references/storage.md
Normal file
@@ -0,0 +1,264 @@
|
||||
# Storage, KV & Settings
|
||||
|
||||
Plugins have three data mechanisms:
|
||||
|
||||
| Mechanism | Purpose | Access |
|
||||
| ------------------- | ----------------------------------------- | ---------------------- |
|
||||
| **Storage** | Document collections with indexed queries | `ctx.storage` |
|
||||
| **KV** | Key-value pairs for state and settings | `ctx.kv` |
|
||||
| **Settings Schema** | Auto-generated admin UI for configuration | `admin.settingsSchema` |
|
||||
|
||||
## Storage Collections
|
||||
|
||||
Declare in `definePlugin({ storage })`. EmDash creates the schema automatically — no migrations.
|
||||
|
||||
```typescript
|
||||
definePlugin({
|
||||
id: "forms",
|
||||
version: "1.0.0",
|
||||
|
||||
storage: {
|
||||
submissions: {
|
||||
indexes: [
|
||||
"formId", // Single-field index
|
||||
"status",
|
||||
"createdAt",
|
||||
["formId", "createdAt"], // Composite index
|
||||
],
|
||||
},
|
||||
forms: {
|
||||
indexes: ["slug"],
|
||||
},
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
Storage is scoped to the plugin — `submissions` in plugin `forms` is separate from `submissions` in another plugin.
|
||||
|
||||
### CRUD
|
||||
|
||||
```typescript
|
||||
const { submissions } = ctx.storage;
|
||||
|
||||
await submissions.put("sub_123", { formId: "contact", email: "user@example.com" });
|
||||
const item = await submissions.get("sub_123");
|
||||
const exists = await submissions.exists("sub_123");
|
||||
await submissions.delete("sub_123");
|
||||
```
|
||||
|
||||
### Batch Operations
|
||||
|
||||
```typescript
|
||||
const items = await submissions.getMany(["sub_1", "sub_2"]); // Map<string, T>
|
||||
|
||||
await submissions.putMany([
|
||||
{ id: "sub_1", data: { formId: "contact", status: "new" } },
|
||||
{ id: "sub_2", data: { formId: "contact", status: "new" } },
|
||||
]);
|
||||
|
||||
const deletedCount = await submissions.deleteMany(["sub_1", "sub_2"]);
|
||||
```
|
||||
|
||||
### Querying
|
||||
|
||||
Only indexed fields can be queried. Non-indexed queries throw.
|
||||
|
||||
```typescript
|
||||
const result = await ctx.storage.submissions.query({
|
||||
where: {
|
||||
formId: "contact",
|
||||
status: "pending",
|
||||
},
|
||||
orderBy: { createdAt: "desc" },
|
||||
limit: 20,
|
||||
});
|
||||
|
||||
// result.items - Array of { id, data }
|
||||
// result.cursor - Pagination cursor
|
||||
// result.hasMore - Boolean
|
||||
```
|
||||
|
||||
### Where Operators
|
||||
|
||||
```typescript
|
||||
// Exact match
|
||||
where: { status: "pending" }
|
||||
|
||||
// Range
|
||||
where: { createdAt: { gte: "2024-01-01" } }
|
||||
where: { score: { gt: 50, lte: 100 } }
|
||||
|
||||
// In
|
||||
where: { status: { in: ["pending", "approved"] } }
|
||||
|
||||
// Starts with
|
||||
where: { slug: { startsWith: "blog-" } }
|
||||
```
|
||||
|
||||
### Pagination
|
||||
|
||||
```typescript
|
||||
let cursor: string | undefined;
|
||||
do {
|
||||
const result = await ctx.storage.submissions!.query({
|
||||
orderBy: { createdAt: "desc" },
|
||||
limit: 100,
|
||||
cursor,
|
||||
});
|
||||
// process result.items
|
||||
cursor = result.cursor;
|
||||
} while (cursor);
|
||||
```
|
||||
|
||||
### Counting
|
||||
|
||||
```typescript
|
||||
const total = await ctx.storage.submissions!.count();
|
||||
const pending = await ctx.storage.submissions!.count({ status: "pending" });
|
||||
```
|
||||
|
||||
### Index Design
|
||||
|
||||
| Query Pattern | Index Needed |
|
||||
| ---------------------------------------- | ------------------------- |
|
||||
| Filter by `formId` | `"formId"` |
|
||||
| Filter by `formId`, order by `createdAt` | `["formId", "createdAt"]` |
|
||||
| Order by `createdAt` only | `"createdAt"` |
|
||||
|
||||
Composite indexes support filtering on the first field + ordering by the second.
|
||||
|
||||
### Type Safety
|
||||
|
||||
```typescript
|
||||
interface Submission {
|
||||
formId: string;
|
||||
status: "pending" | "approved" | "spam";
|
||||
createdAt: string;
|
||||
}
|
||||
|
||||
// Cast in hook/route handlers
|
||||
const submissions = ctx.storage.submissions as StorageCollection<Submission>;
|
||||
```
|
||||
|
||||
### Full API
|
||||
|
||||
```typescript
|
||||
interface StorageCollection<T = unknown> {
|
||||
get(id: string): Promise<T | null>;
|
||||
put(id: string, data: T): Promise<void>;
|
||||
delete(id: string): Promise<boolean>;
|
||||
exists(id: string): Promise<boolean>;
|
||||
getMany(ids: string[]): Promise<Map<string, T>>;
|
||||
putMany(items: Array<{ id: string; data: T }>): Promise<void>;
|
||||
deleteMany(ids: string[]): Promise<number>;
|
||||
query(options?: QueryOptions): Promise<PaginatedResult<{ id: string; data: T }>>;
|
||||
count(where?: WhereClause): Promise<number>;
|
||||
}
|
||||
```
|
||||
|
||||
## KV Store
|
||||
|
||||
General-purpose key-value store. Use for internal state, cached computations, or programmatic access to settings.
|
||||
|
||||
```typescript
|
||||
interface KVAccess {
|
||||
get<T>(key: string): Promise<T | null>;
|
||||
set(key: string, value: unknown): Promise<void>;
|
||||
delete(key: string): Promise<boolean>;
|
||||
list(prefix?: string): Promise<Array<{ key: string; value: unknown }>>;
|
||||
}
|
||||
```
|
||||
|
||||
### Key Naming Conventions
|
||||
|
||||
| Prefix | Purpose | Example |
|
||||
| ----------- | ----------------------------- | ----------------- |
|
||||
| `settings:` | User-configurable preferences | `settings:apiKey` |
|
||||
| `state:` | Internal plugin state | `state:lastSync` |
|
||||
| `cache:` | Cached data | `cache:results` |
|
||||
|
||||
```typescript
|
||||
await ctx.kv.set("settings:webhookUrl", url);
|
||||
await ctx.kv.set("state:lastRun", new Date().toISOString());
|
||||
const allSettings = await ctx.kv.list("settings:");
|
||||
```
|
||||
|
||||
## Settings Schema
|
||||
|
||||
Declare `admin.settingsSchema` to auto-generate a settings form in the admin UI:
|
||||
|
||||
```typescript
|
||||
admin: {
|
||||
settingsSchema: {
|
||||
siteTitle: {
|
||||
type: "string",
|
||||
label: "Site Title",
|
||||
description: "Used in title tags",
|
||||
default: "",
|
||||
},
|
||||
maxItems: {
|
||||
type: "number",
|
||||
label: "Max Items",
|
||||
default: 100,
|
||||
min: 1,
|
||||
max: 1000,
|
||||
},
|
||||
enabled: {
|
||||
type: "boolean",
|
||||
label: "Enabled",
|
||||
default: true,
|
||||
},
|
||||
theme: {
|
||||
type: "select",
|
||||
label: "Theme",
|
||||
options: [
|
||||
{ value: "light", label: "Light" },
|
||||
{ value: "dark", label: "Dark" },
|
||||
],
|
||||
default: "light",
|
||||
},
|
||||
apiKey: {
|
||||
type: "secret",
|
||||
label: "API Key",
|
||||
description: "Encrypted at rest",
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
### Setting Types
|
||||
|
||||
| Type | UI | Notes |
|
||||
| --------- | ------------ | ----------------------------------------- |
|
||||
| `string` | Text input | Optional `multiline: true` for textarea |
|
||||
| `number` | Number input | Optional `min`, `max` |
|
||||
| `boolean` | Toggle | |
|
||||
| `select` | Dropdown | Requires `options: [{ value, label }]` |
|
||||
| `secret` | Masked input | Encrypted at rest, never shown after save |
|
||||
|
||||
### Reading Settings
|
||||
|
||||
Settings are accessed via KV with `settings:` prefix:
|
||||
|
||||
```typescript
|
||||
const enabled = (await ctx.kv.get<boolean>("settings:enabled")) ?? true;
|
||||
const apiKey = await ctx.kv.get<string>("settings:apiKey");
|
||||
```
|
||||
|
||||
Schema defaults are UI defaults only — not auto-persisted. Handle missing values with `??` or persist defaults in `plugin:install`:
|
||||
|
||||
```typescript
|
||||
"plugin:install": async (_event, ctx) => {
|
||||
await ctx.kv.set("settings:enabled", true);
|
||||
await ctx.kv.set("settings:maxItems", 100);
|
||||
}
|
||||
```
|
||||
|
||||
## When to Use What
|
||||
|
||||
| Use Case | Mechanism |
|
||||
| -------------------------------------------- | --------------------------------- |
|
||||
| Admin-editable preferences | `settingsSchema` + KV `settings:` |
|
||||
| Internal state (timestamps, cursors) | KV `state:` |
|
||||
| Collections of documents (logs, submissions) | Storage |
|
||||
| Cached computations | KV `cache:` |
|
||||
164
skills/emdash-cli/EDITING-FLOW.md
Normal file
164
skills/emdash-cli/EDITING-FLOW.md
Normal file
@@ -0,0 +1,164 @@
|
||||
# Editing Flow
|
||||
|
||||
How content editing works through the CLI. Covers Portable Text conversion, `_rev` tokens, and raw mode.
|
||||
|
||||
## Portable Text and Markdown
|
||||
|
||||
EmDash stores rich text as [Portable Text](https://portabletext.org/) (PT) — a structured JSON format. The CLI automatically converts between PT and markdown so you work with a familiar text format.
|
||||
|
||||
### Automatic Conversion
|
||||
|
||||
- **On read**: PT arrays in `portableText` fields are converted to markdown strings
|
||||
- **On write**: markdown strings in `portableText` fields are converted back to PT arrays
|
||||
- **Non-PT fields** (string, text, number, etc.) pass through unchanged
|
||||
|
||||
The CLI detects which fields need conversion by fetching the collection's field schema.
|
||||
|
||||
### Supported Markdown Syntax
|
||||
|
||||
Standard blocks (lossless round-trip):
|
||||
|
||||
| Markdown | PT block |
|
||||
| ---------------------------- | ------------------------------------------ |
|
||||
| `# Heading` through `######` | h1-h6 blocks |
|
||||
| Plain paragraph | normal block |
|
||||
| `> Quote` | blockquote |
|
||||
| `- item` / `* item` | bullet list (nesting via 2-space indent) |
|
||||
| `1. item` | numbered list (nesting via 2-space indent) |
|
||||
| ` ``` ```lang``` ` | code block with language |
|
||||
| `` | image block |
|
||||
|
||||
Inline marks:
|
||||
|
||||
| Markdown | PT mark |
|
||||
| ------------- | --------------- |
|
||||
| `**bold**` | `strong` |
|
||||
| `_italic_` | `em` |
|
||||
| `` `code` `` | `code` |
|
||||
| `~~strike~~` | `strikethrough` |
|
||||
| `[text](url)` | link annotation |
|
||||
|
||||
### Unknown Blocks (Opaque Fences)
|
||||
|
||||
Blocks the converter doesn't recognize (custom blocks, embeds, etc.) are serialized as HTML comments:
|
||||
|
||||
```markdown
|
||||
<!--ec:block {"_type":"callout","level":"warning","text":"Be careful"} -->
|
||||
```
|
||||
|
||||
These survive round-trips intact. You can see and move them, but editing the JSON risks corruption. On write, they're deserialized back to the original PT block.
|
||||
|
||||
### Raw Mode
|
||||
|
||||
Skip markdown conversion entirely to work with raw PT JSON:
|
||||
|
||||
```bash
|
||||
npx emdash content get posts 01ABC123 --raw
|
||||
```
|
||||
|
||||
Use raw mode when:
|
||||
|
||||
- You need exact control over PT structure
|
||||
- You're working with custom block types
|
||||
- You're copying PT between items without transformation
|
||||
|
||||
### Writing Content
|
||||
|
||||
When creating or updating content, each field is checked:
|
||||
|
||||
- `portableText` field + **string value** → converts markdown to PT before sending
|
||||
- `portableText` field + **array value** → sends as raw PT (no conversion)
|
||||
- Any other field type → sends as-is
|
||||
|
||||
```bash
|
||||
# Markdown string — converted to PT automatically
|
||||
npx emdash content create posts --data '{"title": "Hello", "body": "# Welcome\n\nThis is **bold**."}'
|
||||
|
||||
# Raw PT array — passed through as-is
|
||||
npx emdash content create posts --data '{"title": "Hello", "body": [{"_type": "block", "children": [{"_type": "span", "text": "Welcome"}]}]}'
|
||||
```
|
||||
|
||||
## Auto-Publishing
|
||||
|
||||
The CLI is designed for agents. It auto-publishes on `create` and `update` by default so agents get read-after-write consistency without managing the draft/publish lifecycle.
|
||||
|
||||
### How It Works
|
||||
|
||||
- **`create`** — creates the item, then publishes it. The returned item is in `published` status.
|
||||
- **`update`** — updates the item. If the collection uses revisions and the update created a draft revision, it auto-publishes to promote the draft to the content table. The returned item reflects the updated data.
|
||||
- **`get`** — returns the latest state. If a pending draft exists (e.g. someone edited in the admin UI but didn't publish), the draft data is returned instead of the published data. Use `--published` to see only published data.
|
||||
|
||||
Use `--draft` on create/update to skip auto-publishing.
|
||||
|
||||
### Why Auto-Publish?
|
||||
|
||||
EmDash collections can support draft revisions. When they do, `update` writes data to a draft revision instead of the content table. Without auto-publish, an agent would update, then `get` the item, and see stale published data — not the changes it just made. Auto-publish eliminates this confusion.
|
||||
|
||||
## Read-Before-Write
|
||||
|
||||
Updates use `_rev` tokens for optimistic concurrency — the same principle as a file editing tool that requires you to read a file before you can edit it. You must see what you're overwriting.
|
||||
|
||||
### The Analogy
|
||||
|
||||
Think of it like a filesystem edit tool:
|
||||
|
||||
1. You **read** the file to see its current contents
|
||||
2. You decide what to change
|
||||
3. You **write** with a reference to the version you read
|
||||
|
||||
If someone else changed the file between your read and your write, the write fails — you can't overwrite changes you haven't seen. The `_rev` token is your proof that you've seen the current state.
|
||||
|
||||
### How It Works
|
||||
|
||||
1. `content get` returns the item with a `_rev` token in the output
|
||||
2. You pass that `_rev` back to `content update` via `--rev`
|
||||
3. The server checks: if the item has changed since your read, it returns **409 Conflict**
|
||||
4. A successful update returns a new `_rev` for subsequent edits
|
||||
|
||||
### What Is a `_rev` Token?
|
||||
|
||||
An opaque base64 string. Don't parse it — just pass it back.
|
||||
|
||||
### CLI Workflow
|
||||
|
||||
The CLI **requires** `--rev` on updates. The typical workflow:
|
||||
|
||||
```bash
|
||||
# 1. Read the item — note the _rev in the output
|
||||
npx emdash content get posts 01ABC123
|
||||
# Output includes: _rev: MToyMDI2LTAyLTE0...
|
||||
|
||||
# 2. Update with the _rev you received — auto-publishes by default
|
||||
npx emdash content update posts 01ABC123 \
|
||||
--rev MToyMDI2LTAyLTE0... \
|
||||
--data '{"title": "New Title"}'
|
||||
# Output shows updated item with new _rev
|
||||
```
|
||||
|
||||
If you try to update without `--rev`, the CLI rejects the command. This ensures you always know what you're overwriting.
|
||||
|
||||
### Conflict Handling
|
||||
|
||||
If someone else updated the item between your read and write:
|
||||
|
||||
```
|
||||
EmDashApiError: Content has been modified since last read (version conflict)
|
||||
status: 409
|
||||
code: CONFLICT
|
||||
```
|
||||
|
||||
Resolution: re-read with `get`, inspect the new state, then `update` with the fresh `_rev`.
|
||||
|
||||
### Which Operations Need `_rev`?
|
||||
|
||||
Only `update`. All other operations are either idempotent or non-destructive:
|
||||
|
||||
| Command | `--rev` needed? | Why |
|
||||
| ------------------- | --------------- | ------------------------ |
|
||||
| `content create` | No | Nothing exists yet |
|
||||
| `content update` | **Yes** | Overwrites existing data |
|
||||
| `content delete` | No | Soft delete, reversible |
|
||||
| `content publish` | No | Idempotent status change |
|
||||
| `content unpublish` | No | Idempotent status change |
|
||||
| `content schedule` | No | Only changes metadata |
|
||||
| `content restore` | No | Restores from trash |
|
||||
246
skills/emdash-cli/SKILL.md
Normal file
246
skills/emdash-cli/SKILL.md
Normal file
@@ -0,0 +1,246 @@
|
||||
---
|
||||
name: emdash-cli
|
||||
description: Use the EmDash CLI to manage content, schema, media, and more. Use this skill when you need to interact with a running EmDash instance from the command line — creating content, managing collections, uploading media, generating types, or scripting CMS operations.
|
||||
---
|
||||
|
||||
# EmDash CLI
|
||||
|
||||
The EmDash CLI (`emdash` or `ec`) manages EmDash CMS instances. Commands fall into two categories:
|
||||
|
||||
- **Local commands** — work directly on a SQLite file, no running server needed: `init`, `dev`, `seed`, `export-seed`, `auth secret`
|
||||
- **Remote commands** — talk to a running EmDash instance via HTTP: `types`, `login`, `logout`, `whoami`, `content`, `schema`, `media`, `search`, `taxonomy`, `menu`
|
||||
|
||||
## Authentication
|
||||
|
||||
Remote commands resolve auth automatically:
|
||||
|
||||
1. `--token` flag
|
||||
2. `EMDASH_TOKEN` env var
|
||||
3. Stored credentials from `emdash login`
|
||||
4. Dev bypass (localhost only — no token needed)
|
||||
|
||||
For local dev servers, just run the command — auth is handled automatically. For remote instances, run `emdash login --url https://my-site.pages.dev` first.
|
||||
|
||||
## Custom Headers & Reverse Proxies
|
||||
|
||||
Sites behind Cloudflare Access or other reverse proxies need auth headers on every request. The CLI supports this via `--header` flags and environment variables.
|
||||
|
||||
### Service Tokens (Recommended for CI/Automation)
|
||||
|
||||
```bash
|
||||
# Single header
|
||||
npx emdash login --url https://my-site.pages.dev \
|
||||
--header "CF-Access-Client-Id: xxx.access" \
|
||||
--header "CF-Access-Client-Secret: yyy"
|
||||
|
||||
# Short form
|
||||
npx emdash login -H "CF-Access-Client-Id: xxx" -H "CF-Access-Client-Secret: yyy"
|
||||
|
||||
# Via environment (newline-separated)
|
||||
export EMDASH_HEADERS="CF-Access-Client-Id: xxx
|
||||
CF-Access-Client-Secret: yyy"
|
||||
npx emdash login --url https://my-site.pages.dev
|
||||
```
|
||||
|
||||
Headers are persisted to `~/.config/emdash/auth.json` after login, so subsequent commands inherit them automatically.
|
||||
|
||||
### Cloudflare Access Browser Flow
|
||||
|
||||
If you don't have service tokens and `cloudflared` is installed, the CLI will automatically:
|
||||
|
||||
1. Detect when Access blocks the request
|
||||
2. Try to get a cached JWT via `cloudflared access token`
|
||||
3. Fall back to `cloudflared access login` for browser-based auth
|
||||
|
||||
This works for interactive use but isn't suitable for CI. Use service tokens for automation.
|
||||
|
||||
### Generic Reverse Proxy Auth
|
||||
|
||||
The `--header` flag works with any auth scheme:
|
||||
|
||||
```bash
|
||||
# Basic auth
|
||||
npx emdash login --url https://example.com -H "Authorization: Basic dXNlcjpwYXNz"
|
||||
|
||||
# Custom auth header
|
||||
npx emdash login --url https://example.com -H "X-API-Key: secret123"
|
||||
```
|
||||
|
||||
## Quick Reference
|
||||
|
||||
### Database Setup
|
||||
|
||||
```bash
|
||||
# Initialize database with migrations
|
||||
npx emdash init
|
||||
|
||||
# Start dev server (runs migrations, starts Astro)
|
||||
npx emdash dev
|
||||
|
||||
# Start dev server and generate types from remote
|
||||
npx emdash dev --types
|
||||
|
||||
# Apply a seed file
|
||||
npx emdash seed .emdash/seed.json
|
||||
|
||||
# Export database as seed
|
||||
npx emdash export-seed > seed.json
|
||||
npx emdash export-seed --with-content > seed.json
|
||||
```
|
||||
|
||||
### Type Generation
|
||||
|
||||
```bash
|
||||
# Generate types from local dev server
|
||||
npx emdash types
|
||||
|
||||
# Generate from remote
|
||||
npx emdash types --url https://my-site.pages.dev
|
||||
|
||||
# Custom output path
|
||||
npx emdash types --output src/types/cms.ts
|
||||
```
|
||||
|
||||
Writes `.emdash/types.ts` (TypeScript interfaces) and `.emdash/schema.json`.
|
||||
|
||||
### Authentication
|
||||
|
||||
```bash
|
||||
# Login (OAuth Device Flow)
|
||||
npx emdash login --url https://my-site.pages.dev
|
||||
|
||||
# Check current user
|
||||
npx emdash whoami
|
||||
|
||||
# Logout
|
||||
npx emdash logout
|
||||
|
||||
# Generate auth secret for deployment
|
||||
npx emdash auth secret
|
||||
```
|
||||
|
||||
### Content CRUD
|
||||
|
||||
The CLI is designed for agents. Create and update auto-publish by default so agents get read-after-write consistency without managing drafts.
|
||||
|
||||
```bash
|
||||
# List content
|
||||
npx emdash content list posts
|
||||
npx emdash content list posts --status published --limit 10
|
||||
|
||||
# Get a single item (Portable Text fields converted to markdown)
|
||||
# Returns draft data if a pending draft exists
|
||||
npx emdash content get posts 01ABC123
|
||||
npx emdash content get posts 01ABC123 --raw # skip PT->markdown conversion
|
||||
npx emdash content get posts 01ABC123 --published # ignore pending drafts
|
||||
|
||||
# Create content (auto-publishes by default)
|
||||
npx emdash content create posts --data '{"title": "Hello", "body": "# World"}'
|
||||
npx emdash content create posts --file post.json --slug hello-world
|
||||
npx emdash content create posts --draft --data '...' # keep as draft
|
||||
cat post.json | npx emdash content create posts --stdin
|
||||
|
||||
# Update (requires --rev from a prior get, auto-publishes by default)
|
||||
npx emdash content update posts 01ABC123 --rev MToyMDI2... --data '{"title": "Updated"}'
|
||||
npx emdash content update posts 01ABC123 --rev MToyMDI2... --draft --data '...' # keep as draft
|
||||
|
||||
# Delete (soft delete)
|
||||
npx emdash content delete posts 01ABC123
|
||||
|
||||
# Lifecycle
|
||||
npx emdash content publish posts 01ABC123
|
||||
npx emdash content unpublish posts 01ABC123
|
||||
npx emdash content schedule posts 01ABC123 --at 2026-03-01T09:00:00Z
|
||||
npx emdash content restore posts 01ABC123
|
||||
```
|
||||
|
||||
### Schema Management
|
||||
|
||||
```bash
|
||||
# List collections
|
||||
npx emdash schema list
|
||||
|
||||
# Get collection with fields
|
||||
npx emdash schema get posts
|
||||
|
||||
# Create collection
|
||||
npx emdash schema create articles --label Articles --description "Blog articles"
|
||||
|
||||
# Delete collection
|
||||
npx emdash schema delete articles --force
|
||||
|
||||
# Add field
|
||||
npx emdash schema add-field posts body --type portableText --label "Body Content"
|
||||
npx emdash schema add-field posts featured --type boolean --required
|
||||
|
||||
# Remove field
|
||||
npx emdash schema remove-field posts featured
|
||||
```
|
||||
|
||||
Field types: `string`, `text`, `number`, `integer`, `boolean`, `datetime`, `image`, `reference`, `portableText`, `json`.
|
||||
|
||||
### Media
|
||||
|
||||
```bash
|
||||
# List media
|
||||
npx emdash media list
|
||||
npx emdash media list --mime image/png
|
||||
|
||||
# Upload
|
||||
npx emdash media upload ./photo.jpg --alt "A sunset" --caption "Bristol, 2026"
|
||||
|
||||
# Get / delete
|
||||
npx emdash media get 01MEDIA123
|
||||
npx emdash media delete 01MEDIA123
|
||||
```
|
||||
|
||||
### Search
|
||||
|
||||
```bash
|
||||
npx emdash search "hello world"
|
||||
npx emdash search "hello" --collection posts --limit 5
|
||||
```
|
||||
|
||||
### Taxonomies
|
||||
|
||||
```bash
|
||||
npx emdash taxonomy list
|
||||
npx emdash taxonomy terms categories
|
||||
npx emdash taxonomy add-term categories --name "Tech" --slug tech
|
||||
npx emdash taxonomy add-term categories --name "Frontend" --parent 01PARENT123
|
||||
```
|
||||
|
||||
### Menus
|
||||
|
||||
```bash
|
||||
npx emdash menu list
|
||||
npx emdash menu get primary
|
||||
```
|
||||
|
||||
## Drafts and Publishing
|
||||
|
||||
The CLI auto-publishes on `create` and `update` by default. This means:
|
||||
|
||||
- **`create`** creates the item and immediately publishes it
|
||||
- **`update`** updates the item and publishes if a draft revision was created
|
||||
- **`get`** returns draft data if a pending draft exists (e.g. from the admin UI)
|
||||
|
||||
Use `--draft` on create/update to skip auto-publishing. Use `--published` on get to ignore pending drafts.
|
||||
|
||||
Collections that support revisions store edits as draft revisions. The CLI handles this transparently — agents don't need to know whether a collection uses revisions or not.
|
||||
|
||||
## JSON Output
|
||||
|
||||
All remote commands support `--json` for machine-readable output. It's auto-enabled when stdout is piped.
|
||||
|
||||
```bash
|
||||
# Pipe to jq
|
||||
npx emdash content list posts --json | jq '.items[].slug'
|
||||
|
||||
# Use in scripts
|
||||
ID=$(npx emdash content create posts --data '{"title":"Hello"}' --json | jq -r '.id')
|
||||
```
|
||||
|
||||
## Editing Flow
|
||||
|
||||
For details on how content editing works — Portable Text/markdown conversion, `_rev` tokens, and raw mode — see **[EDITING-FLOW.md](./EDITING-FLOW.md)**.
|
||||
299
skills/wordpress-plugin-to-emdash/SKILL.md
Normal file
299
skills/wordpress-plugin-to-emdash/SKILL.md
Normal file
@@ -0,0 +1,299 @@
|
||||
---
|
||||
name: wordpress-plugin-to-emdash
|
||||
description: Port a WordPress plugin to EmDash CMS. Use this skill when asked to migrate, convert, or port a WordPress plugin, theme functionality, or custom post type to EmDash. Provides concept mapping and implementation patterns.
|
||||
---
|
||||
|
||||
# Porting WordPress Plugins to EmDash
|
||||
|
||||
This skill maps WordPress concepts to their EmDash equivalents for plugin porting. For general plugin authoring details (plugin structure, `definePlugin()`, hooks, storage, admin UI, etc.), use the **creating-plugins** skill.
|
||||
|
||||
## Migration Approach
|
||||
|
||||
1. **Understand the plugin** — What does it do, not how
|
||||
2. **Identify concepts** — Content types, admin pages, hooks, shortcodes
|
||||
3. **Map to EmDash** — Use the tables below
|
||||
4. **Implement in TypeScript** — Clean room, not line-by-line port. Use the **creating-plugins** skill for implementation details.
|
||||
5. **Test behaviour** — Same result, different implementation
|
||||
|
||||
## Concept Mapping
|
||||
|
||||
### Content & Data
|
||||
|
||||
| WordPress | EmDash | Notes |
|
||||
| ----------------------- | ------------------------------------------- | --------------------------------------------- |
|
||||
| `register_post_type()` | `SchemaRegistry.createCollection()` | Via Admin API or seed file |
|
||||
| `register_taxonomy()` | `_emdash_taxonomy_defs` table | Hierarchical or flat, attached to collections |
|
||||
| `register_meta()` / ACF | Collection fields via SchemaRegistry | All become typed schema fields |
|
||||
| `get_post_meta()` | `entry.data.fieldName` | Direct typed access |
|
||||
| `get_option()` | `getSiteSetting()` / `ctx.kv` | Site settings or plugin-namespaced KV |
|
||||
| `WP_Query` | `getEmDashCollection()` | Runtime queries with filters |
|
||||
| `get_post($id)` | `getEmDashEntry(collection, slug)` | Returns entry or null |
|
||||
| `wp_insert_post()` | `POST /_emdash/api/content/{type}` | REST API |
|
||||
| `wp_update_post()` | `PUT /_emdash/api/content/{type}/{id}` | REST API |
|
||||
| `wp_delete_post()` | `DELETE /_emdash/api/content/{type}/{id}` | Soft delete |
|
||||
| Custom tables | Plugin storage collections | `ctx.storage.collectionName.put/get/query` |
|
||||
|
||||
### Site Configuration
|
||||
|
||||
| WordPress | EmDash | Notes |
|
||||
| ------------------------ | --------------------------- | ---------------------------------------- |
|
||||
| `get_bloginfo('name')` | `getSiteSetting('title')` | From `options` table with `site:` prefix |
|
||||
| `get_option('blogdesc')` | `getSiteSetting('tagline')` | Site settings API |
|
||||
| Theme Customizer | Site Settings admin page | `/_emdash/admin/settings` |
|
||||
| `site_icon` | `getSiteSetting('favicon')` | Media reference |
|
||||
| `custom_logo` | `getSiteSetting('logo')` | Media reference |
|
||||
|
||||
### Navigation Menus
|
||||
|
||||
| WordPress | EmDash | Notes |
|
||||
| ---------------------- | --------------------------------------- | ----------------------------------- |
|
||||
| `register_nav_menu()` | Create menu via admin or seed | `_emdash_menus` table |
|
||||
| `wp_nav_menu()` | `getMenu(name)` | Returns `{ items: MenuItem[] }` |
|
||||
| `wp_nav_menu_item` | `_emdash_menu_items` table | Type: custom, page, post, taxonomy |
|
||||
| `_menu_item_object_id` | `reference_id` + `reference_collection` | Links to content entries |
|
||||
| Menu locations | Query by name in templates | No locations concept — direct query |
|
||||
|
||||
### Taxonomies
|
||||
|
||||
| WordPress | EmDash | Notes |
|
||||
| --------------------- | --------------------------------------- | ------------------------------ |
|
||||
| `register_taxonomy()` | `_emdash_taxonomy_defs` table | Define via admin, seed, or API |
|
||||
| `get_terms()` | `getTaxonomyTerms(name)` | Returns tree for hierarchical |
|
||||
| `get_the_terms()` | `getEntryTerms(collection, id, name)` | Terms for specific entry |
|
||||
| `wp_set_post_terms()` | `TaxonomyRepository.setTermsForEntry()` | Replace terms for entry |
|
||||
| Hierarchical taxonomy | `hierarchical: true` in definition | Categories-style |
|
||||
| Flat taxonomy | `hierarchical: false` | Tags-style |
|
||||
|
||||
### Widgets & Sidebars
|
||||
|
||||
| WordPress | EmDash | Notes |
|
||||
| -------------------- | -------------------------------------- | ------------------------------- |
|
||||
| `register_sidebar()` | `_emdash_widget_areas` table | Create via admin or seed |
|
||||
| `dynamic_sidebar()` | `getWidgetArea(name)` | Returns `{ widgets: Widget[] }` |
|
||||
| `WP_Widget` class | Widget types: content, menu, component | Simplified — 3 types only |
|
||||
| Text widget | `type: 'content'` + Portable Text | Rich text widget |
|
||||
| Nav Menu widget | `type: 'menu'` + `menuName` | References a menu |
|
||||
| Custom widgets | `type: 'component'` + `componentId` | Plugin-registered components |
|
||||
|
||||
### Admin UI
|
||||
|
||||
| WordPress | EmDash | Notes |
|
||||
| ------------------------ | --------------------------------- | ---------------------------------------- |
|
||||
| `add_menu_page()` | `admin.pages` in `definePlugin()` | Plugin config |
|
||||
| `add_submenu_page()` | Nested admin pages | Parent determines hierarchy |
|
||||
| `add_settings_section()` | `admin.settingsSchema` | Auto-generated settings page |
|
||||
| `add_meta_box()` | Field groups in collection schema | UI config in schema |
|
||||
| `wp_enqueue_script()` | ESM imports in admin components | React (trusted) or Block Kit (sandboxed) |
|
||||
| Admin notices | Toast notifications | Via admin UI framework |
|
||||
|
||||
### Hooks
|
||||
|
||||
| WordPress | EmDash | Notes |
|
||||
| ---------------------------------- | --------------------------------------- | ----------------------------------------------------- |
|
||||
| `add_action('init')` | `plugin:install` hook | Runs once on first install |
|
||||
| `add_action('save_post')` | `content:afterSave` hook | Filter by `event.collection` |
|
||||
| `add_action('before_delete_post')` | `content:beforeDelete` hook | Return false to prevent |
|
||||
| `add_action('wp_head')` | `page:metadata` / `page:fragments` hook | Metadata is sandbox-safe; scripts need trusted plugin |
|
||||
| `add_action('rest_api_init')` | `definePlugin({ routes })` | Trusted only |
|
||||
| `add_filter('the_content')` | Portable Text components | Custom block renderers |
|
||||
| `add_filter('the_title')` | Template logic | Handle in Astro component |
|
||||
|
||||
### Frontend Output
|
||||
|
||||
| WordPress | EmDash | Notes |
|
||||
| ----------------------- | ---------------------------- | ---------------------------------------------------- |
|
||||
| `add_shortcode()` | Portable Text custom block | Content → block. Template → component. Trusted only. |
|
||||
| `register_block_type()` | PT block + `componentsEntry` | Block data → Astro component props. Trusted only. |
|
||||
| Template tags | Astro expressions | `get_the_title()` → `{post.data.title}` |
|
||||
| Widgets | Widget area + components | Query with `getWidgetArea()` |
|
||||
|
||||
### Plugin Storage
|
||||
|
||||
| WordPress | EmDash | Notes |
|
||||
| ------------------------ | ------------------------ | ---------------------------------- |
|
||||
| `get_option('plugin_*')` | `ctx.kv.get(key)` | Namespaced to plugin automatically |
|
||||
| `update_option()` | `ctx.kv.set(key, value)` | Scoped KV storage |
|
||||
| `delete_option()` | `ctx.kv.delete(key)` | Delete single key |
|
||||
| Custom tables | `ctx.storage.collection` | Document collections with indexes |
|
||||
| Transients | Plugin KV | No TTL yet |
|
||||
|
||||
## Porting-Specific Patterns
|
||||
|
||||
These patterns cover WordPress-specific concepts that don't have a direct 1:1 mapping. For general plugin patterns (defining hooks, storage, routes, admin UI), see the **creating-plugins** skill.
|
||||
|
||||
### Shortcodes → Portable Text Blocks
|
||||
|
||||
WordPress shortcodes (`[youtube id="xxx"]`) become Portable Text custom block types. The block data replaces shortcode attributes, and an Astro component replaces the shortcode render function. This is a trusted-only feature.
|
||||
|
||||
```typescript
|
||||
// WordPress
|
||||
add_shortcode('youtube', function($atts) {
|
||||
return '<iframe src="https://youtube.com/embed/' . $atts['id'] . '"></iframe>';
|
||||
});
|
||||
|
||||
// EmDash — block type declaration in definePlugin()
|
||||
admin: {
|
||||
portableTextBlocks: [{
|
||||
type: "youtube",
|
||||
label: "YouTube Video",
|
||||
icon: "video",
|
||||
fields: [
|
||||
{ type: "text_input", action_id: "id", label: "YouTube URL" },
|
||||
{ type: "text_input", action_id: "title", label: "Title" },
|
||||
],
|
||||
}],
|
||||
}
|
||||
|
||||
// EmDash — Astro component for rendering
|
||||
// src/astro/YouTube.astro
|
||||
const { id, title } = Astro.props.node;
|
||||
const videoId = id?.match(/(?:v=|youtu\.be\/)([^&]+)/)?.[1] ?? id;
|
||||
// <iframe src={`https://youtube-nocookie.com/embed/${videoId}`} ... />
|
||||
```
|
||||
|
||||
### Options API → Plugin KV
|
||||
|
||||
WordPress's `get_option`/`update_option` maps to the plugin KV store. The key difference: WordPress options are global, EmDash KV is automatically scoped to the plugin.
|
||||
|
||||
```typescript
|
||||
// WordPress
|
||||
$count = get_option("myplugin_post_count", 0);
|
||||
update_option("myplugin_post_count", $count + 1);
|
||||
delete_option("myplugin_temp_data");
|
||||
|
||||
// EmDash — no prefix needed, automatically scoped
|
||||
const count = (await ctx.kv.get<number>("post-count")) ?? 0;
|
||||
await ctx.kv.set("post-count", count + 1);
|
||||
await ctx.kv.delete("temp-data");
|
||||
```
|
||||
|
||||
### Custom Database Tables → Storage Collections
|
||||
|
||||
WordPress plugins that create custom tables with `$wpdb->query("CREATE TABLE ...")` should use EmDash's storage collections instead. No migrations needed — declare the schema in `definePlugin()` and it's automatically provisioned.
|
||||
|
||||
```typescript
|
||||
// WordPress
|
||||
$wpdb->insert($table, ['form_id' => $id, 'data' => json_encode($data), 'created_at' => current_time('mysql')]);
|
||||
$results = $wpdb->get_results("SELECT * FROM $table WHERE form_id = '$id' ORDER BY created_at DESC LIMIT 50");
|
||||
|
||||
// EmDash — declared in definePlugin()
|
||||
storage: {
|
||||
submissions: {
|
||||
indexes: ["formId", "createdAt", ["formId", "createdAt"]],
|
||||
},
|
||||
},
|
||||
|
||||
// In a hook or route handler
|
||||
await ctx.storage.submissions!.put(entryId, { formId, data, createdAt: new Date().toISOString() });
|
||||
const result = await ctx.storage.submissions!.query({
|
||||
where: { formId },
|
||||
orderBy: { createdAt: "desc" },
|
||||
limit: 50,
|
||||
});
|
||||
```
|
||||
|
||||
### Seeding Data (replaces starter content, theme setup)
|
||||
|
||||
WordPress plugins that call `wp_insert_term()`, `register_nav_menu()`, or insert default content on activation should use a seed file:
|
||||
|
||||
```json
|
||||
{
|
||||
"version": "1",
|
||||
"settings": { "title": "My Site", "tagline": "Welcome" },
|
||||
"taxonomies": [
|
||||
{
|
||||
"name": "category",
|
||||
"label": "Categories",
|
||||
"hierarchical": true,
|
||||
"collections": ["posts"],
|
||||
"terms": [
|
||||
{ "slug": "news", "label": "News" },
|
||||
{ "slug": "tutorials", "label": "Tutorials" }
|
||||
]
|
||||
}
|
||||
],
|
||||
"menus": [
|
||||
{
|
||||
"name": "primary",
|
||||
"label": "Primary Navigation",
|
||||
"items": [
|
||||
{ "type": "custom", "label": "Home", "url": "/" },
|
||||
{ "type": "page", "ref": "about", "collection": "pages" }
|
||||
]
|
||||
}
|
||||
],
|
||||
"redirects": [
|
||||
{ "source": "/?p=123", "destination": "/about" },
|
||||
{ "source": "/old-contact", "destination": "/contact", "type": 301 }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
```bash
|
||||
npx emdash seed .emdash/seed.json
|
||||
```
|
||||
|
||||
Use `redirects` for legacy WordPress URLs that still receive traffic after migration.
|
||||
|
||||
### Querying Content (replaces WP_Query)
|
||||
|
||||
```typescript
|
||||
// WordPress
|
||||
$query = new WP_Query(['post_type' => 'post', 'category_name' => 'tech', 'posts_per_page' => 10]);
|
||||
|
||||
// EmDash — in Astro component frontmatter
|
||||
import { getEmDashCollection, getEntryTerms } from "emdash";
|
||||
const { entries } = await getEmDashCollection("posts", {
|
||||
where: { category: "technology" },
|
||||
limit: 10,
|
||||
});
|
||||
```
|
||||
|
||||
### Menus (replaces wp_nav_menu)
|
||||
|
||||
```typescript
|
||||
// WordPress
|
||||
wp_nav_menu(['theme_location' => 'primary']);
|
||||
|
||||
// EmDash — in Astro component
|
||||
import { getMenu } from "emdash";
|
||||
const nav = await getMenu("primary");
|
||||
// nav.items[].label, nav.items[].url, nav.items[].children
|
||||
```
|
||||
|
||||
### Widget Areas (replaces dynamic_sidebar)
|
||||
|
||||
```typescript
|
||||
// WordPress
|
||||
dynamic_sidebar("sidebar-1");
|
||||
|
||||
// EmDash — in Astro component
|
||||
import { getWidgetArea } from "emdash";
|
||||
const sidebar = await getWidgetArea("sidebar");
|
||||
// sidebar.widgets[].type: "content" | "menu" | "component"
|
||||
```
|
||||
|
||||
## Red Flags (Need Human Decision)
|
||||
|
||||
Flag these for review — they may need architectural decisions:
|
||||
|
||||
1. **Deep WP integration** — Hooks into WP core features not in EmDash
|
||||
2. **Theme dependencies** — Assumes specific theme structure
|
||||
3. **Multisite features** — Not supported
|
||||
4. **Complex WP_Query** — Meta queries may need custom implementation
|
||||
5. **Direct SQL** — Schema differs, use Kysely or plugin storage
|
||||
6. **Session/transient abuse** — Needs proper caching layer
|
||||
7. **User capability checks** — Review role mapping (future)
|
||||
8. **ob_start() buffering** — PHP pattern, rethink for streaming
|
||||
9. **Cron jobs** — `wp_schedule_event()` has no direct equivalent; needs platform cron
|
||||
|
||||
## Output Format
|
||||
|
||||
When porting a plugin, provide:
|
||||
|
||||
1. **Analysis** — What the WP plugin does (concepts, not code)
|
||||
2. **Concept mapping** — Which WP concepts map to which EmDash features
|
||||
3. **Plugin code** — `src/descriptor.ts` and `src/index.ts` (use **creating-plugins** skill for structure)
|
||||
4. **Seed data** — If plugin needs default taxonomies/menus/widgets
|
||||
5. **Astro components** — For frontend output
|
||||
6. **Flags** — Anything needing human decision
|
||||
84
skills/wordpress-theme-to-emdash/SKILL.md
Normal file
84
skills/wordpress-theme-to-emdash/SKILL.md
Normal file
@@ -0,0 +1,84 @@
|
||||
---
|
||||
name: wordpress-theme-to-emdash
|
||||
description: Port WordPress themes to EmDash CMS. Use when asked to convert, migrate, or port a WordPress theme to EmDash, or when creating an EmDash site that should match an existing WordPress site's design. Handles design extraction, template conversion, and EmDash-specific features like menus, taxonomies, and widgets.
|
||||
---
|
||||
|
||||
# WordPress Theme to EmDash
|
||||
|
||||
Port WordPress themes to EmDash in six phases. **Read the phase file before starting each phase.**
|
||||
|
||||
## Critical Rules
|
||||
|
||||
1. **Copy scaffold first** - Start every theme by copying `scaffold/` from this skill
|
||||
2. **Take screenshots of demo** - Identify the demo URL and capture all page types using agent-browser before starting work
|
||||
3. **No hard-coded content** - Use `getSiteSettings()` for title/tagline, `getMenu()` for navigation
|
||||
4. **Server-rendered pages** - Never use `getStaticPaths()` for EmDash content
|
||||
5. **Astro 6** - Use `ClientRouter` not `ViewTransitions`, Zod 4 syntax, Node 22+
|
||||
6. **Use emdash Image component** - For all images, import Image from "emdash/ui"
|
||||
|
||||
## Phases
|
||||
|
||||
| Phase | File | Summary |
|
||||
| ----- | ----------------------- | ----------------------------------------------- |
|
||||
| 1 | `phases/1-discovery.md` | Download theme, screenshot demo, capture images |
|
||||
| 2 | `phases/2-design.md` | Extract CSS variables, fonts, colors |
|
||||
| 3 | `phases/3-templates.md` | Convert PHP templates to Astro |
|
||||
| 4 | `phases/4-dynamic.md` | Site settings, menus, taxonomies, widgets |
|
||||
| 5 | `phases/5-seed.md` | Create seed file with demo content |
|
||||
| 6 | `phases/6-verify.md` | Screenshot, compare, iterate, build |
|
||||
|
||||
## Checklist
|
||||
|
||||
### Setup
|
||||
|
||||
- [ ] Copy `scaffold/` to new theme directory. Unless otherwise specified by the user, make this a subdirectory of `themes/` and name it after the WordPress theme (e.g., `themes/twentytwentyfour/`).
|
||||
- [ ] Rename folder, update `package.json`
|
||||
- [ ] Verify build: `pnpm build`
|
||||
|
||||
### Phase 1: Discovery
|
||||
|
||||
- [ ] Theme source downloaded
|
||||
- [ ] Demo site identified
|
||||
- [ ] `discovery/` folder created with `screenshots/`, `images/`, `notes.md`
|
||||
- [ ] All page types screenshotted
|
||||
- [ ] Sample images downloaded
|
||||
|
||||
### Phase 2: Design
|
||||
|
||||
- [ ] CSS variables in `global.css`
|
||||
- [ ] Fonts loading
|
||||
- [ ] Colors match demo
|
||||
|
||||
### Phase 3: Templates
|
||||
|
||||
- [ ] Homepage, single post, archive, category, tag, page, 404
|
||||
- [ ] Components extracted (PostCard, etc.)
|
||||
|
||||
### Phase 4: Dynamic
|
||||
|
||||
- [ ] Site settings (title, tagline, logo from CMS)
|
||||
- [ ] Navigation menus (from CMS, not hard-coded)
|
||||
- [ ] Taxonomies
|
||||
- [ ] Widget areas (if applicable)
|
||||
|
||||
### Phase 5: Seed
|
||||
|
||||
- [ ] Seed file created with demo images
|
||||
- [ ] Validates: `emdash seed --validate`
|
||||
|
||||
### Phase 6: Verify
|
||||
|
||||
- [ ] Seed applied
|
||||
- [ ] Output screenshots captured
|
||||
- [ ] Visual comparison done
|
||||
- [ ] Build succeeds: `pnpm build`
|
||||
- [ ] LICENSE file downloaded (GPL-2.0 in most cases)
|
||||
- [ ] README credits original theme
|
||||
|
||||
## Reference Documents
|
||||
|
||||
- `references/astro-essentials.md` - Astro 6 patterns
|
||||
- `references/template-patterns.md` - PHP → Astro conversion
|
||||
- `references/concept-mapping.md` - WP → EmDash concepts
|
||||
- `references/emdash-api.md` - Full API reference
|
||||
- `references/design-extraction.md` - CSS extraction techniques
|
||||
149
skills/wordpress-theme-to-emdash/phases/1-discovery.md
Normal file
149
skills/wordpress-theme-to-emdash/phases/1-discovery.md
Normal file
@@ -0,0 +1,149 @@
|
||||
# Phase 1: Discovery & Reference Capture
|
||||
|
||||
Before writing any code, gather comprehensive reference materials from the demo site.
|
||||
|
||||
## 1.0 Create Discovery Folder
|
||||
|
||||
Create a `discovery/` folder in your theme directory to store all reference materials:
|
||||
|
||||
```
|
||||
discovery/
|
||||
├── screenshots/ # Reference screenshots from demo site
|
||||
│ ├── homepage.png
|
||||
│ ├── single-post.png
|
||||
│ ├── archive.png
|
||||
│ ├── category.png
|
||||
│ ├── page.png
|
||||
│ └── 404.png
|
||||
├── images/ # Sample images downloaded for seed content
|
||||
│ ├── featured-1.jpg
|
||||
│ ├── featured-2.jpg
|
||||
│ └── hero.jpg
|
||||
└── notes.md # Design decisions and observations
|
||||
```
|
||||
|
||||
The `notes.md` file should capture:
|
||||
|
||||
- Color values extracted from the demo
|
||||
- Font families and sizes observed
|
||||
- Layout patterns (header style, sidebar position, footer columns)
|
||||
- Special components or interactions to recreate
|
||||
- Anything that might be forgotten between sessions
|
||||
|
||||
## 1.1 Identify All Page Types
|
||||
|
||||
Identify the URL of the demo site for the WordPress theme you are converting. For wordpress.org themes, this is usually wp-themes.com/theme-name/. For other themes, use the "Live Preview" link. This may show it inside a frame; if so, ignore the frame and focus on the theme's actual content.
|
||||
|
||||
Use the agent-browser to explore the demo site to find every distinct page type:
|
||||
|
||||
- **Homepage** - Often has unique layout (hero, featured posts, etc.)
|
||||
- **Blog/Archive** - Post listing page
|
||||
- **Single Post** - Individual blog post with content
|
||||
- **Page** - Static page (About, Contact, etc.)
|
||||
- **Category/Tag Archive** - Taxonomy listing pages
|
||||
- **Search Results** - If the theme has custom search styling
|
||||
- **404 Page** - Error page styling
|
||||
|
||||
Use agent-browser to navigate the demo and discover pages:
|
||||
|
||||
```bash
|
||||
agent-browser open https://demo-site.com
|
||||
# Click around to find different page types
|
||||
# Check the navigation menu for page links
|
||||
# Look for "View all posts" or category links
|
||||
```
|
||||
|
||||
## 1.2 Screenshot All Page Types
|
||||
|
||||
Capture full-page screenshots of each page type to `discovery/screenshots/`:
|
||||
|
||||
```bash
|
||||
# Homepage
|
||||
agent-browser open https://demo-site.com
|
||||
agent-browser screenshot discovery/screenshots/homepage.png --full
|
||||
|
||||
# Single post (find a post with featured image and good content)
|
||||
agent-browser open https://demo-site.com/sample-post/
|
||||
agent-browser screenshot discovery/screenshots/single-post.png --full
|
||||
|
||||
# Blog archive
|
||||
agent-browser open https://demo-site.com/blog/
|
||||
agent-browser screenshot discovery/screenshots/archive.png --full
|
||||
|
||||
# Category page
|
||||
agent-browser open https://demo-site.com/category/news/
|
||||
agent-browser screenshot discovery/screenshots/category.png --full
|
||||
|
||||
# Static page
|
||||
agent-browser open https://demo-site.com/about/
|
||||
agent-browser screenshot discovery/screenshots/page.png --full
|
||||
|
||||
# 404 page
|
||||
agent-browser open https://demo-site.com/nonexistent-page-xyz/
|
||||
agent-browser screenshot discovery/screenshots/404.png --full
|
||||
```
|
||||
|
||||
## 1.3 Download Sample Images
|
||||
|
||||
If the theme is open source (GPL), download sample images from the demo to `discovery/images/`. This ensures visual consistency when comparing.
|
||||
|
||||
```bash
|
||||
# Find featured images in demo posts
|
||||
agent-browser eval "Array.from(document.querySelectorAll('article img')).map(i => i.src)"
|
||||
|
||||
# Download images for seed content
|
||||
curl -o discovery/images/featured-1.jpg "https://demo-site.com/wp-content/uploads/photo1.jpg"
|
||||
curl -o discovery/images/featured-2.jpg "https://demo-site.com/wp-content/uploads/photo2.jpg"
|
||||
```
|
||||
|
||||
For premium themes or when images aren't freely available, use Unsplash images that match the demo's visual style (same aspect ratios, similar subjects).
|
||||
|
||||
## 1.4 Document Page Structure
|
||||
|
||||
For each page type, document observations in `discovery/notes.md`:
|
||||
|
||||
- Header style (sticky? transparent? logo position?)
|
||||
- Sidebar presence and position
|
||||
- Footer layout (columns? widgets?)
|
||||
- Special components (hero sections, CTAs, etc.)
|
||||
- Color values (use browser DevTools color picker)
|
||||
- Font families and sizes
|
||||
- Spacing patterns
|
||||
|
||||
This inventory guides which templates and components you need to build, and preserves details that might be forgotten between sessions.
|
||||
|
||||
## Theme Source Discovery
|
||||
|
||||
### WordPress.org Themes
|
||||
|
||||
For themes on wordpress.org (e.g., `https://wordpress.org/themes/theme-name/`):
|
||||
|
||||
1. **Demo/Preview**: Click "Preview" button or visit `https://wp-themes.com/theme-name/`
|
||||
2. **Source Download**: The "Download" button provides a ZIP, or use:
|
||||
```bash
|
||||
curl -O https://downloads.wordpress.org/theme/theme-name.zip
|
||||
unzip theme-name.zip
|
||||
```
|
||||
3. **Theme Info**: The page includes author, version, tags, and description
|
||||
|
||||
### GitHub-Hosted Themes
|
||||
|
||||
1. **Source**: Clone or download the repository
|
||||
2. **Demo**: Check README for demo URL, or look for `Demo:` in theme description
|
||||
3. **Documentation**: Usually in README or `/docs` folder
|
||||
|
||||
### ThemeForest / Premium Themes
|
||||
|
||||
1. **Demo**: Use the "Live Preview" button on the product page
|
||||
2. **Source**: Requires purchase - ask the user to provide the unzipped theme files
|
||||
3. **Documentation**: Usually included in the download or linked from the product page
|
||||
|
||||
### Auto-Discovery
|
||||
|
||||
When given only a theme URL or name, derive URLs yourself:
|
||||
|
||||
1. Fetch the listing page to extract demo URL, download URL, and theme info
|
||||
2. Download the source (if freely available)
|
||||
3. Open the demo in agent-browser
|
||||
|
||||
Don't ask the user for URLs you can derive yourself.
|
||||
122
skills/wordpress-theme-to-emdash/phases/2-design.md
Normal file
122
skills/wordpress-theme-to-emdash/phases/2-design.md
Normal file
@@ -0,0 +1,122 @@
|
||||
# Phase 2: Design Extraction
|
||||
|
||||
Extract design tokens from the WordPress theme source and live demo.
|
||||
|
||||
## 2.1 Analyze the Live Site
|
||||
|
||||
Use `agent-browser` to extract computed styles:
|
||||
|
||||
```bash
|
||||
agent-browser eval "(() => {
|
||||
const body = getComputedStyle(document.body);
|
||||
const header = document.querySelector('header, .site-header');
|
||||
return JSON.stringify({
|
||||
body: {
|
||||
fontFamily: body.fontFamily,
|
||||
fontSize: body.fontSize,
|
||||
color: body.color,
|
||||
background: body.backgroundColor,
|
||||
},
|
||||
header: header ? {
|
||||
background: getComputedStyle(header).backgroundColor,
|
||||
height: getComputedStyle(header).height,
|
||||
} : null,
|
||||
}, null, 2);
|
||||
})()"
|
||||
```
|
||||
|
||||
## 2.2 Extract Design Tokens
|
||||
|
||||
Read the theme's CSS files. Look for:
|
||||
|
||||
```
|
||||
style.css # Main stylesheet (has theme header)
|
||||
assets/css/ # Additional stylesheets
|
||||
theme.json # Block themes (WP 5.9+) - structured design tokens
|
||||
```
|
||||
|
||||
### CSS Variable Mapping
|
||||
|
||||
| WP Pattern | EmDash Variable |
|
||||
| ---------------- | ------------------ |
|
||||
| Body font family | `--font-body` |
|
||||
| Heading font | `--font-heading` |
|
||||
| Primary color | `--color-primary` |
|
||||
| Background | `--color-base` |
|
||||
| Text color | `--color-contrast` |
|
||||
| Content width | `--content-width` |
|
||||
|
||||
### Block Theme (theme.json)
|
||||
|
||||
Block themes store design tokens in `theme.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"settings": {
|
||||
"color": {
|
||||
"palette": [{ "slug": "primary", "color": "#0073aa", "name": "Primary" }]
|
||||
},
|
||||
"typography": {
|
||||
"fontFamilies": [{ "fontFamily": "'Open Sans', sans-serif", "slug": "body" }]
|
||||
},
|
||||
"layout": {
|
||||
"contentSize": "650px",
|
||||
"wideSize": "1200px"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 2.3 Create Base Layout
|
||||
|
||||
Create `src/layouts/Base.astro` with:
|
||||
|
||||
- Extracted CSS variables in `:root`
|
||||
- Header/footer structure matching WP theme
|
||||
- Font loading (Google Fonts or local)
|
||||
- Responsive breakpoints
|
||||
|
||||
### CSS Variables Template
|
||||
|
||||
```css
|
||||
:root {
|
||||
/* Colors */
|
||||
--color-base: #ffffff;
|
||||
--color-contrast: #1a1a1a;
|
||||
--color-primary: #0073aa;
|
||||
--color-accent: #ff6b35;
|
||||
--color-muted: #6b7280;
|
||||
--color-border: #e5e7eb;
|
||||
|
||||
/* Typography */
|
||||
--font-body: system-ui, sans-serif;
|
||||
--font-heading: Georgia, serif;
|
||||
|
||||
/* Font sizes */
|
||||
--text-sm: 0.875rem;
|
||||
--text-base: 1rem;
|
||||
--text-lg: 1.125rem;
|
||||
--text-xl: 1.25rem;
|
||||
--text-2xl: 1.5rem;
|
||||
--text-3xl: 1.875rem;
|
||||
--text-4xl: 2.25rem;
|
||||
--text-5xl: clamp(2.5rem, 5vw, 3rem);
|
||||
|
||||
/* Spacing */
|
||||
--space-1: 0.25rem;
|
||||
--space-2: 0.5rem;
|
||||
--space-4: 1rem;
|
||||
--space-6: 1.5rem;
|
||||
--space-8: 2rem;
|
||||
--space-12: 3rem;
|
||||
--space-16: 4rem;
|
||||
--space-24: 6rem;
|
||||
|
||||
/* Layout */
|
||||
--content-width: 720px;
|
||||
--wide-width: 1200px;
|
||||
--header-height: 80px;
|
||||
}
|
||||
```
|
||||
|
||||
See `references/design-extraction.md` for detailed extraction techniques.
|
||||
114
skills/wordpress-theme-to-emdash/phases/3-templates.md
Normal file
114
skills/wordpress-theme-to-emdash/phases/3-templates.md
Normal file
@@ -0,0 +1,114 @@
|
||||
# Phase 3: Template Conversion
|
||||
|
||||
Convert WordPress PHP templates to Astro components.
|
||||
|
||||
## 3.1 Analyze Theme Structure
|
||||
|
||||
Read `functions.php` to identify:
|
||||
|
||||
- `register_nav_menu()` → EmDash menus
|
||||
- `register_sidebar()` → EmDash widget areas
|
||||
- `add_theme_support()` → Features (thumbnails, formats, etc.)
|
||||
- `register_post_type()` → Collections
|
||||
- `register_taxonomy()` → EmDash taxonomy defs
|
||||
- `add_shortcode()` → Portable Text blocks
|
||||
|
||||
## 3.2 Template Mapping
|
||||
|
||||
| WP Template | Astro Route |
|
||||
| -------------- | ----------------------------------- |
|
||||
| `index.php` | `src/pages/index.astro` |
|
||||
| `single.php` | `src/pages/posts/[slug].astro` |
|
||||
| `page.php` | `src/pages/pages/[slug].astro` |
|
||||
| `archive.php` | `src/pages/posts/index.astro` |
|
||||
| `category.php` | `src/pages/categories/[slug].astro` |
|
||||
| `tag.php` | `src/pages/tags/[slug].astro` |
|
||||
| `search.php` | `src/pages/search.astro` |
|
||||
| `404.php` | `src/pages/404.astro` |
|
||||
| `header.php` | Component in layout |
|
||||
| `footer.php` | Component in layout |
|
||||
|
||||
## 3.3 Convert Templates
|
||||
|
||||
### The Loop → getEmDashCollection
|
||||
|
||||
```php
|
||||
// WordPress
|
||||
<?php while (have_posts()) : the_post(); ?>
|
||||
<h2><?php the_title(); ?></h2>
|
||||
<?php endwhile; ?>
|
||||
```
|
||||
|
||||
```astro
|
||||
---
|
||||
// Astro/EmDash
|
||||
import { getEmDashCollection } from "emdash";
|
||||
const { entries: posts } = await getEmDashCollection("posts");
|
||||
---
|
||||
{posts.map(post => <h2>{post.data.title}</h2>)}
|
||||
```
|
||||
|
||||
### Single Post → getEmDashEntry
|
||||
|
||||
```php
|
||||
// WordPress
|
||||
<?php the_content(); ?>
|
||||
```
|
||||
|
||||
```astro
|
||||
---
|
||||
// Astro/EmDash
|
||||
import { getEmDashEntry } from "emdash";
|
||||
import { PortableText } from "emdash/ui";
|
||||
const { entry: post } = await getEmDashEntry("posts", Astro.params.slug);
|
||||
---
|
||||
{post && <PortableText value={post.data.content} />}
|
||||
```
|
||||
|
||||
## 3.4 Page Templates
|
||||
|
||||
WordPress themes often register page templates (Full Width, Sidebar, Landing Page, etc.). In EmDash, this is a `select` field on the pages collection:
|
||||
|
||||
1. Add a `template` select field to the pages collection with the theme's template names as options (e.g. "Default", "Full Width", "Landing Page")
|
||||
2. Create an Astro layout component for each template in `src/layouts/`
|
||||
3. Map the field value to a layout component in the page route:
|
||||
|
||||
```astro
|
||||
---
|
||||
// src/pages/pages/[slug].astro
|
||||
import { getEmDashEntry } from "emdash";
|
||||
import PageDefault from "../../layouts/PageDefault.astro";
|
||||
import PageFullWidth from "../../layouts/PageFullWidth.astro";
|
||||
|
||||
const { slug } = Astro.params;
|
||||
const { entry: page } = await getEmDashEntry("pages", slug!);
|
||||
if (!page) return Astro.redirect("/404");
|
||||
|
||||
const layouts = {
|
||||
"Default": PageDefault,
|
||||
"Full Width": PageFullWidth,
|
||||
};
|
||||
const Layout = layouts[page.data.template as keyof typeof layouts] ?? PageDefault;
|
||||
---
|
||||
<Layout page={page} />
|
||||
```
|
||||
|
||||
Use human-readable option names (matching what the WP theme displayed) since these appear in the admin dropdown.
|
||||
|
||||
## Important: Server-Rendered Pages
|
||||
|
||||
**Never use `getStaticPaths()` or `export const prerender = true` for EmDash content pages.** Content changes at runtime, so pages must be server-rendered.
|
||||
|
||||
```astro
|
||||
---
|
||||
// CORRECT - server-rendered
|
||||
const { slug } = Astro.params;
|
||||
const { entry: post } = await getEmDashEntry("posts", slug!);
|
||||
|
||||
if (!post) {
|
||||
return Astro.redirect("/404");
|
||||
}
|
||||
---
|
||||
```
|
||||
|
||||
See `references/template-patterns.md` for more conversion patterns.
|
||||
147
skills/wordpress-theme-to-emdash/phases/4-dynamic.md
Normal file
147
skills/wordpress-theme-to-emdash/phases/4-dynamic.md
Normal file
@@ -0,0 +1,147 @@
|
||||
# Phase 4: Dynamic Features
|
||||
|
||||
Implement CMS-driven features: site settings, menus, taxonomies, and widgets.
|
||||
|
||||
## 4.1 Site Settings
|
||||
|
||||
Map WordPress customizer values to EmDash site settings:
|
||||
|
||||
| WP Customizer Setting | EmDash Site Setting |
|
||||
| --------------------- | --------------------- |
|
||||
| Site Title | `title` |
|
||||
| Tagline | `tagline` |
|
||||
| Site Icon | `favicon` |
|
||||
| Custom Logo | `logo` |
|
||||
| Posts per page | `postsPerPage` |
|
||||
| Date format | `dateFormat` |
|
||||
|
||||
```astro
|
||||
---
|
||||
import { getSiteSettings } from "emdash";
|
||||
const settings = await getSiteSettings();
|
||||
---
|
||||
<header>
|
||||
{settings.logo ? (
|
||||
<img src={settings.logo.url} alt={settings.title} />
|
||||
) : (
|
||||
<span class="site-title">{settings.title}</span>
|
||||
)}
|
||||
{settings.tagline && <p class="tagline">{settings.tagline}</p>}
|
||||
</header>
|
||||
```
|
||||
|
||||
## 4.2 Navigation Menus
|
||||
|
||||
Identify menus in `functions.php`:
|
||||
|
||||
```php
|
||||
register_nav_menus([
|
||||
'primary' => 'Primary Navigation',
|
||||
'footer' => 'Footer Links',
|
||||
]);
|
||||
```
|
||||
|
||||
Use in templates:
|
||||
|
||||
```astro
|
||||
---
|
||||
import { getMenu } from "emdash";
|
||||
const primaryNav = await getMenu("primary");
|
||||
---
|
||||
<nav class="primary-nav">
|
||||
{primaryNav && (
|
||||
<ul>
|
||||
{primaryNav.items.map(item => (
|
||||
<li>
|
||||
<a href={item.url} aria-current={Astro.url.pathname === item.url ? 'page' : undefined}>
|
||||
{item.label}
|
||||
</a>
|
||||
{item.children.length > 0 && (
|
||||
<ul class="submenu">
|
||||
{item.children.map(child => (
|
||||
<li><a href={child.url}>{child.label}</a></li>
|
||||
))}
|
||||
</ul>
|
||||
)}
|
||||
</li>
|
||||
))}
|
||||
</ul>
|
||||
)}
|
||||
</nav>
|
||||
```
|
||||
|
||||
## 4.3 Taxonomies
|
||||
|
||||
Identify taxonomies in theme:
|
||||
|
||||
```php
|
||||
register_taxonomy('genre', 'book', [
|
||||
'label' => 'Genres',
|
||||
'hierarchical' => true,
|
||||
]);
|
||||
```
|
||||
|
||||
Use in templates:
|
||||
|
||||
```astro
|
||||
---
|
||||
import { getTaxonomyTerms, getEntryTerms, getEntriesByTerm } from "emdash";
|
||||
|
||||
// Get all terms
|
||||
const genres = await getTaxonomyTerms("genre");
|
||||
|
||||
// Get terms for a specific entry
|
||||
const bookGenres = await getEntryTerms("books", book.id, "genre");
|
||||
|
||||
// Get entries by term
|
||||
const fictionBooks = await getEntriesByTerm("books", "genre", "fiction");
|
||||
---
|
||||
```
|
||||
|
||||
## 4.4 Widget Areas
|
||||
|
||||
Identify sidebars in theme:
|
||||
|
||||
```php
|
||||
register_sidebar([
|
||||
'name' => 'Main Sidebar',
|
||||
'id' => 'sidebar-1',
|
||||
]);
|
||||
```
|
||||
|
||||
Use in templates:
|
||||
|
||||
```astro
|
||||
---
|
||||
import { getWidgetArea } from "emdash";
|
||||
import { PortableText } from "emdash/ui";
|
||||
|
||||
const sidebar = await getWidgetArea("sidebar");
|
||||
---
|
||||
{sidebar && sidebar.widgets.length > 0 && (
|
||||
<aside class="sidebar">
|
||||
{sidebar.widgets.map(widget => (
|
||||
<div class="widget">
|
||||
{widget.title && <h3>{widget.title}</h3>}
|
||||
{widget.type === "content" && <PortableText value={widget.content} />}
|
||||
</div>
|
||||
))}
|
||||
</aside>
|
||||
)}
|
||||
```
|
||||
|
||||
## 4.5 Widget Components
|
||||
|
||||
Map WP widgets to Astro components:
|
||||
|
||||
| WP Widget | EmDash Component |
|
||||
| ---------------- | ------------------- |
|
||||
| Recent Posts | `core:recent-posts` |
|
||||
| Categories | `core:categories` |
|
||||
| Tag Cloud | `core:tags` |
|
||||
| Search | `core:search` |
|
||||
| Archives | `core:archives` |
|
||||
| Text/Custom HTML | `type: 'content'` |
|
||||
| Navigation Menu | `type: 'menu'` |
|
||||
|
||||
See `references/emdash-api.md` for full API reference.
|
||||
206
skills/wordpress-theme-to-emdash/phases/5-seed.md
Normal file
206
skills/wordpress-theme-to-emdash/phases/5-seed.md
Normal file
@@ -0,0 +1,206 @@
|
||||
# Phase 5: Create Seed File
|
||||
|
||||
Combine all theme features into a seed file with sample content.
|
||||
|
||||
## 5.1 Image Strategy
|
||||
|
||||
**Use the same images you downloaded in Phase 1** for visual consistency.
|
||||
|
||||
1. **Open source themes (GPL)**: Use exact images from the demo
|
||||
2. **Premium themes**: Use Unsplash images matching the demo's style
|
||||
3. **Local images**: Reference with `file:./` prefix:
|
||||
```json
|
||||
"featured_image": {
|
||||
"$media": {
|
||||
"url": "file:./discovery/images/hero.jpg",
|
||||
"alt": "Hero image"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 5.2 Validate Before Applying
|
||||
|
||||
```bash
|
||||
# Validate without applying
|
||||
emdash seed --validate
|
||||
```
|
||||
|
||||
The validator catches common mistakes:
|
||||
|
||||
| Check | Error |
|
||||
| ---------------------------- | ------------------------- |
|
||||
| Image using raw URL | "must use $media syntax" |
|
||||
| Reference using raw ID | "must use $ref:id syntax" |
|
||||
| PortableText not an array | "expected array" |
|
||||
| PortableText missing `_type` | "missing required \_type" |
|
||||
|
||||
### Common Fixes
|
||||
|
||||
```json
|
||||
// WRONG - raw URL
|
||||
"featured_image": "https://example.com/photo.jpg"
|
||||
|
||||
// CORRECT - $media syntax
|
||||
"featured_image": {
|
||||
"$media": {
|
||||
"url": "https://example.com/photo.jpg",
|
||||
"alt": "Description"
|
||||
}
|
||||
}
|
||||
|
||||
// WRONG - unknown byline reference
|
||||
"bylines": [{ "byline": "author-1" }]
|
||||
|
||||
// CORRECT - define root bylines[] and reference byline IDs
|
||||
"bylines": [{ "byline": "byline-author-1" }]
|
||||
```
|
||||
|
||||
## 5.3 Seed File Structure
|
||||
|
||||
```json
|
||||
{
|
||||
"$schema": "https://emdashcms.com/seed.schema.json",
|
||||
"version": "1",
|
||||
"meta": {
|
||||
"name": "Theme Name",
|
||||
"description": "Ported from WordPress theme"
|
||||
},
|
||||
|
||||
"settings": {
|
||||
"title": "Site Title",
|
||||
"tagline": "Site tagline"
|
||||
},
|
||||
|
||||
"collections": [
|
||||
{
|
||||
"slug": "posts",
|
||||
"label": "Posts",
|
||||
"fields": [
|
||||
{ "slug": "title", "type": "string", "required": true },
|
||||
{ "slug": "content", "type": "portableText" },
|
||||
{ "slug": "featured_image", "type": "image" }
|
||||
]
|
||||
}
|
||||
],
|
||||
|
||||
"taxonomies": [
|
||||
{
|
||||
"name": "categories",
|
||||
"label": "Categories",
|
||||
"hierarchical": true,
|
||||
"collections": ["posts"],
|
||||
"terms": [{ "slug": "news", "label": "News" }]
|
||||
}
|
||||
],
|
||||
|
||||
"bylines": [
|
||||
{
|
||||
"id": "byline-author-1",
|
||||
"slug": "theme-author",
|
||||
"displayName": "Theme Author"
|
||||
}
|
||||
],
|
||||
|
||||
"menus": [
|
||||
{
|
||||
"name": "primary",
|
||||
"label": "Primary Navigation",
|
||||
"items": [
|
||||
{ "type": "custom", "label": "Home", "url": "/" },
|
||||
{ "type": "custom", "label": "Blog", "url": "/posts" }
|
||||
]
|
||||
}
|
||||
],
|
||||
|
||||
"content": {
|
||||
"posts": [
|
||||
{
|
||||
"id": "post-1",
|
||||
"slug": "hello-world",
|
||||
"status": "published",
|
||||
"bylines": [{ "byline": "byline-author-1" }],
|
||||
"data": {
|
||||
"title": "Hello World",
|
||||
"content": [{ "_type": "block", "children": [{ "text": "Welcome!" }] }],
|
||||
"featured_image": {
|
||||
"$media": {
|
||||
"url": "file:./discovery/images/featured-1.jpg",
|
||||
"alt": "Featured image"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 5.4 Adding Sections (Reusable Blocks)
|
||||
|
||||
If the theme has reusable block patterns, add them as sections:
|
||||
|
||||
```json
|
||||
{
|
||||
"sections": [
|
||||
{
|
||||
"slug": "hero-centered",
|
||||
"title": "Centered Hero",
|
||||
"description": "Full-width hero with centered heading and CTA button",
|
||||
"keywords": ["hero", "banner", "header", "landing"],
|
||||
"content": [
|
||||
{
|
||||
"_type": "block",
|
||||
"style": "h1",
|
||||
"children": [{ "_type": "span", "text": "Welcome to Our Site" }]
|
||||
},
|
||||
{
|
||||
"_type": "block",
|
||||
"children": [{ "_type": "span", "text": "Your compelling tagline goes here." }]
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"slug": "newsletter-cta",
|
||||
"title": "Newsletter Signup",
|
||||
"keywords": ["newsletter", "subscribe", "email", "signup"],
|
||||
"content": [
|
||||
{
|
||||
"_type": "block",
|
||||
"style": "h3",
|
||||
"children": [{ "_type": "span", "text": "Subscribe to our newsletter" }]
|
||||
},
|
||||
{
|
||||
"_type": "block",
|
||||
"children": [
|
||||
{ "_type": "span", "text": "Get the latest updates delivered to your inbox." }
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Editors can insert these sections using the `/section` slash command in the rich text editor.
|
||||
|
||||
## 5.5 Add Redirects for Legacy WordPress URLs
|
||||
|
||||
Include redirects in the seed when the WordPress theme used different URL structures.
|
||||
|
||||
```json
|
||||
{
|
||||
"redirects": [
|
||||
{ "source": "/?p=123", "destination": "/hello-world" },
|
||||
{ "source": "/2024/01/hello-world", "destination": "/hello-world", "type": 301 },
|
||||
{ "source": "/category/news", "destination": "/categories/news" }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Rules:
|
||||
|
||||
- `source` and `destination` must be local paths (start with `/`)
|
||||
- Supported `type` values are `301`, `302`, `307`, `308`
|
||||
- Redirects are idempotent during seeding (existing `source` entries are skipped)
|
||||
|
||||
See `references/emdash-api.md` for full seed file schema.
|
||||
97
skills/wordpress-theme-to-emdash/phases/6-verify.md
Normal file
97
skills/wordpress-theme-to-emdash/phases/6-verify.md
Normal file
@@ -0,0 +1,97 @@
|
||||
# Phase 6: Verify & Iterate
|
||||
|
||||
Seed content, run the dev server, compare screenshots, and iterate until pages match.
|
||||
|
||||
## 6.1 Apply the Seed
|
||||
|
||||
```bash
|
||||
# Validate first
|
||||
emdash seed --validate
|
||||
|
||||
# Apply seed with content
|
||||
emdash seed
|
||||
```
|
||||
|
||||
## 6.2 Start Dev Server
|
||||
|
||||
Kill any existing server first:
|
||||
|
||||
```bash
|
||||
lsof -ti:4321 | xargs kill -9 2>/dev/null || true
|
||||
pnpm dev
|
||||
```
|
||||
|
||||
## 6.3 Screenshot Each Page Type
|
||||
|
||||
Screenshot every page type you captured in Phase 1:
|
||||
|
||||
```bash
|
||||
# Homepage
|
||||
agent-browser open http://localhost:4321
|
||||
agent-browser screenshot output/homepage.png --full
|
||||
|
||||
# Single post
|
||||
agent-browser open http://localhost:4321/posts/hello-world
|
||||
agent-browser screenshot output/single-post.png --full
|
||||
|
||||
# Blog archive
|
||||
agent-browser open http://localhost:4321/posts
|
||||
agent-browser screenshot output/archive.png --full
|
||||
|
||||
# Category page
|
||||
agent-browser open http://localhost:4321/categories/news
|
||||
agent-browser screenshot output/category.png --full
|
||||
|
||||
# Static page
|
||||
agent-browser open http://localhost:4321/pages/about
|
||||
agent-browser screenshot output/page.png --full
|
||||
|
||||
# 404 page
|
||||
agent-browser open http://localhost:4321/nonexistent
|
||||
agent-browser screenshot output/404.png --full
|
||||
```
|
||||
|
||||
## 6.4 Compare & Iterate
|
||||
|
||||
Compare each screenshot pair:
|
||||
|
||||
| Page Type | Reference | Output |
|
||||
| ----------- | --------------------------------------- | ------------------------ |
|
||||
| Homepage | `discovery/screenshots/homepage.png` | `output/homepage.png` |
|
||||
| Single Post | `discovery/screenshots/single-post.png` | `output/single-post.png` |
|
||||
| Archive | `discovery/screenshots/archive.png` | `output/archive.png` |
|
||||
| Category | `discovery/screenshots/category.png` | `output/category.png` |
|
||||
| Page | `discovery/screenshots/page.png` | `output/page.png` |
|
||||
| 404 | `discovery/screenshots/404.png` | `output/404.png` |
|
||||
|
||||
For each page, identify differences and fix:
|
||||
|
||||
1. **Layout** - CSS grid/flexbox, content width, spacing
|
||||
2. **Typography** - Font family, sizes, line height
|
||||
3. **Colors** - Background, text, links, borders
|
||||
4. **Components** - Headers, footers, cards, buttons
|
||||
5. **Responsive** - Check mobile viewport too
|
||||
|
||||
Re-screenshot after each round of fixes.
|
||||
|
||||
**Don't aim for pixel-perfect** - aim for "same design language."
|
||||
|
||||
## 6.5 Final Build Test
|
||||
|
||||
```bash
|
||||
pnpm run build
|
||||
```
|
||||
|
||||
## License Compliance
|
||||
|
||||
WordPress themes are GPL-licensed. Every ported theme needs:
|
||||
|
||||
1. **LICENSE** - GPL-2.0 text (download with curl, don't output directly):
|
||||
|
||||
```bash
|
||||
curl -o LICENSE https://raw.githubusercontent.com/spdx/license-list-data/main/text/GPL-2.0-or-later.txt
|
||||
```
|
||||
|
||||
2. **README.md** - Credits to original theme
|
||||
|
||||
3. **package.json** - `"license": "GPL-2.0-or-later"`
|
||||
1136
skills/wordpress-theme-to-emdash/references/astro-essentials.md
Normal file
1136
skills/wordpress-theme-to-emdash/references/astro-essentials.md
Normal file
File diff suppressed because it is too large
Load Diff
410
skills/wordpress-theme-to-emdash/references/concept-mapping.md
Normal file
410
skills/wordpress-theme-to-emdash/references/concept-mapping.md
Normal file
@@ -0,0 +1,410 @@
|
||||
# WP Theme → EmDash Concept Mapping
|
||||
|
||||
## Template Hierarchy
|
||||
|
||||
| WP Template | Purpose | EmDash Equivalent |
|
||||
| ------------------------- | ----------------------- | ------------------------------------------------------- |
|
||||
| `index.php` | Fallback for everything | `src/pages/index.astro` |
|
||||
| `front-page.php` | Static front page | `src/pages/index.astro` |
|
||||
| `home.php` | Blog posts page | `src/pages/index.astro` or `src/pages/blog/index.astro` |
|
||||
| `single.php` | Single post | `src/pages/posts/[slug].astro` |
|
||||
| `single-{post_type}.php` | Custom post type single | `src/pages/{type}/[slug].astro` |
|
||||
| `page.php` | Single page | `src/pages/pages/[slug].astro` |
|
||||
| `page-{slug}.php` | Specific page template | `src/pages/pages/{slug}.astro` (static) |
|
||||
| `archive.php` | Post archives | `src/pages/posts/index.astro` |
|
||||
| `archive-{post_type}.php` | CPT archive | `src/pages/{type}/index.astro` |
|
||||
| `category.php` | Category archive | `src/pages/categories/[slug].astro` |
|
||||
| `tag.php` | Tag archive | `src/pages/tags/[slug].astro` |
|
||||
| `author.php` | Author archive | `src/pages/authors/[slug].astro` |
|
||||
| `date.php` | Date archive | `src/pages/archive/[year]/[month].astro` |
|
||||
| `search.php` | Search results | `src/pages/search.astro` (use `search()` API) |
|
||||
| `404.php` | Not found | `src/pages/404.astro` |
|
||||
| `header.php` | Site header | Part of `src/layouts/Base.astro` |
|
||||
| `footer.php` | Site footer | Part of `src/layouts/Base.astro` |
|
||||
| `sidebar.php` | Sidebar widget area | Component: `src/components/Sidebar.astro` |
|
||||
| `comments.php` | Comments template | Component or third-party (Giscus, etc.) |
|
||||
|
||||
## Template Parts
|
||||
|
||||
| WP Pattern | EmDash Pattern |
|
||||
| ---------------------------------------------------------- | ---------------------------- |
|
||||
| `get_template_part('content', 'post')` | `<PostCard />` component |
|
||||
| `get_template_part('template-parts/header/site-branding')` | `<SiteBranding />` component |
|
||||
| `template-parts/` directory | `src/components/` directory |
|
||||
|
||||
## Functions.php Registrations
|
||||
|
||||
### Navigation Menus
|
||||
|
||||
```php
|
||||
// WordPress
|
||||
register_nav_menus([
|
||||
'primary' => 'Primary Menu',
|
||||
'footer' => 'Footer Menu',
|
||||
]);
|
||||
```
|
||||
|
||||
EmDash has first-class menu support with automatic URL resolution:
|
||||
|
||||
```typescript
|
||||
import { getMenu } from "emdash";
|
||||
|
||||
const primaryMenu = await getMenu("primary");
|
||||
// Returns { id, name, label, items: MenuItem[] }
|
||||
// Items have resolved URLs and support nesting
|
||||
```
|
||||
|
||||
Menus are created via:
|
||||
|
||||
- Admin UI
|
||||
- Seed files (JSON)
|
||||
- WordPress import (automatic migration)
|
||||
|
||||
### Sidebars/Widget Areas
|
||||
|
||||
```php
|
||||
// WordPress
|
||||
register_sidebar([
|
||||
'name' => 'Main Sidebar',
|
||||
'id' => 'sidebar-1',
|
||||
]);
|
||||
```
|
||||
|
||||
EmDash has first-class widget area support:
|
||||
|
||||
```typescript
|
||||
import { getWidgetArea } from "emdash";
|
||||
|
||||
const sidebar = await getWidgetArea("sidebar");
|
||||
// Returns { id, name, label, widgets: Widget[] }
|
||||
// Widgets can be content (Portable Text), menu, or component
|
||||
```
|
||||
|
||||
Widget areas are created via:
|
||||
|
||||
- Admin UI
|
||||
- Seed files (JSON)
|
||||
- WordPress import (automatic migration)
|
||||
|
||||
### Theme Support
|
||||
|
||||
```php
|
||||
// WordPress
|
||||
add_theme_support('post-thumbnails');
|
||||
add_theme_support('title-tag');
|
||||
add_theme_support('custom-logo');
|
||||
add_theme_support('post-formats');
|
||||
```
|
||||
|
||||
EmDash equivalents:
|
||||
|
||||
- `post-thumbnails` → `featured_image` field on collections (automatic)
|
||||
- `title-tag` → Astro handles `<title>` in layout
|
||||
- `custom-logo` → `getSiteSetting("logo")` returns `{ mediaId, alt, url }`
|
||||
- `post-formats` → Field on collection (select type)
|
||||
|
||||
### Custom Post Types
|
||||
|
||||
```php
|
||||
// WordPress
|
||||
register_post_type('portfolio', [...]);
|
||||
```
|
||||
|
||||
EmDash: Create collection via admin UI or API. The collection will be created during content import if it doesn't exist.
|
||||
|
||||
## Template Tags → EmDash
|
||||
|
||||
### Content Retrieval
|
||||
|
||||
| WP Function | EmDash Equivalent |
|
||||
| ----------------------------- | ------------------------------------------------- |
|
||||
| `have_posts()` / `the_post()` | `getEmDashCollection()` |
|
||||
| `get_post()` | `getEmDashEntry()` |
|
||||
| `the_title()` | `post.data.title` |
|
||||
| `the_content()` | `<PortableText value={post.data.content} />` |
|
||||
| `the_excerpt()` | `post.data.excerpt` |
|
||||
| `the_permalink()` | `/posts/${post.id}` or `/posts/${post.data.slug}` |
|
||||
| `the_post_thumbnail()` | `post.data.featured_image` |
|
||||
| `get_the_date()` | `post.data.publishedAt` |
|
||||
| `get_the_author()` | `post.data.byline?.displayName` |
|
||||
| `get_the_category()` | `getEntryTerms(coll, id, "categories")` |
|
||||
| `get_the_tags()` | `getEntryTerms(coll, id, "tags")` |
|
||||
|
||||
### Taxonomies
|
||||
|
||||
| WP Function | EmDash Equivalent |
|
||||
| ---------------------------- | -------------------------------------------------- |
|
||||
| `get_categories()` | `getTaxonomyTerms("categories")` |
|
||||
| `get_tags()` | `getTaxonomyTerms("tags")` |
|
||||
| `get_terms($taxonomy)` | `getTaxonomyTerms(taxonomy)` |
|
||||
| `get_term($id, $taxonomy)` | `getTerm(taxonomy, slug)` |
|
||||
| `get_term_by('slug', ...)` | `getTerm(taxonomy, slug)` |
|
||||
| `get_the_terms($post, $tax)` | `getEntryTerms(collection, entryId, taxonomy)` |
|
||||
| `wp_get_post_categories()` | `getEntryTerms(collection, entryId, "categories")` |
|
||||
| `wp_get_post_tags()` | `getEntryTerms(collection, entryId, "tags")` |
|
||||
| `get_category_link($cat)` | `/categories/${term.slug}` |
|
||||
| `get_tag_link($tag)` | `/tags/${term.slug}` |
|
||||
|
||||
EmDash supports hierarchical taxonomies (like categories) and flat taxonomies (like tags):
|
||||
|
||||
### Site Info
|
||||
|
||||
| WP Function | EmDash Equivalent |
|
||||
| ------------------------- | --------------------------------------- |
|
||||
| `bloginfo('name')` | `getSiteSetting("title")` |
|
||||
| `bloginfo('description')` | `getSiteSetting("tagline")` |
|
||||
| `home_url()` | `Astro.site` or `import.meta.env.SITE` |
|
||||
| `get_theme_mod()` | `getSiteSetting(key)` or plugin storage |
|
||||
| `get_option()` | `getSiteSetting(key)` or plugin storage |
|
||||
| `get_custom_logo()` | `getSiteSetting("logo")` returns URL |
|
||||
|
||||
### Conditional Tags
|
||||
|
||||
| WP Function | Astro Equivalent |
|
||||
| ----------------- | ---------------------------------- |
|
||||
| `is_home()` | `Astro.url.pathname === '/'` |
|
||||
| `is_front_page()` | `Astro.url.pathname === '/'` |
|
||||
| `is_single()` | Check route pattern |
|
||||
| `is_page()` | Check route pattern |
|
||||
| `is_archive()` | Check route pattern |
|
||||
| `is_category()` | Check route pattern |
|
||||
| `is_search()` | `Astro.url.pathname === '/search'` |
|
||||
| `is_404()` | N/A (404.astro handles this) |
|
||||
|
||||
### Media
|
||||
|
||||
| WP Function | EmDash Equivalent |
|
||||
| --------------------------- | -------------------------- |
|
||||
| `wp_get_attachment_image()` | `<img src={media.url} />` |
|
||||
| `wp_get_attachment_url()` | `media.url` |
|
||||
| `the_post_thumbnail()` | `post.data.featured_image` |
|
||||
|
||||
### Navigation
|
||||
|
||||
| WP Function | EmDash Equivalent |
|
||||
| ------------------------ | ------------------------------------- |
|
||||
| `wp_nav_menu()` | `getMenu("menu-name")` + render items |
|
||||
| `wp_list_pages()` | Query pages collection or use menu |
|
||||
| `the_posts_navigation()` | Custom pagination component |
|
||||
| `the_posts_pagination()` | Custom pagination component |
|
||||
| `get_nav_menu_items()` | `getMenu("name").items` |
|
||||
|
||||
## Hooks → EmDash Events
|
||||
|
||||
WordPress hooks don't have direct equivalents. Most hook functionality becomes:
|
||||
|
||||
1. **Astro middleware** - For request/response modification
|
||||
2. **EmDash plugin hooks** - For content lifecycle events
|
||||
3. **Build-time logic** - In Astro config or components
|
||||
|
||||
| WP Hook | EmDash Approach |
|
||||
| -------------------- | ------------------------------------------ |
|
||||
| `wp_head` | Add to `<head>` in layout |
|
||||
| `wp_footer` | Add before `</body>` in layout |
|
||||
| `the_content` filter | PortableText components |
|
||||
| `pre_get_posts` | Query filters in `getEmDashCollection()` |
|
||||
| `save_post` | EmDash plugin hook: `content:beforeSave` |
|
||||
|
||||
## Asset Enqueueing
|
||||
|
||||
```php
|
||||
// WordPress
|
||||
wp_enqueue_style('theme-style', get_stylesheet_uri());
|
||||
wp_enqueue_script('theme-script', get_template_directory_uri() . '/js/main.js');
|
||||
```
|
||||
|
||||
Astro:
|
||||
|
||||
```astro
|
||||
---
|
||||
// In layout or component
|
||||
import '../styles/main.css';
|
||||
import '../scripts/main.js';
|
||||
---
|
||||
<link rel="stylesheet" href="/styles/main.css" />
|
||||
<script src="/scripts/main.js"></script>
|
||||
```
|
||||
|
||||
Or use Astro's built-in bundling:
|
||||
|
||||
```astro
|
||||
<style>
|
||||
/* Scoped styles */
|
||||
</style>
|
||||
<script>
|
||||
// Client-side JS
|
||||
</script>
|
||||
```
|
||||
|
||||
## Shortcodes → Portable Text Blocks
|
||||
|
||||
```php
|
||||
// WordPress shortcode
|
||||
add_shortcode('gallery', function($atts) {
|
||||
return '<div class="gallery">...</div>';
|
||||
});
|
||||
// Usage: [gallery ids="1,2,3"]
|
||||
```
|
||||
|
||||
EmDash: Custom Portable Text block type + component:
|
||||
|
||||
```astro
|
||||
---
|
||||
// GalleryBlock.astro
|
||||
const { ids } = Astro.props;
|
||||
---
|
||||
<div class="gallery">
|
||||
<!-- Render images -->
|
||||
</div>
|
||||
```
|
||||
|
||||
```astro
|
||||
<PortableText
|
||||
value={content}
|
||||
components={{ gallery: GalleryBlock }}
|
||||
/>
|
||||
```
|
||||
|
||||
## Widgets → Widget Areas
|
||||
|
||||
EmDash has first-class widget support with `getWidgetArea()`:
|
||||
|
||||
```typescript
|
||||
import { getWidgetArea } from "emdash";
|
||||
|
||||
const sidebar = await getWidgetArea("sidebar");
|
||||
sidebar?.widgets.forEach((widget) => {
|
||||
// widget.type: "content" | "menu" | "component"
|
||||
});
|
||||
```
|
||||
|
||||
### Widget Types
|
||||
|
||||
| WP Widget | EmDash Widget Type | Notes |
|
||||
| ------------ | ------------------------------- | ----------------------------- |
|
||||
| Text/HTML | `content` | Portable Text (rich content) |
|
||||
| Custom Menu | `menu` | References menu by name |
|
||||
| Recent Posts | `component` `core:recent-posts` | Built-in component with props |
|
||||
| Categories | `component` `core:categories` | Built-in component |
|
||||
| Tag Cloud | `component` `core:tag-cloud` | Built-in component |
|
||||
| Search | `<LiveSearch />` component | Use `emdash/ui` LiveSearch |
|
||||
| Archives | `component` `core:archives` | Built-in component |
|
||||
|
||||
### Core Widget Components
|
||||
|
||||
| Component ID | Props |
|
||||
| ------------------- | ------------------------ |
|
||||
| `core:recent-posts` | `limit`, `collection` |
|
||||
| `core:categories` | `taxonomy`, `showCounts` |
|
||||
| `core:tag-cloud` | `taxonomy`, `limit` |
|
||||
| `core:search` | `placeholder` |
|
||||
| `core:archives` | `collection`, `format` |
|
||||
|
||||
## Search
|
||||
|
||||
WordPress search maps to EmDash's FTS5-based search system:
|
||||
|
||||
```php
|
||||
// WordPress search form
|
||||
get_search_form();
|
||||
|
||||
// WordPress search query
|
||||
$results = new WP_Query(['s' => 'hello world']);
|
||||
```
|
||||
|
||||
EmDash:
|
||||
|
||||
```typescript
|
||||
import { search } from "emdash";
|
||||
import LiveSearch from "emdash/ui/search";
|
||||
|
||||
// Programmatic search
|
||||
const results = await search("hello world", {
|
||||
collections: ["posts", "pages"],
|
||||
limit: 20,
|
||||
});
|
||||
|
||||
// Or use the LiveSearch component
|
||||
<LiveSearch placeholder="Search..." />
|
||||
```
|
||||
|
||||
### Search Page Pattern
|
||||
|
||||
```astro
|
||||
---
|
||||
// src/pages/search.astro
|
||||
import { search } from "emdash";
|
||||
import Base from "../layouts/Base.astro";
|
||||
|
||||
const query = Astro.url.searchParams.get("q") || "";
|
||||
const results = query ? await search(query, { limit: 20 }) : { results: [] };
|
||||
---
|
||||
<Base title={`Search: ${query}`}>
|
||||
<h1>Search Results for "{query}"</h1>
|
||||
{results.results.length === 0 ? (
|
||||
<p>No results found.</p>
|
||||
) : (
|
||||
<ul>
|
||||
{results.results.map(r => (
|
||||
<li>
|
||||
<a href={`/${r.collection}/${r.slug}`}>{r.title}</a>
|
||||
<p set:html={r.snippet} />
|
||||
</li>
|
||||
))}
|
||||
</ul>
|
||||
)}
|
||||
</Base>
|
||||
```
|
||||
|
||||
### Search Features
|
||||
|
||||
| WordPress | EmDash |
|
||||
| ---------------------------- | ------------------------------- |
|
||||
| Basic keyword search | FTS5 with Porter stemming |
|
||||
| Search all public post types | Per-collection search enable |
|
||||
| `s` query parameter | `q` query parameter |
|
||||
| Relevance sorting | BM25 ranking with field weights |
|
||||
| Search widget | `<LiveSearch />` component |
|
||||
|
||||
**Note:** Search must be enabled per-collection in admin. Mark fields as "Searchable" to include them in the index.
|
||||
|
||||
## Reusable Blocks → Sections
|
||||
|
||||
WordPress reusable blocks (`wp_block` post type) map to EmDash sections:
|
||||
|
||||
```php
|
||||
// WordPress - creating a reusable block
|
||||
// Done via Gutenberg editor, saved as wp_block post type
|
||||
```
|
||||
|
||||
EmDash:
|
||||
|
||||
```typescript
|
||||
import { getSection, getSections } from "emdash";
|
||||
|
||||
// Get a specific section
|
||||
const cta = await getSection("newsletter-cta");
|
||||
|
||||
// List sections by category
|
||||
const heroes = await getSections({ category: "heroes" });
|
||||
```
|
||||
|
||||
### Inserting Sections
|
||||
|
||||
In WordPress, you insert reusable blocks from the block inserter. In EmDash, editors use the `/section` slash command in the rich text editor.
|
||||
|
||||
### Section Sources
|
||||
|
||||
| Source | Origin |
|
||||
| -------- | --------------------------------------- |
|
||||
| `theme` | Defined in seed file (theme patterns) |
|
||||
| `user` | Created by editors in admin |
|
||||
| `import` | Imported from WordPress reusable blocks |
|
||||
|
||||
### Migration
|
||||
|
||||
WordPress `wp_block` posts are automatically imported as sections:
|
||||
|
||||
- Content converted from Gutenberg to Portable Text
|
||||
- Placed in "Imported" category
|
||||
- Source set to `"import"`
|
||||
396
skills/wordpress-theme-to-emdash/references/design-extraction.md
Normal file
396
skills/wordpress-theme-to-emdash/references/design-extraction.md
Normal file
@@ -0,0 +1,396 @@
|
||||
# Design Extraction Guide
|
||||
|
||||
Extract design tokens from WordPress themes for use in EmDash.
|
||||
|
||||
## CSS Variable Extraction
|
||||
|
||||
### Finding Design Tokens in Classic Themes
|
||||
|
||||
Look in these files (in order of priority):
|
||||
|
||||
1. **`style.css`** - Main stylesheet, often has custom properties
|
||||
2. **`assets/css/custom-properties.css`** - Some themes separate variables
|
||||
3. **`inc/customizer.php`** - Default values for customizer options
|
||||
4. **`functions.php`** - Inline styles with defaults
|
||||
|
||||
Common patterns to search for:
|
||||
|
||||
```css
|
||||
/* Root variables */
|
||||
:root {
|
||||
--primary-color: #0073aa;
|
||||
--font-family: 'Open Sans', sans-serif;
|
||||
}
|
||||
|
||||
/* Theme-specific prefixes */
|
||||
--theme-name-color-primary
|
||||
--wp--preset--color--primary
|
||||
```
|
||||
|
||||
### Finding Design Tokens in Block Themes (theme.json)
|
||||
|
||||
Block themes (WordPress 5.9+) store design tokens in `theme.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"settings": {
|
||||
"color": {
|
||||
"palette": [
|
||||
{ "slug": "primary", "color": "#0073aa", "name": "Primary" },
|
||||
{ "slug": "secondary", "color": "#23282d", "name": "Secondary" }
|
||||
]
|
||||
},
|
||||
"typography": {
|
||||
"fontFamilies": [
|
||||
{
|
||||
"fontFamily": "'Open Sans', sans-serif",
|
||||
"slug": "body",
|
||||
"name": "Body"
|
||||
}
|
||||
],
|
||||
"fontSizes": [{ "size": "1rem", "slug": "medium", "name": "Medium" }]
|
||||
},
|
||||
"spacing": {
|
||||
"units": ["px", "em", "rem", "%"],
|
||||
"spacingSizes": [{ "size": "1rem", "slug": "20", "name": "Small" }]
|
||||
},
|
||||
"layout": {
|
||||
"contentSize": "650px",
|
||||
"wideSize": "1200px"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Convert to EmDash CSS variables:
|
||||
|
||||
```css
|
||||
:root {
|
||||
/* Colors from theme.json palette */
|
||||
--color-primary: #0073aa;
|
||||
--color-secondary: #23282d;
|
||||
|
||||
/* Typography */
|
||||
--font-body: "Open Sans", sans-serif;
|
||||
--font-size-medium: 1rem;
|
||||
|
||||
/* Layout */
|
||||
--content-width: 650px;
|
||||
--wide-width: 1200px;
|
||||
|
||||
/* Spacing */
|
||||
--space-20: 1rem;
|
||||
}
|
||||
```
|
||||
|
||||
## Color Extraction
|
||||
|
||||
### From Live Site
|
||||
|
||||
Use browser DevTools or automation:
|
||||
|
||||
1. **Background colors**: `document.body.style.backgroundColor`
|
||||
2. **Text colors**: Inspect body, headings, links
|
||||
3. **Accent colors**: Buttons, links, highlights
|
||||
|
||||
Common elements to check:
|
||||
|
||||
- Body background and text
|
||||
- Header/footer backgrounds
|
||||
- Link colors (normal, hover, visited)
|
||||
- Button colors (primary, secondary)
|
||||
- Border colors
|
||||
- Selection highlight
|
||||
|
||||
### Common Color Mapping
|
||||
|
||||
| WP Pattern | EmDash Variable |
|
||||
| ---------------- | ------------------- |
|
||||
| Background | `--color-base` |
|
||||
| Text | `--color-contrast` |
|
||||
| Primary brand | `--color-primary` |
|
||||
| Secondary brand | `--color-secondary` |
|
||||
| Accent/highlight | `--color-accent-1` |
|
||||
| Muted text | `--color-muted` |
|
||||
| Border | `--color-border` |
|
||||
| Error | `--color-error` |
|
||||
| Success | `--color-success` |
|
||||
|
||||
## Typography Extraction
|
||||
|
||||
### Font Families
|
||||
|
||||
Check for:
|
||||
|
||||
1. Google Fonts in `<head>` - `fonts.googleapis.com`
|
||||
2. `@font-face` declarations in CSS
|
||||
3. Font files in `assets/fonts/` or `fonts/`
|
||||
4. Customizer settings for typography
|
||||
|
||||
Extract the stack:
|
||||
|
||||
```css
|
||||
/* WP theme might have */
|
||||
font-family: "Playfair Display", Georgia, serif;
|
||||
|
||||
/* Convert to EmDash */
|
||||
:root {
|
||||
--font-heading: "Playfair Display", Georgia, serif;
|
||||
}
|
||||
```
|
||||
|
||||
### Font Sizes
|
||||
|
||||
Common patterns:
|
||||
|
||||
```css
|
||||
/* WP theme */
|
||||
body {
|
||||
font-size: 18px;
|
||||
}
|
||||
h1 {
|
||||
font-size: 2.5em;
|
||||
}
|
||||
h2 {
|
||||
font-size: 2em;
|
||||
}
|
||||
|
||||
/* EmDash with clamp for responsiveness */
|
||||
:root {
|
||||
--font-size-base: clamp(1rem, 0.5vw + 0.9rem, 1.125rem);
|
||||
--font-size-xl: clamp(1.75rem, 1vw + 1.5rem, 2rem);
|
||||
--font-size-xxl: clamp(2.15rem, 2vw + 1.5rem, 3rem);
|
||||
}
|
||||
```
|
||||
|
||||
### Line Height and Spacing
|
||||
|
||||
```css
|
||||
/* Extract these values */
|
||||
line-height: 1.6;
|
||||
letter-spacing: -0.01em;
|
||||
```
|
||||
|
||||
## Spacing System
|
||||
|
||||
### Identify the Scale
|
||||
|
||||
Look for consistent spacing values:
|
||||
|
||||
```css
|
||||
/* Common WordPress patterns */
|
||||
padding: 20px;
|
||||
margin-bottom: 30px;
|
||||
gap: 2rem;
|
||||
```
|
||||
|
||||
Create a scale:
|
||||
|
||||
```css
|
||||
:root {
|
||||
--space-10: 0.25rem; /* 4px */
|
||||
--space-20: 0.5rem; /* 8px */
|
||||
--space-30: 1rem; /* 16px */
|
||||
--space-40: 1.5rem; /* 24px */
|
||||
--space-50: 2rem; /* 32px */
|
||||
--space-60: 3rem; /* 48px */
|
||||
--space-70: 4rem; /* 64px */
|
||||
--space-80: 6rem; /* 96px */
|
||||
}
|
||||
```
|
||||
|
||||
## Layout Extraction
|
||||
|
||||
### Content Width
|
||||
|
||||
Find in:
|
||||
|
||||
- `.container`, `.wrapper`, `.site-content` max-width
|
||||
- `theme.json` layout.contentSize
|
||||
- Customizer settings
|
||||
|
||||
```css
|
||||
/* WP theme */
|
||||
.container {
|
||||
max-width: 1140px;
|
||||
}
|
||||
.content-area {
|
||||
max-width: 720px;
|
||||
}
|
||||
|
||||
/* EmDash */
|
||||
:root {
|
||||
--content-width: 720px;
|
||||
--wide-width: 1140px;
|
||||
}
|
||||
```
|
||||
|
||||
### Breakpoints
|
||||
|
||||
Common WordPress breakpoints:
|
||||
|
||||
```css
|
||||
/* Find in theme CSS */
|
||||
@media (max-width: 1200px) {
|
||||
}
|
||||
@media (max-width: 992px) {
|
||||
}
|
||||
@media (max-width: 768px) {
|
||||
}
|
||||
@media (max-width: 576px) {
|
||||
}
|
||||
```
|
||||
|
||||
Document for use in Astro:
|
||||
|
||||
```css
|
||||
/* EmDash breakpoints */
|
||||
@media (max-width: 1024px) {
|
||||
/* Tablet landscape */
|
||||
}
|
||||
@media (max-width: 768px) {
|
||||
/* Tablet portrait */
|
||||
}
|
||||
@media (max-width: 640px) {
|
||||
/* Mobile */
|
||||
}
|
||||
```
|
||||
|
||||
## Component Patterns
|
||||
|
||||
### Header Pattern
|
||||
|
||||
Identify header structure:
|
||||
|
||||
- Logo position (left, center)
|
||||
- Navigation style (horizontal, hamburger)
|
||||
- Background (solid, transparent, sticky)
|
||||
|
||||
```css
|
||||
/* Extract key values */
|
||||
.site-header {
|
||||
height: 80px;
|
||||
background: #ffffff;
|
||||
position: sticky;
|
||||
top: 0;
|
||||
z-index: 100;
|
||||
}
|
||||
```
|
||||
|
||||
### Card Pattern
|
||||
|
||||
```css
|
||||
/* WP card styles */
|
||||
.post-card {
|
||||
border-radius: 8px;
|
||||
box-shadow: 0 2px 8px rgba(0, 0, 0, 0.1);
|
||||
overflow: hidden;
|
||||
}
|
||||
|
||||
/* EmDash equivalent */
|
||||
:root {
|
||||
--radius-card: 8px;
|
||||
--shadow-card: 0 2px 8px rgba(0, 0, 0, 0.1);
|
||||
}
|
||||
```
|
||||
|
||||
### Button Pattern
|
||||
|
||||
```css
|
||||
/* WP button */
|
||||
.button,
|
||||
.wp-block-button__link {
|
||||
padding: 12px 24px;
|
||||
border-radius: 4px;
|
||||
font-weight: 600;
|
||||
text-transform: uppercase;
|
||||
}
|
||||
|
||||
/* EmDash */
|
||||
.btn {
|
||||
padding: var(--space-30) var(--space-40);
|
||||
border-radius: var(--radius-button);
|
||||
font-weight: 600;
|
||||
}
|
||||
```
|
||||
|
||||
## Automated Extraction Script
|
||||
|
||||
For complex themes, consider a script approach:
|
||||
|
||||
```javascript
|
||||
// Run in browser console on live WP site
|
||||
const styles = getComputedStyle(document.body);
|
||||
const tokens = {
|
||||
colors: {
|
||||
background: styles.backgroundColor,
|
||||
text: styles.color,
|
||||
},
|
||||
typography: {
|
||||
fontFamily: styles.fontFamily,
|
||||
fontSize: styles.fontSize,
|
||||
lineHeight: styles.lineHeight,
|
||||
},
|
||||
};
|
||||
|
||||
// Check header
|
||||
const header = document.querySelector("header, .site-header");
|
||||
if (header) {
|
||||
const headerStyles = getComputedStyle(header);
|
||||
tokens.header = {
|
||||
background: headerStyles.backgroundColor,
|
||||
height: headerStyles.height,
|
||||
};
|
||||
}
|
||||
|
||||
console.log(JSON.stringify(tokens, null, 2));
|
||||
```
|
||||
|
||||
## Output Template
|
||||
|
||||
Final CSS variables for EmDash Base.astro:
|
||||
|
||||
```css
|
||||
:root {
|
||||
/* Colors */
|
||||
--color-base: #ffffff;
|
||||
--color-contrast: #1a1a1a;
|
||||
--color-primary: #0073aa;
|
||||
--color-secondary: #23282d;
|
||||
--color-muted: #757575;
|
||||
--color-border: #e0e0e0;
|
||||
|
||||
/* Typography */
|
||||
--font-body: "Open Sans", system-ui, sans-serif;
|
||||
--font-heading: "Playfair Display", Georgia, serif;
|
||||
--font-mono: "Fira Code", monospace;
|
||||
|
||||
/* Font sizes */
|
||||
--font-size-small: 0.875rem;
|
||||
--font-size-base: 1rem;
|
||||
--font-size-large: 1.125rem;
|
||||
--font-size-xl: 1.5rem;
|
||||
--font-size-xxl: 2rem;
|
||||
--font-size-xxxl: 3rem;
|
||||
|
||||
/* Spacing */
|
||||
--space-20: 0.5rem;
|
||||
--space-30: 1rem;
|
||||
--space-40: 1.5rem;
|
||||
--space-50: 2rem;
|
||||
--space-60: 3rem;
|
||||
--space-70: 4rem;
|
||||
--space-80: 6rem;
|
||||
|
||||
/* Layout */
|
||||
--content-width: 720px;
|
||||
--wide-width: 1200px;
|
||||
|
||||
/* Components */
|
||||
--radius-small: 4px;
|
||||
--radius-medium: 8px;
|
||||
--radius-large: 16px;
|
||||
--shadow-small: 0 1px 3px rgba(0, 0, 0, 0.1);
|
||||
--shadow-medium: 0 4px 12px rgba(0, 0, 0, 0.15);
|
||||
}
|
||||
```
|
||||
516
skills/wordpress-theme-to-emdash/references/emdash-api.md
Normal file
516
skills/wordpress-theme-to-emdash/references/emdash-api.md
Normal file
@@ -0,0 +1,516 @@
|
||||
# EmDash API Reference
|
||||
|
||||
Quick reference for EmDash-specific APIs used when porting themes.
|
||||
|
||||
> **See also:** The `scaffold/` directory contains working examples of all these patterns. When in doubt, copy from there.
|
||||
|
||||
## Content Retrieval
|
||||
|
||||
EmDash's query functions follow Astro's [live content collections](https://docs.astro.build/en/reference/experimental-flags/live-content-collections/) pattern, returning structured results for graceful error handling.
|
||||
|
||||
### getEmDashCollection
|
||||
|
||||
Fetch multiple entries from a collection.
|
||||
|
||||
```typescript
|
||||
import { getEmDashCollection } from "emdash";
|
||||
|
||||
// Returns { entries, error }
|
||||
const { entries: posts } = await getEmDashCollection("posts");
|
||||
|
||||
// With filters
|
||||
const { entries: posts } = await getEmDashCollection("posts", {
|
||||
status: "published",
|
||||
limit: 10,
|
||||
where: { category: "news" },
|
||||
});
|
||||
```
|
||||
|
||||
### getEmDashEntry
|
||||
|
||||
Fetch a single entry by slug.
|
||||
|
||||
```typescript
|
||||
import { getEmDashEntry } from "emdash";
|
||||
|
||||
// Returns { entry, error, isPreview }
|
||||
const { entry: post } = await getEmDashEntry("posts", "hello-world");
|
||||
|
||||
if (!post) {
|
||||
return Astro.redirect("/404");
|
||||
}
|
||||
```
|
||||
|
||||
### Entry Shape
|
||||
|
||||
```typescript
|
||||
interface Entry {
|
||||
id: string;
|
||||
collection: string;
|
||||
data: {
|
||||
title: string;
|
||||
slug: string;
|
||||
content: PortableTextBlock[];
|
||||
featured_image?: ImageField; // { src, alt } - NOT a string!
|
||||
// ... custom fields
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
## Field Types at Runtime
|
||||
|
||||
**IMPORTANT:** Field types have specific runtime shapes. The most common mistake is treating image fields as strings.
|
||||
|
||||
### Image Fields
|
||||
|
||||
Image fields are **objects**, not strings:
|
||||
|
||||
```typescript
|
||||
interface ImageField {
|
||||
src: string; // The resolved URL
|
||||
alt?: string;
|
||||
}
|
||||
```
|
||||
|
||||
```astro
|
||||
{/* CORRECT */}
|
||||
{post.data.featured_image?.src && (
|
||||
<img
|
||||
src={post.data.featured_image.src}
|
||||
alt={post.data.featured_image.alt || post.data.title}
|
||||
/>
|
||||
)}
|
||||
|
||||
{/* WRONG - renders [object Object] */}
|
||||
<img src={post.data.featured_image} />
|
||||
```
|
||||
|
||||
### Reference Fields
|
||||
|
||||
In seed files use `"$ref:id"` format. At runtime they may be resolved objects or strings.
|
||||
|
||||
### PortableText Fields
|
||||
|
||||
Rich content is an array of blocks with `_type` property.
|
||||
|
||||
## Site Settings
|
||||
|
||||
### getSiteSettings
|
||||
|
||||
Get all site settings.
|
||||
|
||||
```typescript
|
||||
import { getSiteSettings } from "emdash";
|
||||
|
||||
const settings = await getSiteSettings();
|
||||
console.log(settings.title); // "My Site"
|
||||
console.log(settings.logo?.url); // Resolved media URL
|
||||
```
|
||||
|
||||
### getSiteSetting
|
||||
|
||||
Get a single setting.
|
||||
|
||||
```typescript
|
||||
import { getSiteSetting } from "emdash";
|
||||
|
||||
const title = await getSiteSetting("title");
|
||||
const logo = await getSiteSetting("logo");
|
||||
```
|
||||
|
||||
### Available Settings
|
||||
|
||||
| Key | Type | Description |
|
||||
| ------------ | ---------------- | ------------------------ |
|
||||
| `title` | `string` | Site name |
|
||||
| `tagline` | `string` | Site tagline/description |
|
||||
| `logo` | `MediaReference` | Site logo with URL |
|
||||
| `favicon` | `MediaReference` | Favicon with URL |
|
||||
| `social` | `SocialLinks` | Social media URLs |
|
||||
| `timezone` | `string` | Site timezone |
|
||||
| `dateFormat` | `string` | Date display format |
|
||||
|
||||
## Navigation Menus
|
||||
|
||||
### getMenu
|
||||
|
||||
Fetch a menu by name with resolved URLs.
|
||||
|
||||
```typescript
|
||||
import { getMenu } from "emdash";
|
||||
|
||||
const menu = await getMenu("primary");
|
||||
|
||||
if (menu) {
|
||||
console.log(menu.items); // MenuItem[]
|
||||
}
|
||||
```
|
||||
|
||||
### getMenus
|
||||
|
||||
Get all menus (names only).
|
||||
|
||||
```typescript
|
||||
import { getMenus } from "emdash";
|
||||
|
||||
const menus = await getMenus();
|
||||
// [{ id, name, label }]
|
||||
```
|
||||
|
||||
### MenuItem Shape
|
||||
|
||||
```typescript
|
||||
interface MenuItem {
|
||||
id: string;
|
||||
label: string;
|
||||
url: string; // Resolved URL
|
||||
target?: string;
|
||||
children: MenuItem[];
|
||||
}
|
||||
```
|
||||
|
||||
### Rendering Menus
|
||||
|
||||
```astro
|
||||
---
|
||||
import { getMenu } from "emdash";
|
||||
|
||||
const primaryMenu = await getMenu("primary");
|
||||
---
|
||||
<nav>
|
||||
{primaryMenu?.items.map(item => (
|
||||
<a href={item.url}>{item.label}</a>
|
||||
))}
|
||||
</nav>
|
||||
```
|
||||
|
||||
## Taxonomies
|
||||
|
||||
### getTaxonomyTerms
|
||||
|
||||
Get all terms for a taxonomy.
|
||||
|
||||
```typescript
|
||||
import { getTaxonomyTerms } from "emdash";
|
||||
|
||||
const categories = await getTaxonomyTerms("categories");
|
||||
const tags = await getTaxonomyTerms("tags");
|
||||
```
|
||||
|
||||
### getTerm
|
||||
|
||||
Get a single term by slug.
|
||||
|
||||
```typescript
|
||||
import { getTerm } from "emdash";
|
||||
|
||||
const term = await getTerm("categories", "news");
|
||||
console.log(term?.label); // "News"
|
||||
console.log(term?.count); // Number of entries
|
||||
```
|
||||
|
||||
### getEntryTerms
|
||||
|
||||
Get terms assigned to a specific entry.
|
||||
|
||||
> **IMPORTANT:** This function does NOT take a `db` parameter.
|
||||
|
||||
```typescript
|
||||
import { getEntryTerms } from "emdash";
|
||||
|
||||
// Get all terms for an entry
|
||||
const terms = await getEntryTerms("posts", post.id);
|
||||
|
||||
// Get only categories
|
||||
const categories = await getEntryTerms("posts", post.id, "categories");
|
||||
```
|
||||
|
||||
### getEntriesByTerm
|
||||
|
||||
Get entries that have a specific term.
|
||||
|
||||
```typescript
|
||||
import { getEntriesByTerm } from "emdash";
|
||||
|
||||
const posts = await getEntriesByTerm("posts", "categories", "news");
|
||||
```
|
||||
|
||||
### TaxonomyTerm Shape
|
||||
|
||||
```typescript
|
||||
interface TaxonomyTerm {
|
||||
id: string;
|
||||
name: string; // Taxonomy name
|
||||
slug: string; // Term slug
|
||||
label: string; // Display label
|
||||
children: TaxonomyTerm[];
|
||||
count?: number;
|
||||
}
|
||||
```
|
||||
|
||||
## Widget Areas
|
||||
|
||||
### getWidgetArea
|
||||
|
||||
Get a widget area by name.
|
||||
|
||||
```typescript
|
||||
import { getWidgetArea } from "emdash";
|
||||
|
||||
const sidebar = await getWidgetArea("sidebar");
|
||||
|
||||
if (sidebar) {
|
||||
console.log(sidebar.widgets); // Widget[]
|
||||
}
|
||||
```
|
||||
|
||||
### Widget Types
|
||||
|
||||
| Type | Description | Key Fields |
|
||||
| ----------- | -------------------- | ---------------------- |
|
||||
| `content` | Rich text (PT) | `content` |
|
||||
| `menu` | Navigation menu | `menuName` |
|
||||
| `component` | Registered component | `componentId`, `props` |
|
||||
|
||||
## Sections (Reusable Blocks)
|
||||
|
||||
Sections are reusable content blocks that editors can insert via `/section` slash command.
|
||||
|
||||
### getSection
|
||||
|
||||
Get a single section by slug.
|
||||
|
||||
```typescript
|
||||
import { getSection } from "emdash";
|
||||
|
||||
const cta = await getSection("newsletter-cta");
|
||||
// Returns { id, slug, title, content, keywords, source }
|
||||
```
|
||||
|
||||
### getSections
|
||||
|
||||
List sections with optional filters.
|
||||
|
||||
```typescript
|
||||
import { getSections } from "emdash";
|
||||
|
||||
// Get all sections
|
||||
const all = await getSections();
|
||||
|
||||
// Filter by source: "theme" | "user" | "import"
|
||||
const imported = await getSections({ source: "import" });
|
||||
```
|
||||
|
||||
### Section Sources
|
||||
|
||||
| Source | Description |
|
||||
| -------- | --------------------------------------- |
|
||||
| `theme` | Defined in seed file |
|
||||
| `user` | Created by editors in admin |
|
||||
| `import` | Imported from WordPress reusable blocks |
|
||||
|
||||
## Search
|
||||
|
||||
### search
|
||||
|
||||
Global search across collections.
|
||||
|
||||
```typescript
|
||||
import { search } from "emdash";
|
||||
|
||||
const results = await search("hello world", {
|
||||
collections: ["posts", "pages"], // Optional: limit to specific collections
|
||||
status: "published", // Optional: filter by status
|
||||
limit: 20, // Optional: max results
|
||||
});
|
||||
|
||||
// Returns { results: SearchResult[], total, nextCursor? }
|
||||
results.results.forEach((r) => {
|
||||
console.log(r.collection); // "posts"
|
||||
console.log(r.id); // Entry ID
|
||||
console.log(r.title); // Entry title
|
||||
console.log(r.slug); // Entry slug
|
||||
console.log(r.snippet); // HTML snippet with <mark> highlights
|
||||
console.log(r.score); // Relevance score
|
||||
});
|
||||
```
|
||||
|
||||
### LiveSearch Component
|
||||
|
||||
Ready-to-use search with instant results:
|
||||
|
||||
```astro
|
||||
---
|
||||
import LiveSearch from "emdash/ui/search";
|
||||
---
|
||||
|
||||
<LiveSearch
|
||||
placeholder="Search..."
|
||||
collections={["posts", "pages"]}
|
||||
/>
|
||||
```
|
||||
|
||||
Features:
|
||||
|
||||
- Debounced instant search
|
||||
- Prefix matching (automatic `*` suffix)
|
||||
- Porter stemming ("run" finds "running")
|
||||
- Result snippets with `<mark>` highlights
|
||||
|
||||
### Search Configuration
|
||||
|
||||
Search is enabled per-collection via admin UI:
|
||||
|
||||
1. Edit Content Type → check "Search" in Features
|
||||
2. Edit fields → check "Searchable" for text fields
|
||||
|
||||
Only collections with search enabled are indexed.
|
||||
|
||||
## Rendering Content
|
||||
|
||||
### PortableText Component
|
||||
|
||||
```astro
|
||||
---
|
||||
import { PortableText } from "emdash/ui";
|
||||
---
|
||||
|
||||
<PortableText value={post.data.content} />
|
||||
```
|
||||
|
||||
## CLI Commands
|
||||
|
||||
### Seed Validation
|
||||
|
||||
Validate seed files before applying:
|
||||
|
||||
```bash
|
||||
# Validate default seed file (.emdash/seed.json)
|
||||
emdash seed --validate
|
||||
|
||||
# Validate a specific file
|
||||
emdash seed path/to/seed.json --validate
|
||||
```
|
||||
|
||||
Catches common mistakes:
|
||||
|
||||
- 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.)
|
||||
|
||||
### Apply Seed
|
||||
|
||||
```bash
|
||||
# Apply seed with content
|
||||
emdash seed
|
||||
|
||||
# Apply seed without sample content
|
||||
emdash seed --no-content
|
||||
|
||||
# Specify database path
|
||||
emdash seed --database ./my-data.db
|
||||
```
|
||||
|
||||
### Export Seed
|
||||
|
||||
```bash
|
||||
# Export schema only
|
||||
emdash export-seed
|
||||
|
||||
# Export schema and all content
|
||||
emdash export-seed --with-content
|
||||
|
||||
# Export specific collections
|
||||
emdash export-seed --with-content=posts,pages
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
### astro.config.mjs
|
||||
|
||||
```javascript
|
||||
import { defineConfig } from "astro/config";
|
||||
import emdash, { local } from "emdash/astro";
|
||||
import { sqlite } from "emdash/db";
|
||||
|
||||
export default defineConfig({
|
||||
integrations: [
|
||||
emdash({
|
||||
database: sqlite({ url: "file:./data.db" }),
|
||||
storage: local({
|
||||
directory: "./uploads",
|
||||
baseUrl: "/_emdash/api/media/file",
|
||||
}),
|
||||
}),
|
||||
],
|
||||
});
|
||||
```
|
||||
|
||||
### live.config.ts
|
||||
|
||||
```typescript
|
||||
// src/live.config.ts
|
||||
import { defineLiveCollection } from "astro:content";
|
||||
import { emdashLoader } from "emdash/runtime";
|
||||
|
||||
export const collections = {
|
||||
_emdash: defineLiveCollection({ loader: emdashLoader() }),
|
||||
};
|
||||
```
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### Homepage with Recent Posts
|
||||
|
||||
```astro
|
||||
---
|
||||
import { getEmDashCollection, getSiteSettings } from "emdash";
|
||||
import Base from "../layouts/Base.astro";
|
||||
|
||||
const settings = await getSiteSettings();
|
||||
const { entries: posts } = await getEmDashCollection("posts", { limit: 10 });
|
||||
---
|
||||
<Base title={settings.title}>
|
||||
{posts.map(post => (
|
||||
<article>
|
||||
<a href={`/posts/${post.data.slug}`}>{post.data.title}</a>
|
||||
</article>
|
||||
))}
|
||||
</Base>
|
||||
```
|
||||
|
||||
### Category Archive
|
||||
|
||||
```astro
|
||||
---
|
||||
import { getTerm, getEntriesByTerm } from "emdash";
|
||||
|
||||
const { slug } = Astro.params;
|
||||
const category = await getTerm("categories", slug);
|
||||
const posts = await getEntriesByTerm("posts", "categories", slug);
|
||||
---
|
||||
<h1>{category?.label}</h1>
|
||||
{posts.map(post => (
|
||||
<a href={`/posts/${post.data.slug}`}>{post.data.title}</a>
|
||||
))}
|
||||
```
|
||||
|
||||
### Dynamic Navigation
|
||||
|
||||
```astro
|
||||
---
|
||||
import { getMenu, getSiteSettings } from "emdash";
|
||||
|
||||
const settings = await getSiteSettings();
|
||||
const primaryMenu = await getMenu("primary");
|
||||
---
|
||||
<header>
|
||||
<a href="/">{settings.title}</a>
|
||||
<nav>
|
||||
{primaryMenu?.items.map(item => (
|
||||
<a href={item.url}>{item.label}</a>
|
||||
))}
|
||||
</nav>
|
||||
</header>
|
||||
```
|
||||
839
skills/wordpress-theme-to-emdash/references/template-patterns.md
Normal file
839
skills/wordpress-theme-to-emdash/references/template-patterns.md
Normal file
@@ -0,0 +1,839 @@
|
||||
# PHP → Astro Template Patterns
|
||||
|
||||
Common WordPress PHP patterns and their Astro/EmDash equivalents.
|
||||
|
||||
## The Loop
|
||||
|
||||
### Basic Loop
|
||||
|
||||
```php
|
||||
// WordPress
|
||||
<?php if (have_posts()) : ?>
|
||||
<?php while (have_posts()) : the_post(); ?>
|
||||
<article>
|
||||
<h2><a href="<?php the_permalink(); ?>"><?php the_title(); ?></a></h2>
|
||||
<?php the_excerpt(); ?>
|
||||
</article>
|
||||
<?php endwhile; ?>
|
||||
<?php else : ?>
|
||||
<p>No posts found.</p>
|
||||
<?php endif; ?>
|
||||
```
|
||||
|
||||
```astro
|
||||
---
|
||||
// Astro/EmDash
|
||||
import { getEmDashCollection } from "emdash";
|
||||
const { entries: posts } = await getEmDashCollection("posts");
|
||||
---
|
||||
{posts.length > 0 ? (
|
||||
posts.map(post => (
|
||||
<article>
|
||||
<h2><a href={`/posts/${post.id}`}>{post.data.title}</a></h2>
|
||||
<p>{post.data.excerpt}</p>
|
||||
</article>
|
||||
))
|
||||
) : (
|
||||
<p>No posts found.</p>
|
||||
)}
|
||||
```
|
||||
|
||||
### Custom Query
|
||||
|
||||
```php
|
||||
// WordPress
|
||||
$args = [
|
||||
'post_type' => 'portfolio',
|
||||
'posts_per_page' => 6,
|
||||
'orderby' => 'date',
|
||||
'order' => 'DESC',
|
||||
];
|
||||
$query = new WP_Query($args);
|
||||
while ($query->have_posts()) : $query->the_post();
|
||||
// ...
|
||||
endwhile;
|
||||
wp_reset_postdata();
|
||||
```
|
||||
|
||||
```astro
|
||||
---
|
||||
// Astro/EmDash
|
||||
import { getEmDashCollection } from "emdash";
|
||||
const { entries: items } = await getEmDashCollection("portfolio", {
|
||||
limit: 6,
|
||||
orderBy: { published_at: "desc" },
|
||||
});
|
||||
---
|
||||
{items.map(item => (
|
||||
// ...
|
||||
))}
|
||||
```
|
||||
|
||||
## Single Post/Page
|
||||
|
||||
### Basic Single
|
||||
|
||||
```php
|
||||
// WordPress single.php
|
||||
<?php get_header(); ?>
|
||||
<main>
|
||||
<?php while (have_posts()) : the_post(); ?>
|
||||
<article>
|
||||
<h1><?php the_title(); ?></h1>
|
||||
<div class="meta">
|
||||
<?php the_date(); ?> | <?php the_author(); ?>
|
||||
</div>
|
||||
<?php the_content(); ?>
|
||||
</article>
|
||||
<?php endwhile; ?>
|
||||
</main>
|
||||
<?php get_footer(); ?>
|
||||
```
|
||||
|
||||
```astro
|
||||
---
|
||||
// Astro pages/posts/[slug].astro
|
||||
// NOTE: EmDash pages are always server-rendered (no getStaticPaths)
|
||||
import { getEmDashEntry } from "emdash";
|
||||
import { PortableText } from "emdash/ui";
|
||||
import Base from "../../layouts/Base.astro";
|
||||
|
||||
const { slug } = Astro.params;
|
||||
const { entry: post } = await getEmDashEntry("posts", slug!);
|
||||
|
||||
if (!post) {
|
||||
return Astro.redirect("/404");
|
||||
}
|
||||
---
|
||||
<Base title={post.data.title}>
|
||||
<main>
|
||||
<article>
|
||||
<h1>{post.data.title}</h1>
|
||||
<div class="meta">
|
||||
{post.data.publishedAt} | {post.data.byline?.displayName ?? "Unknown"}
|
||||
</div>
|
||||
<PortableText value={post.data.content} />
|
||||
</article>
|
||||
</main>
|
||||
</Base>
|
||||
```
|
||||
|
||||
## Featured Image
|
||||
|
||||
```php
|
||||
// WordPress
|
||||
<?php if (has_post_thumbnail()) : ?>
|
||||
<figure class="featured-image">
|
||||
<?php the_post_thumbnail('large'); ?>
|
||||
</figure>
|
||||
<?php endif; ?>
|
||||
```
|
||||
|
||||
```astro
|
||||
---
|
||||
// Astro
|
||||
const { featured_image } = post.data;
|
||||
---
|
||||
{featured_image && (
|
||||
<figure class="featured-image">
|
||||
<img src={featured_image} alt={post.data.title} />
|
||||
</figure>
|
||||
)}
|
||||
```
|
||||
|
||||
## Pagination
|
||||
|
||||
### Archive Pagination
|
||||
|
||||
```php
|
||||
// WordPress
|
||||
<?php
|
||||
the_posts_pagination([
|
||||
'prev_text' => '« Previous',
|
||||
'next_text' => 'Next »',
|
||||
]);
|
||||
?>
|
||||
```
|
||||
|
||||
```astro
|
||||
---
|
||||
// Astro - using cursor pagination
|
||||
import { getEmDashCollection } from "emdash";
|
||||
const page = Astro.url.searchParams.get('page') || '1';
|
||||
const { entries, nextCursor, prevCursor } = await getEmDashCollection("posts", {
|
||||
limit: 10,
|
||||
cursor: Astro.url.searchParams.get('cursor'),
|
||||
});
|
||||
---
|
||||
<nav class="pagination">
|
||||
{prevCursor && <a href={`?cursor=${prevCursor}`}>« Previous</a>}
|
||||
{nextCursor && <a href={`?cursor=${nextCursor}`}>Next »</a>}
|
||||
</nav>
|
||||
```
|
||||
|
||||
### Post Navigation (Prev/Next)
|
||||
|
||||
```php
|
||||
// WordPress
|
||||
<?php
|
||||
the_post_navigation([
|
||||
'prev_text' => '← %title',
|
||||
'next_text' => '%title →',
|
||||
]);
|
||||
?>
|
||||
```
|
||||
|
||||
```astro
|
||||
---
|
||||
// Astro - requires fetching adjacent posts
|
||||
// This is more complex; typically done at query time
|
||||
// or by storing prev/next references
|
||||
---
|
||||
```
|
||||
|
||||
## Conditionals
|
||||
|
||||
### Check Post Type
|
||||
|
||||
```php
|
||||
// WordPress
|
||||
<?php if (is_singular('portfolio')) : ?>
|
||||
<!-- Portfolio-specific content -->
|
||||
<?php endif; ?>
|
||||
```
|
||||
|
||||
```astro
|
||||
---
|
||||
// Astro - handled by file-based routing
|
||||
// pages/portfolio/[slug].astro IS the portfolio single
|
||||
---
|
||||
```
|
||||
|
||||
### Check Page Template
|
||||
|
||||
```php
|
||||
// WordPress
|
||||
<?php if (is_page_template('templates/full-width.php')) : ?>
|
||||
<div class="full-width">
|
||||
<?php else : ?>
|
||||
<div class="with-sidebar">
|
||||
<?php endif; ?>
|
||||
```
|
||||
|
||||
```astro
|
||||
---
|
||||
// Astro - add a "template" select field to your pages collection
|
||||
// with options like "Default", "Full Width", etc.
|
||||
// Then in your page route, map templates to layout components:
|
||||
|
||||
import PageDefault from "../../layouts/PageDefault.astro";
|
||||
import PageFullWidth from "../../layouts/PageFullWidth.astro";
|
||||
|
||||
const layouts = {
|
||||
"Default": PageDefault,
|
||||
"Full Width": PageFullWidth,
|
||||
};
|
||||
|
||||
const Layout = layouts[page.data.template as keyof typeof layouts] ?? PageDefault;
|
||||
---
|
||||
<Layout page={page} />
|
||||
```
|
||||
|
||||
## Template Parts
|
||||
|
||||
### Include Template Part
|
||||
|
||||
```php
|
||||
// WordPress
|
||||
<?php get_template_part('template-parts/content', get_post_type()); ?>
|
||||
// Loads template-parts/content-{post_type}.php
|
||||
```
|
||||
|
||||
```astro
|
||||
---
|
||||
// Astro - use components
|
||||
import PostCard from '../components/PostCard.astro';
|
||||
import PortfolioCard from '../components/PortfolioCard.astro';
|
||||
|
||||
const CardComponent = post.collection === 'portfolio' ? PortfolioCard : PostCard;
|
||||
---
|
||||
<CardComponent post={post} />
|
||||
```
|
||||
|
||||
### Reusable Card Component
|
||||
|
||||
```php
|
||||
// WordPress template-parts/content.php
|
||||
<article id="post-<?php the_ID(); ?>" <?php post_class(); ?>>
|
||||
<header class="entry-header">
|
||||
<?php the_title('<h2 class="entry-title"><a href="' . esc_url(get_permalink()) . '">', '</a></h2>'); ?>
|
||||
</header>
|
||||
<div class="entry-content">
|
||||
<?php the_excerpt(); ?>
|
||||
</div>
|
||||
</article>
|
||||
```
|
||||
|
||||
```astro
|
||||
---
|
||||
// Astro components/PostCard.astro
|
||||
interface Props {
|
||||
post: {
|
||||
id: string;
|
||||
data: {
|
||||
title: string;
|
||||
excerpt?: string;
|
||||
};
|
||||
};
|
||||
}
|
||||
const { post } = Astro.props;
|
||||
---
|
||||
<article id={`post-${post.id}`} class="post">
|
||||
<header class="entry-header">
|
||||
<h2 class="entry-title">
|
||||
<a href={`/posts/${post.id}`}>{post.data.title}</a>
|
||||
</h2>
|
||||
</header>
|
||||
<div class="entry-content">
|
||||
<p>{post.data.excerpt}</p>
|
||||
</div>
|
||||
</article>
|
||||
```
|
||||
|
||||
## Navigation Menus
|
||||
|
||||
```php
|
||||
// WordPress
|
||||
<?php
|
||||
wp_nav_menu([
|
||||
'theme_location' => 'primary',
|
||||
'container' => 'nav',
|
||||
'container_class' => 'primary-nav',
|
||||
]);
|
||||
?>
|
||||
```
|
||||
|
||||
```astro
|
||||
---
|
||||
// Astro/EmDash - First-class menu support
|
||||
import { getMenu } from "emdash";
|
||||
|
||||
const primaryMenu = await getMenu("primary");
|
||||
---
|
||||
<nav class="primary-nav">
|
||||
{primaryMenu && (
|
||||
<ul>
|
||||
{primaryMenu.items.map(item => (
|
||||
<li class={item.cssClasses}>
|
||||
<a
|
||||
href={item.url}
|
||||
target={item.target}
|
||||
title={item.titleAttr}
|
||||
>
|
||||
{item.label}
|
||||
</a>
|
||||
{/* Nested items for dropdowns */}
|
||||
{item.children.length > 0 && (
|
||||
<ul class="submenu">
|
||||
{item.children.map(child => (
|
||||
<li><a href={child.url}>{child.label}</a></li>
|
||||
))}
|
||||
</ul>
|
||||
)}
|
||||
</li>
|
||||
))}
|
||||
</ul>
|
||||
)}
|
||||
</nav>
|
||||
```
|
||||
|
||||
### Recursive Menu Component
|
||||
|
||||
```astro
|
||||
---
|
||||
// components/MenuItem.astro
|
||||
interface Props {
|
||||
item: {
|
||||
label: string;
|
||||
url: string;
|
||||
target?: string;
|
||||
cssClasses?: string;
|
||||
children: Props['item'][];
|
||||
};
|
||||
}
|
||||
const { item } = Astro.props;
|
||||
---
|
||||
<li class={item.cssClasses}>
|
||||
<a href={item.url} target={item.target}>{item.label}</a>
|
||||
{item.children.length > 0 && (
|
||||
<ul class="submenu">
|
||||
{item.children.map(child => (
|
||||
<Astro.self item={child} />
|
||||
))}
|
||||
</ul>
|
||||
)}
|
||||
</li>
|
||||
```
|
||||
|
||||
## Sidebars / Widget Areas
|
||||
|
||||
```php
|
||||
// WordPress
|
||||
<?php if (is_active_sidebar('sidebar-1')) : ?>
|
||||
<aside class="sidebar">
|
||||
<?php dynamic_sidebar('sidebar-1'); ?>
|
||||
</aside>
|
||||
<?php endif; ?>
|
||||
```
|
||||
|
||||
```astro
|
||||
---
|
||||
// Astro/EmDash - First-class widget area support
|
||||
import { getWidgetArea, getMenu, getTaxonomyTerms, getEmDashCollection } from "emdash";
|
||||
import { PortableText } from "emdash/astro";
|
||||
|
||||
const sidebar = await getWidgetArea("sidebar");
|
||||
---
|
||||
{sidebar && (
|
||||
<aside class="sidebar">
|
||||
{sidebar.widgets.map(async (widget) => (
|
||||
<div class="widget">
|
||||
{widget.title && <h3 class="widget-title">{widget.title}</h3>}
|
||||
|
||||
{/* Content widget - rich text */}
|
||||
{widget.type === "content" && widget.content && (
|
||||
<PortableText value={widget.content} />
|
||||
)}
|
||||
|
||||
{/* Menu widget - displays a navigation menu */}
|
||||
{widget.type === "menu" && widget.menuName && (
|
||||
<MenuWidget menuName={widget.menuName} />
|
||||
)}
|
||||
|
||||
{/* Component widget - renders a registered component */}
|
||||
{widget.type === "component" && (
|
||||
<WidgetComponent
|
||||
componentId={widget.componentId}
|
||||
props={widget.componentProps}
|
||||
/>
|
||||
)}
|
||||
</div>
|
||||
))}
|
||||
</aside>
|
||||
)}
|
||||
```
|
||||
|
||||
### Widget Component Handler
|
||||
|
||||
```astro
|
||||
---
|
||||
// components/WidgetComponent.astro
|
||||
import { getTaxonomyTerms, getEmDashCollection } from "emdash";
|
||||
|
||||
interface Props {
|
||||
componentId: string;
|
||||
props?: Record<string, unknown>;
|
||||
}
|
||||
const { componentId, props = {} } = Astro.props;
|
||||
|
||||
// Handle core widget components
|
||||
let content = null;
|
||||
|
||||
if (componentId === "core:recent-posts") {
|
||||
const limit = (props.limit as number) || 5;
|
||||
const collection = (props.collection as string) || "posts";
|
||||
const { entries: posts } = await getEmDashCollection(collection, { limit });
|
||||
content = posts;
|
||||
}
|
||||
|
||||
if (componentId === "core:categories") {
|
||||
const taxonomy = (props.taxonomy as string) || "categories";
|
||||
content = await getTaxonomyTerms(taxonomy);
|
||||
}
|
||||
|
||||
if (componentId === "core:tag-cloud") {
|
||||
const taxonomy = (props.taxonomy as string) || "tags";
|
||||
content = await getTaxonomyTerms(taxonomy);
|
||||
}
|
||||
---
|
||||
{componentId === "core:recent-posts" && content && (
|
||||
<ul class="recent-posts">
|
||||
{content.map(post => (
|
||||
<li><a href={`/posts/${post.data.slug}`}>{post.data.title}</a></li>
|
||||
))}
|
||||
</ul>
|
||||
)}
|
||||
|
||||
{componentId === "core:categories" && content && (
|
||||
<ul class="categories">
|
||||
{content.map(cat => (
|
||||
<li>
|
||||
<a href={`/categories/${cat.slug}`}>
|
||||
{cat.label}
|
||||
{props.showCounts && <span>({cat.count})</span>}
|
||||
</a>
|
||||
</li>
|
||||
))}
|
||||
</ul>
|
||||
)}
|
||||
|
||||
{componentId === "core:tag-cloud" && content && (
|
||||
<div class="tag-cloud">
|
||||
{content.map(tag => (
|
||||
<a href={`/tags/${tag.slug}`} class="tag">{tag.label}</a>
|
||||
))}
|
||||
</div>
|
||||
)}
|
||||
|
||||
{componentId === "core:search" && (
|
||||
<form action="/search" method="get">
|
||||
<input
|
||||
type="search"
|
||||
name="q"
|
||||
placeholder={props.placeholder || "Search..."}
|
||||
/>
|
||||
<button type="submit">Search</button>
|
||||
</form>
|
||||
)}
|
||||
```
|
||||
|
||||
## Taxonomy Archives
|
||||
|
||||
### Category Archive
|
||||
|
||||
```php
|
||||
// WordPress category.php
|
||||
<?php
|
||||
$category = get_queried_object();
|
||||
?>
|
||||
<h1><?php echo $category->name; ?></h1>
|
||||
<p><?php echo $category->description; ?></p>
|
||||
|
||||
<?php while (have_posts()) : the_post(); ?>
|
||||
<!-- post loop -->
|
||||
<?php endwhile; ?>
|
||||
```
|
||||
|
||||
```astro
|
||||
---
|
||||
// Astro pages/categories/[slug].astro
|
||||
// NOTE: EmDash pages are always server-rendered (no getStaticPaths)
|
||||
import { getTerm, getEntriesByTerm } from "emdash";
|
||||
import Base from "../../layouts/Base.astro";
|
||||
|
||||
const { slug } = Astro.params;
|
||||
const category = await getTerm("categories", slug!);
|
||||
const posts = await getEntriesByTerm("posts", "categories", slug!);
|
||||
|
||||
if (!category) {
|
||||
return Astro.redirect("/404");
|
||||
}
|
||||
---
|
||||
<Base title={category.label}>
|
||||
<h1>{category.label}</h1>
|
||||
{category.description && <p>{category.description}</p>}
|
||||
|
||||
{posts.map(post => (
|
||||
<article>
|
||||
<a href={`/posts/${post.data.slug}`}>{post.data.title}</a>
|
||||
</article>
|
||||
))}
|
||||
</Base>
|
||||
```
|
||||
|
||||
### Tag Archive
|
||||
|
||||
```php
|
||||
// WordPress tag.php
|
||||
<?php
|
||||
$tag = get_queried_object();
|
||||
?>
|
||||
<h1>Posts tagged: <?php echo $tag->name; ?></h1>
|
||||
```
|
||||
|
||||
```astro
|
||||
---
|
||||
// Astro pages/tags/[slug].astro
|
||||
// NOTE: EmDash pages are always server-rendered (no getStaticPaths)
|
||||
import { getTerm, getEntriesByTerm } from "emdash";
|
||||
|
||||
const { slug } = Astro.params;
|
||||
const tag = await getTerm("tags", slug!);
|
||||
const posts = await getEntriesByTerm("posts", "tags", slug!);
|
||||
|
||||
if (!tag) {
|
||||
return Astro.redirect("/404");
|
||||
}
|
||||
---
|
||||
<h1>Posts tagged: {tag.label}</h1>
|
||||
{posts.map(post => (
|
||||
<article>
|
||||
<a href={`/posts/${post.data.slug}`}>{post.data.title}</a>
|
||||
</article>
|
||||
))}
|
||||
```
|
||||
|
||||
### Display Post Terms
|
||||
|
||||
```php
|
||||
// WordPress - in single.php
|
||||
<?php
|
||||
$categories = get_the_category();
|
||||
$tags = get_the_tags();
|
||||
?>
|
||||
<div class="post-meta">
|
||||
<span>Categories:
|
||||
<?php foreach ($categories as $cat) : ?>
|
||||
<a href="<?php echo get_category_link($cat); ?>"><?php echo $cat->name; ?></a>
|
||||
<?php endforeach; ?>
|
||||
</span>
|
||||
<span>Tags:
|
||||
<?php the_tags('', ', '); ?>
|
||||
</span>
|
||||
</div>
|
||||
```
|
||||
|
||||
```astro
|
||||
---
|
||||
// Astro - in post template
|
||||
import { getEntryTerms } from "emdash";
|
||||
|
||||
const categories = await getEntryTerms("posts", post.id, "categories");
|
||||
const tags = await getEntryTerms("posts", post.id, "tags");
|
||||
---
|
||||
<div class="post-meta">
|
||||
{categories.length > 0 && (
|
||||
<span>Categories:
|
||||
{categories.map((cat, i) => (
|
||||
<>
|
||||
{i > 0 && ", "}
|
||||
<a href={`/categories/${cat.slug}`}>{cat.label}</a>
|
||||
</>
|
||||
))}
|
||||
</span>
|
||||
)}
|
||||
|
||||
{tags.length > 0 && (
|
||||
<span>Tags:
|
||||
{tags.map((tag, i) => (
|
||||
<>
|
||||
{i > 0 && ", "}
|
||||
<a href={`/tags/${tag.slug}`}>{tag.label}</a>
|
||||
</>
|
||||
))}
|
||||
</span>
|
||||
)}
|
||||
</div>
|
||||
```
|
||||
|
||||
### Hierarchical Category List
|
||||
|
||||
```php
|
||||
// WordPress
|
||||
<?php wp_list_categories(['hierarchical' => true]); ?>
|
||||
```
|
||||
|
||||
```astro
|
||||
---
|
||||
// Astro - recursive category tree
|
||||
import { getTaxonomyTerms } from "emdash";
|
||||
|
||||
const categories = await getTaxonomyTerms("categories");
|
||||
|
||||
// Recursive component for nested categories
|
||||
function CategoryTree({ terms }) {
|
||||
return (
|
||||
<ul>
|
||||
{terms.map(term => (
|
||||
<li>
|
||||
<a href={`/categories/${term.slug}`}>
|
||||
{term.label} ({term.count})
|
||||
</a>
|
||||
{term.children?.length > 0 && (
|
||||
<CategoryTree terms={term.children} />
|
||||
)}
|
||||
</li>
|
||||
))}
|
||||
</ul>
|
||||
);
|
||||
}
|
||||
---
|
||||
<CategoryTree terms={categories} />
|
||||
```
|
||||
|
||||
## Site Settings
|
||||
|
||||
```php
|
||||
// WordPress
|
||||
<?php
|
||||
$site_name = get_bloginfo('name');
|
||||
$site_desc = get_bloginfo('description');
|
||||
$custom_logo_id = get_theme_mod('custom_logo');
|
||||
$logo_url = wp_get_attachment_image_url($custom_logo_id, 'full');
|
||||
?>
|
||||
<header>
|
||||
<?php if ($logo_url) : ?>
|
||||
<img src="<?php echo $logo_url; ?>" alt="<?php echo $site_name; ?>" />
|
||||
<?php endif; ?>
|
||||
<h1><?php echo $site_name; ?></h1>
|
||||
<p><?php echo $site_desc; ?></p>
|
||||
</header>
|
||||
```
|
||||
|
||||
```astro
|
||||
---
|
||||
// Astro - using EmDash site settings
|
||||
import { getSiteSettings } from "emdash";
|
||||
|
||||
const settings = await getSiteSettings();
|
||||
---
|
||||
<header>
|
||||
{settings.logo?.url && (
|
||||
<img src={settings.logo.url} alt={settings.logo.alt || settings.title} />
|
||||
)}
|
||||
<h1>{settings.title}</h1>
|
||||
{settings.tagline && <p>{settings.tagline}</p>}
|
||||
</header>
|
||||
```
|
||||
|
||||
## Comments
|
||||
|
||||
```php
|
||||
// WordPress
|
||||
<?php
|
||||
if (comments_open() || get_comments_number()) :
|
||||
comments_template();
|
||||
endif;
|
||||
?>
|
||||
```
|
||||
|
||||
EmDash doesn't include comments. Options:
|
||||
|
||||
1. **Giscus** - GitHub Discussions-based
|
||||
2. **Disqus** - Third-party
|
||||
3. **Custom** - Build with EmDash collections
|
||||
|
||||
```astro
|
||||
---
|
||||
// Astro with Giscus
|
||||
---
|
||||
<script src="https://giscus.app/client.js"
|
||||
data-repo="your/repo"
|
||||
data-repo-id="..."
|
||||
data-category="Comments"
|
||||
data-category-id="..."
|
||||
data-mapping="pathname"
|
||||
crossorigin="anonymous"
|
||||
async>
|
||||
</script>
|
||||
```
|
||||
|
||||
## Search
|
||||
|
||||
```php
|
||||
// WordPress
|
||||
<?php get_search_form(); ?>
|
||||
|
||||
// search.php
|
||||
<?php if (have_posts()) : ?>
|
||||
<h1>Search Results for: <?php the_search_query(); ?></h1>
|
||||
<?php while (have_posts()) : the_post(); ?>
|
||||
<!-- results -->
|
||||
<?php endwhile; ?>
|
||||
<?php else : ?>
|
||||
<p>No results found.</p>
|
||||
<?php endif; ?>
|
||||
```
|
||||
|
||||
```astro
|
||||
---
|
||||
// Astro pages/search.astro
|
||||
import { getEmDashCollection } from "emdash";
|
||||
import Base from "../layouts/Base.astro";
|
||||
|
||||
const query = Astro.url.searchParams.get('q') || '';
|
||||
let results = [];
|
||||
|
||||
if (query) {
|
||||
// Note: Full-text search depends on EmDash implementation
|
||||
const { entries: posts } = await getEmDashCollection("posts");
|
||||
results = posts.filter(p =>
|
||||
p.data.title.toLowerCase().includes(query.toLowerCase())
|
||||
);
|
||||
}
|
||||
---
|
||||
<Base title={`Search: ${query}`}>
|
||||
<form action="/search" method="get">
|
||||
<input type="search" name="q" value={query} />
|
||||
<button type="submit">Search</button>
|
||||
</form>
|
||||
|
||||
{query && (
|
||||
<h1>Search Results for: {query}</h1>
|
||||
{results.length > 0 ? (
|
||||
results.map(post => (
|
||||
<!-- results -->
|
||||
))
|
||||
) : (
|
||||
<p>No results found.</p>
|
||||
)}
|
||||
)}
|
||||
</Base>
|
||||
```
|
||||
|
||||
## Custom Fields (ACF-style)
|
||||
|
||||
```php
|
||||
// WordPress with ACF
|
||||
<?php
|
||||
$subtitle = get_field('subtitle');
|
||||
$gallery = get_field('gallery');
|
||||
?>
|
||||
<h2><?php echo $subtitle; ?></h2>
|
||||
<div class="gallery">
|
||||
<?php foreach ($gallery as $image) : ?>
|
||||
<img src="<?php echo $image['url']; ?>" />
|
||||
<?php endforeach; ?>
|
||||
</div>
|
||||
```
|
||||
|
||||
```astro
|
||||
---
|
||||
// Astro - fields are on post.data
|
||||
const { subtitle, gallery } = post.data;
|
||||
---
|
||||
<h2>{subtitle}</h2>
|
||||
<div class="gallery">
|
||||
{gallery?.map(image => (
|
||||
<img src={image.url} />
|
||||
))}
|
||||
</div>
|
||||
```
|
||||
|
||||
## Date Formatting
|
||||
|
||||
```php
|
||||
// WordPress
|
||||
<?php echo get_the_date('F j, Y'); ?> // January 23, 2025
|
||||
<?php echo human_time_diff(get_the_time('U'), current_time('timestamp')); ?> ago
|
||||
```
|
||||
|
||||
```astro
|
||||
---
|
||||
// Astro
|
||||
const date = post.data.publishedAt;
|
||||
const formatted = date?.toLocaleDateString('en-US', {
|
||||
year: 'numeric',
|
||||
month: 'long',
|
||||
day: 'numeric',
|
||||
});
|
||||
|
||||
// For relative time
|
||||
const rtf = new Intl.RelativeTimeFormat('en', { numeric: 'auto' });
|
||||
const diff = date ? Date.now() - date.getTime() : 0;
|
||||
const days = Math.floor(diff / (1000 * 60 * 60 * 24));
|
||||
const relative = rtf.format(-days, 'day');
|
||||
---
|
||||
<time datetime={date?.toISOString()}>{formatted}</time>
|
||||
<span>{relative}</span>
|
||||
```
|
||||
123
skills/wordpress-theme-to-emdash/scaffold/CHECKLIST.md
Normal file
123
skills/wordpress-theme-to-emdash/scaffold/CHECKLIST.md
Normal file
@@ -0,0 +1,123 @@
|
||||
# Theme Porting Checklist
|
||||
|
||||
Use this checklist to track progress when porting a WordPress theme to EmDash.
|
||||
|
||||
## Phase 1: Discovery & Reference Capture
|
||||
|
||||
- [ ] Theme source downloaded and unzipped
|
||||
- [ ] Demo site URL identified
|
||||
- [ ] Created `discovery/` folder structure:
|
||||
- [ ] `discovery/screenshots/`
|
||||
- [ ] `discovery/images/`
|
||||
- [ ] `discovery/notes.md`
|
||||
- [ ] Identified all page types in demo
|
||||
- [ ] Screenshots captured:
|
||||
- [ ] Homepage (`discovery/screenshots/homepage.png`)
|
||||
- [ ] Single post (`discovery/screenshots/single-post.png`)
|
||||
- [ ] Blog archive (`discovery/screenshots/archive.png`)
|
||||
- [ ] Category archive (`discovery/screenshots/category.png`)
|
||||
- [ ] Static page (`discovery/screenshots/page.png`)
|
||||
- [ ] 404 page (`discovery/screenshots/404.png`)
|
||||
- [ ] Sample images downloaded to `discovery/images/`
|
||||
- [ ] Design notes documented in `discovery/notes.md`:
|
||||
- [ ] Colors (background, text, primary, accent, borders)
|
||||
- [ ] Typography (font families, sizes, line heights)
|
||||
- [ ] Layout (content width, header height, sidebar position)
|
||||
- [ ] Special components to recreate
|
||||
|
||||
## Phase 2: Design Extraction
|
||||
|
||||
- [ ] CSS variables defined in `src/styles/global.css`:
|
||||
- [ ] Color palette (`--color-base`, `--color-contrast`, `--color-primary`, etc.)
|
||||
- [ ] Typography (`--font-body`, `--font-heading`, `--font-mono`)
|
||||
- [ ] Font sizes (`--text-sm` through `--text-5xl`)
|
||||
- [ ] Spacing scale (`--space-1` through `--space-24`)
|
||||
- [ ] Layout (`--content-width`, `--wide-width`, `--header-height`)
|
||||
- [ ] Fonts loading correctly (Google Fonts or local)
|
||||
- [ ] Color scheme matches original demo
|
||||
- [ ] Responsive breakpoints defined
|
||||
|
||||
## Phase 3: Template Conversion
|
||||
|
||||
- [ ] Base layout created (`src/layouts/Base.astro`)
|
||||
- [ ] Homepage (`src/pages/index.astro`)
|
||||
- [ ] Single post (`src/pages/posts/[slug].astro`)
|
||||
- [ ] Blog archive (`src/pages/posts/index.astro`)
|
||||
- [ ] Category archive (`src/pages/categories/[slug].astro`)
|
||||
- [ ] Tag archive (`src/pages/tags/[slug].astro`)
|
||||
- [ ] Static pages (`src/pages/pages/[slug].astro`)
|
||||
- [ ] 404 page (`src/pages/404.astro`)
|
||||
- [ ] Reusable components extracted (PostCard, etc.)
|
||||
|
||||
## Phase 4: Dynamic Features
|
||||
|
||||
- [ ] Site settings configured:
|
||||
- [ ] Title and tagline
|
||||
- [ ] Logo (if applicable)
|
||||
- [ ] Favicon
|
||||
- [ ] Navigation menus:
|
||||
- [ ] Primary menu
|
||||
- [ ] Footer menu (if applicable)
|
||||
- [ ] Mobile menu (if different)
|
||||
- [ ] Taxonomies:
|
||||
- [ ] Categories
|
||||
- [ ] Tags
|
||||
- [ ] Custom taxonomies (if any)
|
||||
- [ ] Widget areas (if applicable):
|
||||
- [ ] Sidebar
|
||||
- [ ] Footer widgets
|
||||
|
||||
## Phase 5: Create Seed File
|
||||
|
||||
- [ ] Seed file created (`.emdash/seed.json`)
|
||||
- [ ] Collections defined with all fields
|
||||
- [ ] Taxonomies defined with sample terms
|
||||
- [ ] Menus defined with items
|
||||
- [ ] Sample content created:
|
||||
- [ ] Posts (3-5 with varied content)
|
||||
- [ ] Pages (About, Contact, etc.)
|
||||
- [ ] Images use `$media` syntax with `discovery/images/` files
|
||||
- [ ] Seed validates: `emdash seed --validate`
|
||||
|
||||
## Phase 6: Verify & Iterate
|
||||
|
||||
- [ ] Seed applied successfully: `emdash seed`
|
||||
- [ ] Dev server running: `pnpm dev`
|
||||
- [ ] Output screenshots captured to `output/`:
|
||||
- [ ] Homepage
|
||||
- [ ] Single post
|
||||
- [ ] Blog archive
|
||||
- [ ] Category archive
|
||||
- [ ] Static page
|
||||
- [ ] 404 page
|
||||
- [ ] Visual comparison completed for each page
|
||||
- [ ] Differences identified and fixed
|
||||
- [ ] Production build succeeds: `pnpm build`
|
||||
|
||||
## License Compliance
|
||||
|
||||
- [ ] `README.md` credits original theme
|
||||
|
||||
If the original theme is GPL-licensed:
|
||||
|
||||
- [ ] `LICENSE` file added (GPL-2.0 text)
|
||||
- [ ] `package.json` has `"license": "GPL-2.0-or-later"`
|
||||
|
||||
## Final Review
|
||||
|
||||
- [ ] All pages render without errors
|
||||
- [ ] Mobile responsive design works
|
||||
- [ ] Navigation works on all pages
|
||||
- [ ] Images load correctly
|
||||
- [ ] Typography matches design intent
|
||||
- [ ] Colors match design intent
|
||||
- [ ] No console errors in browser
|
||||
|
||||
## No Hard-Coded Content
|
||||
|
||||
- [ ] Site title uses `settings.title`, not hard-coded string
|
||||
- [ ] Site tagline uses `settings.tagline`, not hard-coded string
|
||||
- [ ] Logo uses `settings.logo`, not hard-coded path
|
||||
- [ ] Navigation uses `getMenu()`, not hard-coded `<a>` tags
|
||||
- [ ] Footer content uses site settings or widget areas
|
||||
- [ ] No placeholder text like "My Blog" or "Lorem ipsum" in templates
|
||||
101
skills/wordpress-theme-to-emdash/scaffold/README.md
Normal file
101
skills/wordpress-theme-to-emdash/scaffold/README.md
Normal file
@@ -0,0 +1,101 @@
|
||||
# EmDash Theme Scaffold
|
||||
|
||||
This is a minimal, working EmDash theme that demonstrates correct patterns for:
|
||||
|
||||
- **Site settings** - Use `getSiteSettings()` for title, tagline, logo - never hard-code
|
||||
- **Menus** - Use `getMenu()` for navigation - never hard-code links
|
||||
- **Image fields** - Always access `.src` and `.alt`, never the field directly
|
||||
- **Taxonomy terms** - Use `getEntryTerms()` without a db parameter
|
||||
- **PortableText** - Use the `<PortableText>` component from `emdash/ui`
|
||||
|
||||
## Critical: No Hard-Coded Content
|
||||
|
||||
The theme is a shell that displays CMS content. Never hard-code:
|
||||
|
||||
- Site title or tagline (use `settings.title`, `settings.tagline`)
|
||||
- Navigation links (use `getMenu("primary")`)
|
||||
- Logo or favicon (use `settings.logo`, `settings.favicon`)
|
||||
- Footer content (use site settings or widget areas)
|
||||
|
||||
## Usage
|
||||
|
||||
When porting a WordPress theme:
|
||||
|
||||
1. Copy this scaffold to your theme directory
|
||||
2. Run `pnpm install` from monorepo root
|
||||
3. Verify it builds: `pnpm --filter your-theme build`
|
||||
4. Use these templates as reference for correct API usage
|
||||
|
||||
## Key Patterns
|
||||
|
||||
### Image Fields
|
||||
|
||||
```astro
|
||||
{/* CORRECT - check .src exists */}
|
||||
{post.data.featured_image?.src && (
|
||||
<img
|
||||
src={post.data.featured_image.src}
|
||||
alt={post.data.featured_image.alt || post.data.title}
|
||||
/>
|
||||
)}
|
||||
|
||||
{/* WRONG - field is an object, not a string */}
|
||||
{post.data.featured_image && (
|
||||
<img src={post.data.featured_image} /> // Renders [object Object]
|
||||
)}
|
||||
```
|
||||
|
||||
### Taxonomy Terms
|
||||
|
||||
```astro
|
||||
{/* CORRECT - no db parameter */}
|
||||
const categories = await getEntryTerms("posts", post.id, "categories");
|
||||
|
||||
{/* WRONG - db is not a parameter */}
|
||||
const categories = await getEntryTerms("posts", post.id, "categories", db);
|
||||
```
|
||||
|
||||
### Seed File Images
|
||||
|
||||
```json
|
||||
{
|
||||
"featured_image": {
|
||||
"$media": {
|
||||
"url": "https://example.com/image.jpg",
|
||||
"alt": "Description",
|
||||
"filename": "image.jpg"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
At runtime, this becomes `{ src: "...", alt: "..." }`.
|
||||
|
||||
## Files
|
||||
|
||||
```
|
||||
scaffold/
|
||||
├── package.json # Working dependency versions
|
||||
├── astro.config.mjs # Minimal config
|
||||
├── tsconfig.json
|
||||
├── src/
|
||||
│ ├── env.d.ts
|
||||
│ ├── live.config.ts # Collection loader setup
|
||||
│ ├── styles/global.css # Minimal styles with comments
|
||||
│ ├── layouts/Base.astro # Header, footer, menus
|
||||
│ ├── components/
|
||||
│ │ └── PostCard.astro # Image field handling example
|
||||
│ └── pages/
|
||||
│ ├── index.astro
|
||||
│ ├── 404.astro
|
||||
│ ├── posts/
|
||||
│ │ ├── index.astro
|
||||
│ │ └── [slug].astro # Taxonomy terms example
|
||||
│ ├── pages/[slug].astro
|
||||
│ ├── categories/[slug].astro
|
||||
│ └── tags/[slug].astro
|
||||
├── public/
|
||||
│ └── favicon.svg
|
||||
└── .emdash/
|
||||
└── seed.json # All field types demonstrated
|
||||
```
|
||||
27
skills/wordpress-theme-to-emdash/scaffold/astro.config.mjs
Normal file
27
skills/wordpress-theme-to-emdash/scaffold/astro.config.mjs
Normal file
@@ -0,0 +1,27 @@
|
||||
// @ts-check
|
||||
import node from "@astrojs/node";
|
||||
import react from "@astrojs/react";
|
||||
import { defineConfig } from "astro/config";
|
||||
import emdash from "emdash/astro";
|
||||
import { sqlite } from "emdash/db";
|
||||
|
||||
export default defineConfig({
|
||||
output: "server",
|
||||
adapter: node({ mode: "standalone" }),
|
||||
integrations: [
|
||||
react(),
|
||||
emdash({
|
||||
database: sqlite({ url: "file:./data.db" }),
|
||||
}),
|
||||
],
|
||||
// Optional: Add custom fonts
|
||||
// experimental: {
|
||||
// fonts: [
|
||||
// {
|
||||
// provider: "google",
|
||||
// family: "Inter",
|
||||
// weights: [400, 500, 600, 700],
|
||||
// },
|
||||
// ],
|
||||
// },
|
||||
});
|
||||
26
skills/wordpress-theme-to-emdash/scaffold/package.json
Normal file
26
skills/wordpress-theme-to-emdash/scaffold/package.json
Normal file
@@ -0,0 +1,26 @@
|
||||
{
|
||||
"name": "@emdashcms/theme-scaffold",
|
||||
"type": "module",
|
||||
"version": "0.0.1",
|
||||
"private": true,
|
||||
"scripts": {
|
||||
"dev": "astro dev",
|
||||
"build": "astro build",
|
||||
"preview": "astro preview",
|
||||
"check": "astro check"
|
||||
},
|
||||
"dependencies": {
|
||||
"@astrojs/node": "^10.0.0-beta.0",
|
||||
"@astrojs/react": "^5.0.0-beta.1",
|
||||
"astro": "^6.0.0-beta.0",
|
||||
"better-sqlite3": "^11.10.0",
|
||||
"emdash": "workspace:*",
|
||||
"react": "^19.1.0",
|
||||
"react-dom": "^19.1.0"
|
||||
},
|
||||
"devDependencies": {
|
||||
"@astrojs/check": "^0.9.6",
|
||||
"@types/node": "^24.10.9",
|
||||
"typescript": "^5.9.3"
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,4 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32">
|
||||
<rect width="32" height="32" fill="#0066cc" rx="6"/>
|
||||
<text x="16" y="22" font-family="system-ui, sans-serif" font-size="16" font-weight="600" fill="white" text-anchor="middle">E</text>
|
||||
</svg>
|
||||
|
After Width: | Height: | Size: 257 B |
@@ -0,0 +1,52 @@
|
||||
---
|
||||
/**
|
||||
* PostCard Component
|
||||
*
|
||||
* Displays a post preview with optional featured image.
|
||||
*
|
||||
* IMPORTANT: Image fields are objects with { src, alt }, not strings!
|
||||
*/
|
||||
|
||||
interface Props {
|
||||
title: string;
|
||||
href: string;
|
||||
date?: string;
|
||||
excerpt?: string;
|
||||
// Image fields from EmDash are always { src?: string, alt?: string }
|
||||
featuredImage?: {
|
||||
src?: string;
|
||||
alt?: string;
|
||||
};
|
||||
}
|
||||
|
||||
const { title, href, date, excerpt, featuredImage } = Astro.props;
|
||||
|
||||
const formattedDate = date
|
||||
? new Date(date).toLocaleDateString("en-US", {
|
||||
year: "numeric",
|
||||
month: "long",
|
||||
day: "numeric",
|
||||
})
|
||||
: null;
|
||||
---
|
||||
|
||||
<article class="post-card">
|
||||
{/* Check featuredImage.src, not just featuredImage */}
|
||||
{
|
||||
featuredImage?.src && (
|
||||
<a href={href} class="post-card-image">
|
||||
<img src={featuredImage.src} alt={featuredImage.alt || title} loading="lazy" />
|
||||
</a>
|
||||
)
|
||||
}
|
||||
|
||||
<div class="post-card-content">
|
||||
<h2 class="post-card-title">
|
||||
<a href={href}>{title}</a>
|
||||
</h2>
|
||||
|
||||
{formattedDate && <p class="post-card-meta">{formattedDate}</p>}
|
||||
|
||||
{excerpt && <p class="post-card-excerpt">{excerpt}</p>}
|
||||
</div>
|
||||
</article>
|
||||
2
skills/wordpress-theme-to-emdash/scaffold/src/env.d.ts
vendored
Normal file
2
skills/wordpress-theme-to-emdash/scaffold/src/env.d.ts
vendored
Normal file
@@ -0,0 +1,2 @@
|
||||
/// <reference path="../.astro/types.d.ts" />
|
||||
/// <reference types="astro/client" />
|
||||
@@ -0,0 +1,72 @@
|
||||
---
|
||||
/**
|
||||
* Base Layout
|
||||
*
|
||||
* Main layout with header, footer, and navigation from EmDash menus.
|
||||
*/
|
||||
|
||||
import { getMenu, getSiteSettings } from "emdash";
|
||||
import "../styles/global.css";
|
||||
|
||||
interface Props {
|
||||
title?: string;
|
||||
description?: string;
|
||||
}
|
||||
|
||||
const { title, description } = Astro.props;
|
||||
|
||||
// These APIs automatically get the database from the Astro context
|
||||
const settings = await getSiteSettings();
|
||||
const primaryMenu = await getMenu("primary");
|
||||
const footerMenu = await getMenu("footer");
|
||||
|
||||
const siteTitle = settings.title || "My Site";
|
||||
const pageTitle = title ? `${title} | ${siteTitle}` : siteTitle;
|
||||
---
|
||||
|
||||
<!doctype html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="UTF-8" />
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
|
||||
<title>{pageTitle}</title>
|
||||
{description && <meta name="description" content={description} />}
|
||||
<link rel="icon" type="image/svg+xml" href="/favicon.svg" />
|
||||
</head>
|
||||
<body>
|
||||
<header class="site-header">
|
||||
<div class="container">
|
||||
<a href="/" class="site-title">{siteTitle}</a>
|
||||
|
||||
{
|
||||
primaryMenu && primaryMenu.items.length > 0 && (
|
||||
<nav class="site-nav">
|
||||
{primaryMenu.items.map((item) => (
|
||||
<a href={item.url}>{item.label}</a>
|
||||
))}
|
||||
</nav>
|
||||
)
|
||||
}
|
||||
</div>
|
||||
</header>
|
||||
|
||||
<main>
|
||||
<slot />
|
||||
</main>
|
||||
|
||||
<footer class="site-footer">
|
||||
<div class="container">
|
||||
{
|
||||
footerMenu && footerMenu.items.length > 0 && (
|
||||
<nav class="footer-nav">
|
||||
{footerMenu.items.map((item) => (
|
||||
<a href={item.url}>{item.label}</a>
|
||||
))}
|
||||
</nav>
|
||||
)
|
||||
}
|
||||
<p class="copyright">© {new Date().getFullYear()} {siteTitle}</p>
|
||||
</div>
|
||||
</footer>
|
||||
</body>
|
||||
</html>
|
||||
19
skills/wordpress-theme-to-emdash/scaffold/src/live.config.ts
Normal file
19
skills/wordpress-theme-to-emdash/scaffold/src/live.config.ts
Normal file
@@ -0,0 +1,19 @@
|
||||
/**
|
||||
* EmDash Live Config
|
||||
*
|
||||
* This file defines your content collections using EmDash's loader.
|
||||
* It replaces Astro's content collections for CMS-managed content.
|
||||
*/
|
||||
|
||||
import { defineCollection } from "astro:content";
|
||||
import { emdashLoader } from "emdash";
|
||||
|
||||
// Posts collection - loaded from EmDash CMS
|
||||
export const collections = {
|
||||
posts: defineCollection({
|
||||
loader: emdashLoader({ collection: "posts" }),
|
||||
}),
|
||||
pages: defineCollection({
|
||||
loader: emdashLoader({ collection: "pages" }),
|
||||
}),
|
||||
};
|
||||
@@ -0,0 +1,17 @@
|
||||
---
|
||||
/**
|
||||
* 404 Page
|
||||
*/
|
||||
|
||||
import Base from "../layouts/Base.astro";
|
||||
---
|
||||
|
||||
<Base title="Page Not Found">
|
||||
<div class="container">
|
||||
<div class="content-width" style="text-align: center; padding: 4rem 0;">
|
||||
<h1>404</h1>
|
||||
<p class="text-muted">The page you're looking for doesn't exist.</p>
|
||||
<p><a href="/">Go home</a></p>
|
||||
</div>
|
||||
</div>
|
||||
</Base>
|
||||
@@ -0,0 +1,57 @@
|
||||
---
|
||||
/**
|
||||
* Category Archive
|
||||
*
|
||||
* Demonstrates:
|
||||
* - getTerm for fetching taxonomy term details
|
||||
* - getEntriesByTerm for entries with a specific term
|
||||
*/
|
||||
|
||||
import { getTerm, getEntriesByTerm } from "emdash";
|
||||
import Base from "../../layouts/Base.astro";
|
||||
import PostCard from "../../components/PostCard.astro";
|
||||
|
||||
const { slug } = Astro.params;
|
||||
|
||||
const category = await getTerm("categories", slug!);
|
||||
const posts = await getEntriesByTerm("posts", "categories", slug!);
|
||||
|
||||
if (!category) {
|
||||
return Astro.redirect("/404");
|
||||
}
|
||||
---
|
||||
|
||||
<Base title={category.label}>
|
||||
<div class="container">
|
||||
<div class="content-width">
|
||||
<header class="archive-header">
|
||||
<h1>{category.label}</h1>
|
||||
</header>
|
||||
|
||||
{
|
||||
posts.length > 0 ? (
|
||||
<div class="posts-list">
|
||||
{posts.map((post) => (
|
||||
<PostCard
|
||||
title={post.data.title}
|
||||
href={`/posts/${post.data.slug || post.id}`}
|
||||
date={post.data.published_at}
|
||||
excerpt={post.data.excerpt}
|
||||
featuredImage={
|
||||
post.data.featured_image?.src
|
||||
? {
|
||||
src: post.data.featured_image.src,
|
||||
alt: post.data.featured_image.alt || post.data.title,
|
||||
}
|
||||
: undefined
|
||||
}
|
||||
/>
|
||||
))}
|
||||
</div>
|
||||
) : (
|
||||
<p class="text-muted">No posts in this category.</p>
|
||||
)
|
||||
}
|
||||
</div>
|
||||
</div>
|
||||
</Base>
|
||||
@@ -0,0 +1,54 @@
|
||||
---
|
||||
/**
|
||||
* Homepage / Blog Index
|
||||
*
|
||||
* Demonstrates:
|
||||
* - getEmDashCollection for listing entries
|
||||
* - Passing image fields correctly to components
|
||||
*/
|
||||
|
||||
import { getEmDashCollection } from "emdash";
|
||||
import Base from "../layouts/Base.astro";
|
||||
import PostCard from "../components/PostCard.astro";
|
||||
|
||||
const { entries: posts } = await getEmDashCollection("posts", {
|
||||
status: "published",
|
||||
limit: 10,
|
||||
});
|
||||
---
|
||||
|
||||
<Base>
|
||||
<div class="container">
|
||||
<div class="content-width">
|
||||
{
|
||||
posts.length > 0 ? (
|
||||
<div class="posts-list">
|
||||
{posts.map((post) => (
|
||||
<PostCard
|
||||
title={post.data.title}
|
||||
href={`/posts/${post.data.slug || post.id}`}
|
||||
date={post.data.published_at}
|
||||
excerpt={post.data.excerpt}
|
||||
{
|
||||
/*
|
||||
IMPORTANT: featured_image is { src, alt }, not a string!
|
||||
Pass the whole object, or extract src/alt explicitly.
|
||||
*/ }
|
||||
featuredImage={
|
||||
post.data.featured_image?.src
|
||||
? {
|
||||
src: post.data.featured_image.src,
|
||||
alt: post.data.featured_image.alt || post.data.title,
|
||||
}
|
||||
: undefined
|
||||
}
|
||||
/>
|
||||
))}
|
||||
</div>
|
||||
) : (
|
||||
<p class="text-muted">No posts yet.</p>
|
||||
)
|
||||
}
|
||||
</div>
|
||||
</div>
|
||||
</Base>
|
||||
@@ -0,0 +1,35 @@
|
||||
---
|
||||
/**
|
||||
* Single Page
|
||||
*/
|
||||
|
||||
import { getEmDashEntry } from "emdash";
|
||||
import { PortableText } from "emdash/ui";
|
||||
import Base from "../../layouts/Base.astro";
|
||||
|
||||
const { slug } = Astro.params;
|
||||
|
||||
const { entry: page, error } = await getEmDashEntry("pages", slug!);
|
||||
|
||||
if (error) {
|
||||
return new Response("Server error", { status: 500 });
|
||||
}
|
||||
|
||||
if (!page) {
|
||||
return Astro.redirect("/404");
|
||||
}
|
||||
---
|
||||
|
||||
<Base title={page.data.title}>
|
||||
<article class="container">
|
||||
<div class="content-width">
|
||||
<header class="page-header">
|
||||
<h1>{page.data.title}</h1>
|
||||
</header>
|
||||
|
||||
<div class="prose">
|
||||
{page.data.content && <PortableText value={page.data.content} />}
|
||||
</div>
|
||||
</div>
|
||||
</article>
|
||||
</Base>
|
||||
@@ -0,0 +1,99 @@
|
||||
---
|
||||
/**
|
||||
* Single Post
|
||||
*
|
||||
* Demonstrates:
|
||||
* - getEmDashEntry for fetching a single entry
|
||||
* - getEntryTerms for taxonomy terms (NO db parameter!)
|
||||
* - PortableText component for rich content
|
||||
* - Proper image field access
|
||||
*/
|
||||
|
||||
import { getEmDashEntry, getEntryTerms } from "emdash";
|
||||
import { PortableText } from "emdash/ui";
|
||||
import Base from "../../layouts/Base.astro";
|
||||
|
||||
const { slug } = Astro.params;
|
||||
|
||||
const { entry: post, error } = await getEmDashEntry("posts", slug!);
|
||||
|
||||
if (error) {
|
||||
return new Response("Server error", { status: 500 });
|
||||
}
|
||||
|
||||
if (!post) {
|
||||
return Astro.redirect("/404");
|
||||
}
|
||||
|
||||
// Get taxonomy terms - NOTE: no db parameter!
|
||||
const categories = await getEntryTerms("posts", post.id, "categories");
|
||||
const tags = await getEntryTerms("posts", post.id, "tags");
|
||||
|
||||
const formattedDate = post.data.published_at
|
||||
? new Date(post.data.published_at).toLocaleDateString("en-US", {
|
||||
year: "numeric",
|
||||
month: "long",
|
||||
day: "numeric",
|
||||
})
|
||||
: null;
|
||||
---
|
||||
|
||||
<Base title={post.data.title} description={post.data.excerpt}>
|
||||
<article class="container">
|
||||
<div class="content-width">
|
||||
<header class="post-header">
|
||||
<h1>{post.data.title}</h1>
|
||||
|
||||
<div class="post-meta">
|
||||
{
|
||||
formattedDate && (
|
||||
<time datetime={post.data.published_at}>{formattedDate}</time>
|
||||
)
|
||||
}
|
||||
|
||||
{
|
||||
categories.length > 0 && (
|
||||
<span class="post-categories">
|
||||
in{" "}
|
||||
{categories.map((cat, i) => (
|
||||
<>
|
||||
{i > 0 && ", "}
|
||||
<a href={`/categories/${cat.slug}`}>{cat.label}</a>
|
||||
</>
|
||||
))}
|
||||
</span>
|
||||
)
|
||||
}
|
||||
</div>
|
||||
</header>
|
||||
|
||||
{/* IMPORTANT: Check .src, not just the field */}
|
||||
{
|
||||
post.data.featured_image?.src && (
|
||||
<div class="post-featured-image">
|
||||
<img
|
||||
src={post.data.featured_image.src}
|
||||
alt={post.data.featured_image.alt || post.data.title}
|
||||
/>
|
||||
</div>
|
||||
)
|
||||
}
|
||||
|
||||
<div class="prose">
|
||||
{post.data.content && <PortableText value={post.data.content} />}
|
||||
</div>
|
||||
|
||||
{
|
||||
tags.length > 0 && (
|
||||
<div class="post-tags">
|
||||
{tags.map((tag) => (
|
||||
<a href={`/tags/${tag.slug}`} class="tag">
|
||||
{tag.label}
|
||||
</a>
|
||||
))}
|
||||
</div>
|
||||
)
|
||||
}
|
||||
</div>
|
||||
</article>
|
||||
</Base>
|
||||
@@ -0,0 +1,48 @@
|
||||
---
|
||||
/**
|
||||
* Posts Archive
|
||||
*/
|
||||
|
||||
import { getEmDashCollection } from "emdash";
|
||||
import Base from "../../layouts/Base.astro";
|
||||
import PostCard from "../../components/PostCard.astro";
|
||||
|
||||
const { entries: posts } = await getEmDashCollection("posts", {
|
||||
status: "published",
|
||||
});
|
||||
---
|
||||
|
||||
<Base title="Blog">
|
||||
<div class="container">
|
||||
<div class="content-width">
|
||||
<header class="archive-header">
|
||||
<h1>Blog</h1>
|
||||
</header>
|
||||
|
||||
{
|
||||
posts.length > 0 ? (
|
||||
<div class="posts-list">
|
||||
{posts.map((post) => (
|
||||
<PostCard
|
||||
title={post.data.title}
|
||||
href={`/posts/${post.data.slug || post.id}`}
|
||||
date={post.data.published_at}
|
||||
excerpt={post.data.excerpt}
|
||||
featuredImage={
|
||||
post.data.featured_image?.src
|
||||
? {
|
||||
src: post.data.featured_image.src,
|
||||
alt: post.data.featured_image.alt || post.data.title,
|
||||
}
|
||||
: undefined
|
||||
}
|
||||
/>
|
||||
))}
|
||||
</div>
|
||||
) : (
|
||||
<p class="text-muted">No posts found.</p>
|
||||
)
|
||||
}
|
||||
</div>
|
||||
</div>
|
||||
</Base>
|
||||
@@ -0,0 +1,54 @@
|
||||
---
|
||||
/**
|
||||
* Tag Archive
|
||||
*/
|
||||
|
||||
import { getTerm, getEntriesByTerm } from "emdash";
|
||||
import Base from "../../layouts/Base.astro";
|
||||
import PostCard from "../../components/PostCard.astro";
|
||||
|
||||
const { slug } = Astro.params;
|
||||
|
||||
const tag = await getTerm("tags", slug!);
|
||||
const posts = await getEntriesByTerm("posts", "tags", slug!);
|
||||
|
||||
if (!tag) {
|
||||
return Astro.redirect("/404");
|
||||
}
|
||||
---
|
||||
|
||||
<Base title={`Tagged: ${tag.label}`}>
|
||||
<div class="container">
|
||||
<div class="content-width">
|
||||
<header class="archive-header">
|
||||
<p class="text-muted">Tagged</p>
|
||||
<h1>{tag.label}</h1>
|
||||
</header>
|
||||
|
||||
{
|
||||
posts.length > 0 ? (
|
||||
<div class="posts-list">
|
||||
{posts.map((post) => (
|
||||
<PostCard
|
||||
title={post.data.title}
|
||||
href={`/posts/${post.data.slug || post.id}`}
|
||||
date={post.data.published_at}
|
||||
excerpt={post.data.excerpt}
|
||||
featuredImage={
|
||||
post.data.featured_image?.src
|
||||
? {
|
||||
src: post.data.featured_image.src,
|
||||
alt: post.data.featured_image.alt || post.data.title,
|
||||
}
|
||||
: undefined
|
||||
}
|
||||
/>
|
||||
))}
|
||||
</div>
|
||||
) : (
|
||||
<p class="text-muted">No posts with this tag.</p>
|
||||
)
|
||||
}
|
||||
</div>
|
||||
</div>
|
||||
</Base>
|
||||
274
skills/wordpress-theme-to-emdash/scaffold/src/styles/global.css
Normal file
274
skills/wordpress-theme-to-emdash/scaffold/src/styles/global.css
Normal file
@@ -0,0 +1,274 @@
|
||||
/**
|
||||
* Global Styles - Scaffold Theme
|
||||
*
|
||||
* Minimal styles for demonstration. Replace with your theme's design tokens.
|
||||
*/
|
||||
|
||||
/* Reset */
|
||||
*,
|
||||
*::before,
|
||||
*::after {
|
||||
box-sizing: border-box;
|
||||
margin: 0;
|
||||
padding: 0;
|
||||
}
|
||||
|
||||
/* Variables - replace with your theme's tokens */
|
||||
:root {
|
||||
--color-text: #1a1a1a;
|
||||
--color-text-muted: #666;
|
||||
--color-bg: #fff;
|
||||
--color-border: #e5e5e5;
|
||||
--color-accent: #0066cc;
|
||||
|
||||
--font-body: system-ui, -apple-system, sans-serif;
|
||||
--font-mono: ui-monospace, monospace;
|
||||
|
||||
--space-sm: 0.5rem;
|
||||
--space-md: 1rem;
|
||||
--space-lg: 2rem;
|
||||
--space-xl: 4rem;
|
||||
|
||||
--content-width: 40rem;
|
||||
--container-width: 60rem;
|
||||
}
|
||||
|
||||
/* Base */
|
||||
html {
|
||||
font-family: var(--font-body);
|
||||
font-size: 16px;
|
||||
line-height: 1.6;
|
||||
color: var(--color-text);
|
||||
background: var(--color-bg);
|
||||
}
|
||||
|
||||
body {
|
||||
min-height: 100vh;
|
||||
display: flex;
|
||||
flex-direction: column;
|
||||
}
|
||||
|
||||
main {
|
||||
flex: 1;
|
||||
padding: var(--space-xl) var(--space-md);
|
||||
}
|
||||
|
||||
/* Layout */
|
||||
.container {
|
||||
max-width: var(--container-width);
|
||||
margin: 0 auto;
|
||||
padding: 0 var(--space-md);
|
||||
}
|
||||
|
||||
.content-width {
|
||||
max-width: var(--content-width);
|
||||
}
|
||||
|
||||
/* Header */
|
||||
.site-header {
|
||||
padding: var(--space-md) 0;
|
||||
border-bottom: 1px solid var(--color-border);
|
||||
}
|
||||
|
||||
.site-header .container {
|
||||
display: flex;
|
||||
align-items: center;
|
||||
justify-content: space-between;
|
||||
gap: var(--space-md);
|
||||
}
|
||||
|
||||
.site-title {
|
||||
font-size: 1.25rem;
|
||||
font-weight: 600;
|
||||
text-decoration: none;
|
||||
color: inherit;
|
||||
}
|
||||
|
||||
.site-nav {
|
||||
display: flex;
|
||||
gap: var(--space-md);
|
||||
}
|
||||
|
||||
.site-nav a {
|
||||
color: var(--color-text-muted);
|
||||
text-decoration: none;
|
||||
}
|
||||
|
||||
.site-nav a:hover {
|
||||
color: var(--color-text);
|
||||
}
|
||||
|
||||
/* Footer */
|
||||
.site-footer {
|
||||
padding: var(--space-lg) 0;
|
||||
border-top: 1px solid var(--color-border);
|
||||
color: var(--color-text-muted);
|
||||
font-size: 0.875rem;
|
||||
}
|
||||
|
||||
.footer-nav {
|
||||
display: flex;
|
||||
gap: var(--space-md);
|
||||
margin-bottom: var(--space-sm);
|
||||
}
|
||||
|
||||
.footer-nav a {
|
||||
color: inherit;
|
||||
}
|
||||
|
||||
/* Typography */
|
||||
h1,
|
||||
h2,
|
||||
h3,
|
||||
h4,
|
||||
h5,
|
||||
h6 {
|
||||
line-height: 1.3;
|
||||
margin-bottom: var(--space-sm);
|
||||
}
|
||||
|
||||
h1 {
|
||||
font-size: 2rem;
|
||||
}
|
||||
h2 {
|
||||
font-size: 1.5rem;
|
||||
}
|
||||
h3 {
|
||||
font-size: 1.25rem;
|
||||
}
|
||||
|
||||
p {
|
||||
margin-bottom: var(--space-md);
|
||||
}
|
||||
|
||||
a {
|
||||
color: var(--color-accent);
|
||||
}
|
||||
|
||||
code {
|
||||
font-family: var(--font-mono);
|
||||
font-size: 0.9em;
|
||||
background: var(--color-border);
|
||||
padding: 0.1em 0.3em;
|
||||
border-radius: 3px;
|
||||
}
|
||||
|
||||
/* Images */
|
||||
img {
|
||||
max-width: 100%;
|
||||
height: auto;
|
||||
display: block;
|
||||
}
|
||||
|
||||
/* Post Card */
|
||||
.post-card {
|
||||
margin-bottom: var(--space-lg);
|
||||
padding-bottom: var(--space-lg);
|
||||
border-bottom: 1px solid var(--color-border);
|
||||
}
|
||||
|
||||
.post-card:last-child {
|
||||
border-bottom: none;
|
||||
}
|
||||
|
||||
.post-card-image {
|
||||
margin-bottom: var(--space-md);
|
||||
}
|
||||
|
||||
.post-card-image img {
|
||||
border-radius: 4px;
|
||||
}
|
||||
|
||||
.post-card-title {
|
||||
font-size: 1.25rem;
|
||||
margin-bottom: var(--space-sm);
|
||||
}
|
||||
|
||||
.post-card-title a {
|
||||
color: inherit;
|
||||
text-decoration: none;
|
||||
}
|
||||
|
||||
.post-card-title a:hover {
|
||||
color: var(--color-accent);
|
||||
}
|
||||
|
||||
.post-card-meta {
|
||||
font-size: 0.875rem;
|
||||
color: var(--color-text-muted);
|
||||
margin-bottom: var(--space-sm);
|
||||
}
|
||||
|
||||
.post-card-excerpt {
|
||||
color: var(--color-text-muted);
|
||||
}
|
||||
|
||||
/* Single Post/Page */
|
||||
.post-header,
|
||||
.page-header {
|
||||
margin-bottom: var(--space-lg);
|
||||
}
|
||||
|
||||
.post-meta {
|
||||
font-size: 0.875rem;
|
||||
color: var(--color-text-muted);
|
||||
display: flex;
|
||||
gap: var(--space-md);
|
||||
flex-wrap: wrap;
|
||||
}
|
||||
|
||||
.post-featured-image {
|
||||
margin-bottom: var(--space-lg);
|
||||
}
|
||||
|
||||
.post-featured-image img {
|
||||
border-radius: 4px;
|
||||
}
|
||||
|
||||
/* Taxonomy terms */
|
||||
.post-categories a,
|
||||
.post-tags a {
|
||||
color: var(--color-text-muted);
|
||||
}
|
||||
|
||||
.post-tags {
|
||||
margin-top: var(--space-lg);
|
||||
display: flex;
|
||||
gap: var(--space-sm);
|
||||
flex-wrap: wrap;
|
||||
}
|
||||
|
||||
.tag {
|
||||
font-size: 0.875rem;
|
||||
padding: var(--space-sm) var(--space-md);
|
||||
background: var(--color-border);
|
||||
border-radius: 4px;
|
||||
text-decoration: none;
|
||||
color: var(--color-text-muted);
|
||||
}
|
||||
|
||||
.tag:hover {
|
||||
background: var(--color-text);
|
||||
color: var(--color-bg);
|
||||
}
|
||||
|
||||
/* Prose (PortableText content) */
|
||||
.prose > * + * {
|
||||
margin-top: var(--space-md);
|
||||
}
|
||||
|
||||
.prose h2,
|
||||
.prose h3,
|
||||
.prose h4 {
|
||||
margin-top: var(--space-lg);
|
||||
}
|
||||
|
||||
/* Archive header */
|
||||
.archive-header {
|
||||
margin-bottom: var(--space-lg);
|
||||
}
|
||||
|
||||
/* Utility */
|
||||
.text-muted {
|
||||
color: var(--color-text-muted);
|
||||
}
|
||||
8
skills/wordpress-theme-to-emdash/scaffold/tsconfig.json
Normal file
8
skills/wordpress-theme-to-emdash/scaffold/tsconfig.json
Normal file
@@ -0,0 +1,8 @@
|
||||
{
|
||||
"extends": "astro/tsconfigs/strict",
|
||||
"compilerOptions": {
|
||||
"strictNullChecks": true
|
||||
},
|
||||
"include": ["src/**/*", ".astro/**/*"],
|
||||
"exclude": ["node_modules", "dist"]
|
||||
}
|
||||
Reference in New Issue
Block a user