517 lines
10 KiB
Markdown
517 lines
10 KiB
Markdown
# 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>
|
|
```
|