### Install Dependencies and Start Dev Server

Source: https://docs.emdashcms.com/themes/creating-themes

Navigate to the test site directory, install dependencies, and start the development server to test your theme.

```bash
cd test-site
npm install
npm run dev
```

--------------------------------

### Setup Wizard UI Example

Source: https://docs.emdashcms.com/themes/overview

A visual representation of the EmDash Setup Wizard interface for initial site configuration.

```text
┌────────────────────────────────────────────────────────┐
│                                                        │
│                    ◆ EmDash                          │
│                                                        │
│              Welcome to your new site                  │
│                                                        │
│  Site Title:     [My Awesome Blog                    ] │
│  Tagline:        [Thoughts and ideas                 ] │
│                                                        │
│  Admin Email:    [admin@example.com                  ] │
│  Admin Password: [••••••••••••                       ] │
│                                                        │
│  ☑ Include sample content                              │
│                                                        │
│                   [Create Site →]                      │
│                                                        │
│  Template: Blog Starter                                │
│  Creates: 2 collections, 3 pages, 1 post              │
└────────────────────────────────────────────────────────┘

```

--------------------------------

### Start EmDash Development Server

Source: https://docs.emdashcms.com/reference/cli

Start the development server with automatic database setup. Optionally generate types from a remote instance before starting.

```bash
npx emdash dev [options]
```

```bash
# Start dev server
npx emdash dev

# Custom port
npx emdash dev --port 3000

# Generate types from remote before starting
npx emdash dev --types
```

--------------------------------

### Initialize Plugin Settings on Install

Source: https://docs.emdashcms.com/reference/hooks

This hook runs when a plugin is first installed. It's used for initial setup tasks such as creating storage collections or seeding data. This example initializes default settings in KV storage.

```javascript
hooks: {
  "plugin:install": async (event, ctx) => {
    // Initialize default settings
    await ctx.kv.set("settings:enabled", true);
    await ctx.kv.set("settings:threshold", 100);


    ctx.log.info("Plugin installed successfully");
  },
}
```

--------------------------------

### Post-Installation Steps

Source: https://docs.emdashcms.com/themes/overview

Navigate to the site directory, install dependencies, and start the development server.

```bash
cd my-site
npm install
npm run dev

```

--------------------------------

### Start EmDash Demo Locally

Source: https://docs.emdashcms.com/contributing

Navigate to the simple demo directory and start the development server using pnpm. The setup wizard will run automatically on the first launch.

```bash
cd demos/simple
pnpm dev
```

--------------------------------

### Plugin Install Hook

Source: https://docs.emdashcms.com/plugins/hooks

Example of a 'plugin:install' hook that runs once when a plugin is added, seeding default data using KV and storage.

```javascript
"plugin:install": async (_event, ctx) => {
  ctx.log.info("Installing plugin...");


  // Seed default data
  await ctx.kv.set("settings:enabled", true);
  await ctx.storage.items!.put("default", { name: "Default Item" });
}
```

--------------------------------

### Get Setup Status API Endpoint

Source: https://docs.emdashcms.com/reference/rest-api

Checks the current setup status of the system, indicating if setup is complete and if users exist.

```http
GET /_emdash/api/setup/status
```

--------------------------------

### emdash dev

Source: https://docs.emdashcms.com/reference/cli

Start the development server with automatic database setup.

```APIDOC
## `emdash dev`

Start the development server with automatic database setup.

```bash
npx emdash dev [options]
```

### Options

| Option | Alias | Description | Default |
|---|---|---|---|
| `--database` | `-d` | Database file path | `./data.db` |
| `--types` | `-t` | Generate types from remote before starting | `false` |
| `--port` | `-p` | Dev server port | `4321` |
| `--cwd` |  | Working directory | Current directory |

### Examples

```bash
# Start dev server
npx emdash dev

# Custom port
npx emdash dev --port 3000

# Generate types from remote before starting
npx emdash dev --types
```

### Behavior

1. Checks for and runs pending database migrations
2. If `--types` is set, generates TypeScript types from a remote instance (URL from `EMDASH_URL` env or `emdash.url` in `package.json`)
3. Starts Astro dev server with `EMDASH_DATABASE_URL` set
```

--------------------------------

### Installation

Source: https://docs.emdashcms.com/reference/cli

Instructions on how to install the EmDash CLI.

```APIDOC
## Installation

The CLI is included with the `emdash` package.

```bash
npm install emdash
```

Run commands with `npx emdash` or add scripts to `package.json`. The binary is also available as `em` for brevity.
```

--------------------------------

### Install Official EmDash Blog Theme

Source: https://docs.emdashcms.com/themes/overview

Use `create-astro` with the official blog theme template to start a new project.

```bash
npm create astro@latest -- --template @emdash-cms/template-blog

```

--------------------------------

### Start Development Server

Source: https://docs.emdashcms.com/getting-started

Run this command to start the EmDash development server.

```bash
npm run dev
```

--------------------------------

### Install EmDash CLI

Source: https://docs.emdashcms.com/reference/cli

Install the EmDash CLI as part of the emdash package. Run commands using `npx emdash` or add scripts to your `package.json`.

```bash
npm install emdash
```

--------------------------------

### Start EmDash Server

Source: https://docs.emdashcms.com/deployment/nodejs

Start the EmDash server after building the project. The server will run on `http://localhost:4321` by default.

```bash
node ./dist/server/entry.mjs
```

--------------------------------

### List Media Response Example

Source: https://docs.emdashcms.com/reference/rest-api

Example response for listing media assets. Includes file details, size, dimensions, URL, and creation timestamp.

```json
{
  "success": true,
  "data": {
    "items": [
      {
        "id": "01HXK5MZSN...",
        "filename": "photo.jpg",
        "mimeType": "image/jpeg",
        "size": 102400,
        "width": 1920,
        "height": 1080,
        "url": "https://cdn.example.com/photo.jpg",
        "createdAt": "2025-01-24T12:00:00Z"
      }
    ],
    "nextCursor": "eyJpZCI6..."
  }
}
```

--------------------------------

### Example Plugin with API Routes

Source: https://docs.emdashcms.com/plugins/api-routes

A practical example demonstrating how to define API routes within a plugin using Zod for input validation.

```APIDOC
## Example Plugin with API Routes

This example shows a plugin defining two API routes: `status` and `submissions`.

```javascript
import { definePlugin } from "emdash";
import { z } from "astro/zod";


export default definePlugin({
  id: "forms",
  version: "1.0.0",


  storage: {
    submissions: {
      indexes: ["formId", "status", "createdAt"],
    },
  },


  routes: {
    // Simple route
    status: {
      handler: async (ctx) => {
        return { ok: true, plugin: ctx.plugin.id };
      },
    },


    // 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,
        };
      },
    },
  },
});

```

### Route URLs
- `status`: `/_emdash/api/plugins/forms/status`
- `submissions`: `/_emdash/api/plugins/forms/submissions`
```

--------------------------------

### Get Content Response Example

Source: https://docs.emdashcms.com/reference/rest-api

Example response for retrieving a single content item. Details include ID, type, slug, data, status, and timestamps.

```json
{
  "success": true,
  "data": {
    "item": {
      "id": "01HXK5MZSN...",
      "type": "posts",
      "slug": "hello-world",
      "data": { "title": "Hello World", ... },
      "status": "published",
      "createdAt": "2025-01-24T12:00:00Z",
      "updatedAt": "2025-01-24T12:00:00Z"
    }
  }
}
```

--------------------------------

### Install Community EmDash Theme from GitHub

Source: https://docs.emdashcms.com/themes/overview

Install a community-contributed EmDash theme directly from a GitHub repository.

```bash
npm create astro@latest -- --template github:user/emdash-portfolio

```

--------------------------------

### Install Theme from GitHub

Source: https://docs.emdashcms.com/themes/creating-themes

Users can install your theme directly from GitHub by specifying the GitHub repository path as the template.

```bash
npm create astro@latest -- --template github:your-org/emdash-theme-blog
```

--------------------------------

### Clone and Install EmDash Dependencies

Source: https://docs.emdashcms.com/contributing

Clone the EmDash repository, navigate to the project directory, install dependencies using pnpm, and build the project. The build step is required before the first run.

```bash
git clone https://github.com/emdash-cms/emdash.git
cd emdash
pnpm install
pnpm build    # required before first run
```

--------------------------------

### Install Solana SVM Package

Source: https://docs.emdashcms.com/guides/x402-payments

Install the `@x402/svm` package using pnpm to enable Solana chain support.

```bash
pnpm add @x402/svm
```

--------------------------------

### Install Theme from npm

Source: https://docs.emdashcms.com/themes/creating-themes

Users can install your theme by creating a new Astro project using your theme's npm package name as the template.

```bash
npm create astro@latest -- --template @your-org/emdash-theme-blog
```

--------------------------------

### Install PostgreSQL Driver

Source: https://docs.emdashcms.com/deployment/database

Install the `pg` package as a dependency for PostgreSQL support.

```bash
pnpm add pg
```

--------------------------------

### Start EmDash with Docker Compose

Source: https://docs.emdashcms.com/deployment/nodejs

Start the EmDash service defined in `docker-compose.yml` in detached mode.

```bash
docker compose up -d
```

--------------------------------

### SQLite File Path Examples

Source: https://docs.emdashcms.com/deployment/database

Examples of configuring SQLite database file paths, including relative, absolute, and environment variable-based paths. The `url` must be prefixed with `file:`.

```javascript
// Relative path
database: sqlite({ url: "file:./data/emdash.db" });


// Absolute path
database: sqlite({ url: "file:/var/data/emdash.db" });


// From environment variable
database: sqlite({ url: `file:${process.env.DATABASE_PATH}` });
```

--------------------------------

### Example Collection Configuration

Source: https://docs.emdashcms.com/concepts/collections

Defines a 'posts' collection with support for drafts, revisions, preview, and scheduling.

```javascript
{
  slug: "posts",
  label: "Blog Posts",
  labelSingular: "Post",
  supports: ["drafts", "revisions", "preview", "scheduling"]
}
```

--------------------------------

### Install Project Dependencies

Source: https://docs.emdashcms.com/getting-started

Install all necessary dependencies for your EmDash project using npm.

```bash
npm install
```

--------------------------------

### List Content Response Example

Source: https://docs.emdashcms.com/reference/rest-api

Example response when listing content items. Includes item details, status, timestamps, and a cursor for pagination.

```json
{
  "success": true,
  "data": {
    "items": [
      {
        "id": "01HXK5MZSN...",
        "type": "posts",
        "slug": "hello-world",
        "data": { "title": "Hello World", ... },
        "status": "published",
        "createdAt": "2025-01-24T12:00:00Z",
        "updatedAt": "2025-01-24T12:00:00Z"
      }
    ],
    "nextCursor": "eyJpZCI6..."
  }
}
```

--------------------------------

### Theme Structure Example

Source: https://docs.emdashcms.com/themes/overview

Illustrates the typical file and directory structure of an EmDash theme.

```bash
my-theme/
├── package.json           # Theme metadata + EmDash config
├── astro.config.mjs       # Astro integration setup
├── src/
│   ├── live.config.ts     # Live Collections configuration
│   ├── pages/             # Astro routes
│   ├── layouts/           # Layout components
│   └── components/        # UI components
└── .emdash/
    ├── seed.json          # Schema + sample content
    └── uploads/           # Optional local media files

```

--------------------------------

### Schema Analysis Example

Source: https://docs.emdashcms.com/migration/content-import

Example output from the Analyze step of the import flow, detailing post type statuses and required schema changes. Incompatible field types require manual fixes.

```text
Post Types:
├── post (127) → posts [New collection]
├── page (12)  → pages [Existing, compatible]
├── product (45) → products [Add 3 fields]
└── revision (234) → [Skip - internal type]


Required Schema Changes:
├── Create collection: posts
├── Add fields to pages: featured_image
└── Create collection: products
```

--------------------------------

### EmDash Per-Collection Table Schema Example

Source: https://docs.emdashcms.com/concepts/architecture

Example SQL CREATE TABLE statement for a 'posts' collection in EmDash, demonstrating system columns and placeholders for content-specific fields.

```sql
-- Created when "posts" collection is added
CREATE TABLE ec_posts (
  -- System columns (always present)
  id TEXT PRIMARY KEY,
  slug TEXT UNIQUE,
  status TEXT DEFAULT 'draft',  -- draft, published, scheduled
  author_id TEXT,
  created_at TEXT DEFAULT (datetime('now')),
  updated_at TEXT DEFAULT (datetime('now')),
  published_at TEXT,
  deleted_at TEXT,              -- Soft delete
  version INTEGER DEFAULT 1,    -- Optimistic locking

  -- Content columns (from your field definitions)
  title TEXT NOT NULL,
  content JSON,                 -- Portable Text
  excerpt TEXT
);
```

--------------------------------

### Install @emdash-cms/x402 with npm

Source: https://docs.emdashcms.com/guides/x402-payments

Use this command to add the x402 payment integration to your Astro project using npm.

```bash
npm install @emdash-cms/x402
```

--------------------------------

### Install AWS SDK for S3 Adapter

Source: https://docs.emdashcms.com/deployment/storage

Install the necessary AWS SDK packages if you plan to use the S3-compatible storage adapter with EmDash CMS. This is required for `astro build` to succeed.

```bash
pnpm add @aws-sdk/client-s3 @aws-sdk/s3-request-presigner

```

--------------------------------

### Complete EmDash Plugin Example

Source: https://docs.emdashcms.com/plugins/admin-ui

A comprehensive example of defining an EmDash plugin, including its ID, version, capabilities, storage, admin configuration, and routes.

```javascript
import { definePlugin } from "emdash";


export default definePlugin({
  id: "analytics",
  version: "1.0.0",


  capabilities: ["network:fetch"],
  allowedHosts: ["api.analytics.example.com"],


  storage: {
    events: { indexes: ["type", "createdAt"] },
  },


  admin: {
    entry: "@my-org/plugin-analytics/admin",
    settingsSchema: {
      trackingId: { type: "string", label: "Tracking ID" },
      enabled: { type: "boolean", label: "Enabled", default: true },
    },
    pages: [
      { path: "/dashboard", label: "Dashboard", icon: "chart" },
      { path: "/settings", label: "Settings", icon: "settings" },
    ],
    widgets: [{ id: "events-today", title: "Events Today", size: "third" }],
  },


  routes: {
    stats: {
      handler: async (ctx) => {
        const today = new Date().toISOString().split("T")[0];
        const count = await ctx.storage.events!.count({
          createdAt: { gte: today },
        });
        return { today: count };
      },
    },
  },
});
```

--------------------------------

### Install @emdash-cms/x402 with yarn

Source: https://docs.emdashcms.com/guides/x402-payments

Use this command to add the x402 payment integration to your Astro project using yarn.

```bash
yarn add @emdash-cms/x402
```

--------------------------------

### WordPress Options API Example

Source: https://docs.emdashcms.com/migration/porting-plugins

Example of using WordPress functions to get, update, and delete options.

```php
$api_key = get_option('my_plugin_api_key', '');
update_option('my_plugin_api_key', 'abc123');
delete_option('my_plugin_api_key');

```

--------------------------------

### EmDash KV Store Example

Source: https://docs.emdashcms.com/migration/porting-plugins

Example of using EmDash KV store functions to get, set, and delete values.

```typescript
const apiKey = await ctx.kv.get<string>("settings:apiKey") ?? "";
await ctx.kv.set("settings:apiKey", "abc123");
await ctx.kv.delete("settings:apiKey");

```

--------------------------------

### Initialize Database and Run Migrations

Source: https://docs.emdashcms.com/deployment/database

Initialize the database and run pending migrations. This command creates the database file if it doesn't exist.

```bash
npx emdash init --database ./data.db
```

--------------------------------

### Persist Default Settings on Plugin Install

Source: https://docs.emdashcms.com/plugins/settings

To ensure default settings are available from the start, persist them within the 'plugin:install' hook. This guarantees that initial default values are set in KV storage when the plugin is first installed.

```javascript
hooks: {
  "plugin:install": async (_event, ctx) => {
    // Persist schema defaults
    await ctx.kv.set("settings:enabled", true);
    await ctx.kv.set("settings:maxItems", 100);
  }
}
```

--------------------------------

### Complete Blog Post Example with Emdash

Source: https://docs.emdashcms.com/guides/preview

A full blog post page demonstrating Emdash integration for content fetching, preview handling, and visual editing. Middleware automatically handles token verification for previews.

```astro
---
import { getEmDashEntry } from "emdash";
import BaseLayout from "../../layouts/Base.astro";
import { PortableText } from "emdash/ui";


const { slug } = Astro.params;


// Preview is automatic — middleware handles token verification
const { entry, isPreview, error } = await getEmDashEntry("posts", slug);


if (error) {
  return new Response("Server error", { status: 500 });
}


if (!entry) {
  return Astro.redirect("/404");
}
---


<BaseLayout title={entry.data.title}>
  {isPreview && (
    <div class="preview-banner" role="alert">
      <strong>Preview</strong> — This content is not published.
    </div>
  )}


  <article {...entry.edit}>
    <header>
      <h1 {...entry.edit.title}>{entry.data.title}</h1>
      {entry.data.publishedAt && (
        <time datetime={entry.data.publishedAt.toISOString()}>
          {entry.data.publishedAt.toLocaleDateString()}
        </time>
      )}
      {isPreview && !entry.data.publishedAt && (
        <span class="draft-indicator">Draft</span>
      )}
    </header>


    <div class="content" {...entry.edit.content}>
      <PortableText value={entry.data.content} />
    </div>
  </article>
</BaseLayout>

```

--------------------------------

### Get Single WordPress Post

Source: https://docs.emdashcms.com/coming-from/wordpress

Example of retrieving a single post by ID using WordPress's get_post() function.

```php
<?php
$post = get_post($id);
?>
<article>
  <h1><?php echo $post->post_title; ?></h1>
  <?php echo apply_filters('the_content', $post->post_content); ?>
</article>
```

--------------------------------

### Fetch Admin Manifest API Request

Source: https://docs.emdashcms.com/concepts/admin-panel

Example of an HTTP GET request to fetch the admin manifest, which contains metadata about collections, plugins, and other configurations.

```http
GET /_emdash/api/manifest
```

--------------------------------

### Create Test Project from Theme

Source: https://docs.emdashcms.com/themes/creating-themes

Create a new Astro project using your theme as a template to test its functionality.

```bash
npm create astro@latest -- --template ./path/to/my-theme
```

--------------------------------

### Get Single EmDash Entry

Source: https://docs.emdashcms.com/coming-from/wordpress

Example of retrieving a single entry by slug using EmDash's getEmDashEntry function. Includes importing PortableText for rendering structured content.

```typescript
---
import { getEmDashEntry } from "emdash";
import { PortableText } from "emdash/ui";


const { slug } = Astro.params;
const { entry: post } = await getEmDashEntry("posts", slug);


## if (!post) return Astro.redirect("/404");


<article>
  <h1>{post.data.title}</h1>
  <PortableText value={post.data.content} />
</article>
```

--------------------------------

### Get a Single Entry by ID or Slug

Source: https://docs.emdashcms.com/guides/querying-content

Use getEmDashEntry to retrieve a single entry by its ID or slug. This example demonstrates fetching an entry based on Astro.params.slug and rendering its title and content using PortableText.

```javascript
---
import { getEmDashEntry } from "emdash";
import { PortableText } from "emdash/ui";


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");
}
---


<article>
  <h1>{post.data.title}</h1>
  <PortableText value={post.data.content} />
</article>
```

--------------------------------

### Bundle a Plugin

Source: https://docs.emdashcms.com/plugins/publishing

Navigate to your plugin's directory and run the bundle command. This command builds the plugin, collects assets, and validates the bundle.

```bash
cd packages/plugins/my-plugin
emdash plugin bundle
```

--------------------------------

### Configure Admin Build Entry Point (tsup)

Source: https://docs.emdashcms.com/plugins/admin-ui

Set up your bundler (e.g., tsup) with a separate entry point for admin components. Keep React and EmDash as external dependencies.

```javascript
export default {
  entry: {
    index: "src/index.ts",
    admin: "src/admin.tsx"
  },
  format: "esm",
  dts: true,
  external: ["react", "react-dom", "emdash", "@emdash-cms/admin"]
};
```

--------------------------------

### Build and Run Demo Commands

Source: https://docs.emdashcms.com/contributing/translating

Commands to compile locale data, build the project, and run the development server for the EmDash demo.

```bash
pnpm run locale:compile
pnpm build
pnpm --filter emdash-demo dev

```

--------------------------------

### Add Sample Content

Source: https://docs.emdashcms.com/themes/creating-themes

Include sample content like blog posts in the seed file to demonstrate theme design. Ensure content is structured correctly.

```json
{
  "content": {
    "posts": [
      {
        "id": "hello-world",
        "slug": "hello-world",
        "status": "published",
        "data": {
          "title": "Hello World",
          "content": [
            {
              "_type": "block",
              "style": "normal",
              "children": [{ "_type": "span", "text": "Welcome to your new blog!" }]
            }
          ],
          "excerpt": "Your first post on EmDash."
        },
        "taxonomies": {
          "category": ["news"]
        }
      }
    ]
  }
}
```

--------------------------------

### Rate Limiting Response Example

Source: https://docs.emdashcms.com/reference/rest-api

Example of a rate-limited response, indicating the client should wait before retrying.

```http
HTTP/1.1 429 Too Many Requests
Retry-After: 60
```

--------------------------------

### EmDash Storage Collections Example

Source: https://docs.emdashcms.com/migration/porting-plugins

Example of declaring and using EmDash storage collections for data management.

```typescript
// Declare in plugin definition
storage: {
    items: {
        indexes: ["status", "createdAt"],
    },
},


// In hooks or routes:
await ctx.storage.items.put("item-1", {
    name: "Item 1",
    status: "active",
    createdAt: new Date().toISOString(),
});


const result = await ctx.storage.items.query({
    where: { status: "active" },
    limit: 10,
});

```

--------------------------------

### Environment-Based Storage Configuration

Source: https://docs.emdashcms.com/deployment/storage

Dynamically switch between storage backends (e.g., R2 for production, local for development) based on the environment. This example uses `import.meta.env.PROD` to determine the active storage adapter.

```javascript
import emdash, { s3, local } from "emdash/astro";
import { r2 } from "@emdash-cms/cloudflare";


const storage = import.meta.env.PROD
  ? r2({ binding: "MEDIA" })
  : local({
      directory: "./uploads",
      baseUrl: "/_emdash/api/media/file",
    });


export default defineConfig({
  integrations: [emdash({ storage })],
});
```

--------------------------------

### Create and Run EmDash Blog Site

Source: https://docs.emdashcms.com/

Use these npm commands to create a new EmDash blog site using the official Astro template and start the development server. The admin interface will be available at http://localhost:4321/_emdash/admin.

```bash
# Create a new EmDash site
npm create astro@latest -- --template @emdash-cms/template-blog


# Start the dev server
npm run dev


# Visit the admin at http://localhost:4321/_emdash/admin
```

--------------------------------

### WordPress Custom Table Example

Source: https://docs.emdashcms.com/migration/porting-plugins

Example of interacting with custom database tables in WordPress using $wpdb.

```php
global $wpdb;
$table = $wpdb->prefix . 'my_plugin_items';


// Insert
$wpdb->insert($table, ['name' => 'Item 1', 'status' => 'active']);


// Query
$items = $wpdb->get_results(
"SELECT * FROM $table WHERE status = 'active' LIMIT 10"
);

```

--------------------------------

### Create a New EmDash Project with npm

Source: https://docs.emdashcms.com/getting-started

Use this command to initiate a new EmDash project using npm.

```bash
npm create emdash@latest
```

--------------------------------

### Navigate to Project Directory

Source: https://docs.emdashcms.com/getting-started

Change into your newly created EmDash project directory.

```bash
cd my-emdash-site
```

--------------------------------

### Example API Response

Source: https://docs.emdashcms.com/reference/rest-api

This is an example of a successful API response structure, typically returned for content retrieval operations.

```json
{
  "success": true,
  "data": {
    "items": [
      {
        "id": "01HXK5MZSN...",
        "collection": "posts",
        "entryId": "01HXK5MZSN...",
        "data": { ... },
        "createdAt": "2025-01-24T12:00:00Z"
      }
    ],
    "total": 5
  }
}
```

--------------------------------

### Pagination Example

Source: https://docs.emdashcms.com/concepts/admin-panel

Demonstrates how to use cursor-based pagination for list endpoints. Fetch subsequent pages by appending the 'nextCursor' value to the 'cursor' query parameter.

```json
{
  "items": [...],
  "nextCursor": "eyJpZCI6IjAxSjEyMzQ1NiJ9"
}
```

```http
GET /api/content/posts?cursor=eyJpZCI6IjAxSjEyMzQ1NiJ9
```

--------------------------------

### Import Completion Report Example

Source: https://docs.emdashcms.com/migration/content-import

Example of an import completion report, detailing imported items, warnings, and failures.

```text
Import Complete


✓ 125 posts imported
✓ 12 pages imported
✓ 85 media references recorded


⚠ 2 items had warnings:
  - Post "Special Characters ñ" - title encoding fixed
  - Page "About" - duplicate slug renamed to "about-1"


✗ 1 item failed:
  - Post ID 456 - content parsing error (saved as draft)
```

--------------------------------

### Initialize EmDash Database

Source: https://docs.emdashcms.com/deployment/nodejs

Initialize the EmDash database using the provided command. This command sets up the necessary database schema.

```bash
npx emdash init --database ./data/emdash.db
```

--------------------------------

### Portable Text Block Example

Source: https://docs.emdashcms.com/reference/field-types

An example structure for a Portable Text block, showing basic formatting and span content.

```json
[
  {
    "_type": "block",
    "style": "normal",
    "children": [{ "_type": "span", "text": "Hello world" }]
  }
]
```

--------------------------------

### Hook Execution Order Examples

Source: https://docs.emdashcms.com/plugins/hooks

Demonstrates how hooks with different priorities and dependencies are executed. Lower priorities run first, and dependencies ensure plugins complete in the correct order.

```javascript
// Plugin A
"content:afterSave": {
  priority: 50,  // Runs first
  handler: async () => {}
}


// Plugin B
"content:afterSave": {
  priority: 100,  // Runs second (default priority)
  handler: async () => {}
}


// Plugin C
"content:afterSave": {
  priority: 200,
  dependencies: ["plugin-a"],  // Runs after A, even if priority was lower
  handler: async () => {}
}
```

--------------------------------

### EmDash Content Table Schema Example

Source: https://docs.emdashcms.com/concepts/content-model

Example of a content table (`ec_products`) generated based on collection and field definitions.

```sql
CREATE TABLE ec_products (
  -- System columns (always present)
  id TEXT PRIMARY KEY,
  slug TEXT UNIQUE,
  status TEXT DEFAULT 'draft',
  author_id TEXT,
  created_at TEXT DEFAULT (datetime('now')),
  updated_at TEXT DEFAULT (datetime('now')),
  published_at TEXT,
  deleted_at TEXT,                  -- Soft delete
  version INTEGER DEFAULT 1,        -- Optimistic locking


  -- Content columns (from field definitions)
  title TEXT NOT NULL,
  price REAL
);

```

--------------------------------

### Install Cloudflare Variants of EmDash Themes

Source: https://docs.emdashcms.com/themes/overview

Install Cloudflare-specific variants of EmDash themes for deployment on Cloudflare Pages with D1 and R2.

```bash
npm create astro@latest -- --template @emdash-cms/template-blog-cloudflare
npm create astro@latest -- --template @emdash-cms/template-portfolio-cloudflare
npm create astro@latest -- --template @emdash-cms/template-marketing-cloudflare

```

--------------------------------

### Astro Component Example

Source: https://docs.emdashcms.com/coming-from/astro-for-wp-devs

Demonstrates an Astro component with frontmatter for server-side logic and a template for HTML output. Imports and props are defined in the frontmatter.

```astro
---
// Frontmatter: runs on server, never sent to browser
interface Props {
  title: string;
  excerpt: string;
  url: string;
}

const { title, excerpt, url } = Astro.props;
---
<!-- Template: outputs HTML -->
<article class="post-card">
  <h2><a href={url}>{title}</a></h2>
  <p>{excerpt}</p>
</article>

```

--------------------------------

### Install RSS Package

Source: https://docs.emdashcms.com/guides/create-a-blog

Install the necessary RSS package for generating an RSS feed. This command should be run in your project's terminal.

```bash
npm install @astrojs/rss
```

--------------------------------

### EmDash CMS Version Format Examples

Source: https://docs.emdashcms.com/plugins/creating-plugins

EmDash CMS requires semantic versioning. Examples show valid and invalid formats.

```yaml
version: "1.0.0"; // Valid
version: "1.2.3-beta"; // Valid (prerelease)
version: "1.0"; // Invalid (missing patch)
```

--------------------------------

### emdash init

Source: https://docs.emdashcms.com/reference/cli

Initialize the database with core schema and optional template data.

```APIDOC
## `emdash init`

Initialize the database with core schema and optional template data.

```bash
npx emdash init [options]
```

### Options

| Option | Alias | Description | Default |
|---|---|---|---|
| `--database` | `-d` | Database file path | `./data.db` |
| `--cwd` |  | Working directory | Current directory |
| `--force` | `-f` | Re-run schema and seed | `false` |

### Behavior

1. Reads `emdash` config from `package.json`
2. Creates the database file if needed
3. Runs core migrations (creates system tables)
4. Runs template `schema.sql` if configured
5. Runs template `seed.sql` if configured

If the database already contains collections, `init` skips schema and seed unless `--force` is used.
```

--------------------------------

### API Reference - getSiteSettings()

Source: https://docs.emdashcms.com/guides/site-settings

Fetches all site settings with resolved media URLs.

```APIDOC
### `getSiteSettings()`

Fetch all site settings with resolved media URLs.

**Returns:** `Promise<Partial<SiteSettings>>`
Returns a partial object. Unset values are `undefined`.
```

--------------------------------

### Install @emdash-cms/x402 with pnpm

Source: https://docs.emdashcms.com/guides/x402-payments

Use this command to add the x402 payment integration to your Astro project using pnpm.

```bash
pnpm add @emdash-cms/x402
```

--------------------------------

### API Reference - getSiteSetting(key)

Source: https://docs.emdashcms.com/guides/site-settings

Fetches a single site setting by its key.

```APIDOC
### `getSiteSetting(key)`

Fetch a single setting by key.

**Parameters:**
  * `key` — The setting key (e.g., `"title"`, `"logo"`, `"social"`)

**Returns:** `Promise<SiteSettings[K] | undefined>`
Type-safe: the return type matches the key you request.
```

--------------------------------

### Configure Admin Build Entry Point (Alternative tsup)

Source: https://docs.emdashcms.com/plugins/admin-ui

An alternative tsup configuration for admin build entry points, specifying multiple entry files. Ensure React and EmDash are external.

```javascript
export default {
  entry: ["src/index.ts", "src/admin.tsx"],
  format: "esm",
  dts: true,
  external: ["react", "react-dom", "emdash", "@emdash-cms/admin"]
};
```

--------------------------------

### Fetch All Site Settings

Source: https://docs.emdashcms.com/guides/site-settings

Use `getSiteSettings()` to retrieve all global site configurations. This is useful for rendering site-wide elements like headers and footers.

```javascript
import { getSiteSettings } from "emdash";


const settings = await getSiteSettings();
```

```html
<html lang="en">
  <head>
    <title>{settings.title}</title>
    {settings.favicon && (
      <link rel="icon" href={settings.favicon.url} />
    )}
  </head>
  <body>
    <header>
      {settings.logo ? (
        <img src={settings.logo.url} alt={settings.logo.alt || settings.title} />
      ) : (
        <span class="site-title">{settings.title}</span>
      )}
      {settings.tagline && <p class="tagline">{settings.tagline}</p>}
    </header>
    <slot />
  </body>
</html>
```

--------------------------------

### Organize KV Data with Prefixes

Source: https://docs.emdashcms.com/plugins/settings

Use prefixes like 'settings:', 'state:', and 'cache:' to categorize and organize Key-Value data for better clarity and management. 'settings:' is for user-configurable preferences shown in the UI, while other prefixes are for internal plugin use.

```javascript
await ctx.kv.set("settings:webhookUrl", url);
await ctx.kv.set("state:lastRun", timestamp);
await ctx.kv.set("cache:feed", feedData);
```

```javascript
// Avoid: no prefix, unclear purpose
await ctx.kv.set("url", url);
```

--------------------------------

### Example Reference Field with Widget Options

Source: https://docs.emdashcms.com/concepts/collections

Shows a reference field configuration for related products, specifying the target collection and allowing multiple selections.

```json
{
  slug: "relatedProducts",
  type: "reference",
  label: "Related Products",
  options: {
    collection: "products",
    allowMultiple: true
  }
}
```

--------------------------------

### Get Section API

Source: https://docs.emdashcms.com/guides/sections

Retrieves a specific section by its slug.

```APIDOC
## GET /_emdash/api/sections/{slug}

### Description
Retrieves a specific section by its slug.

### Method
GET

### Endpoint
/_emdash/api/sections/{slug}

### Parameters
#### Path Parameters
- **slug** (string) - Required - The unique identifier for the section.

### Response
#### Success Response (200)
- **section** (Section) - The requested section object.
```

--------------------------------

### Create a New EmDash Project with pnpm

Source: https://docs.emdashcms.com/getting-started

Use this command to initiate a new EmDash project using pnpm.

```bash
pnpm create emdash@latest
```

--------------------------------

### Convert WordPress Template Part to Astro Component

Source: https://docs.emdashcms.com/coming-from/wordpress

Shows the equivalent of WordPress's get_template_part function in EmDash using Astro components. The WordPress example includes PHP for fetching and displaying post content, while the EmDash example uses Astro's templating.

```php
get_template_part('template-parts/content', 'post');

// template-parts/content-post.php:
<article class="post">
  <h2><?php the_title(); ?></h2>
  <?php the_excerpt(); ?> 
</article>
```

```astro
--- 
const { post } = Astro.props;
--- 

<article class="post">
  <h2>{post.data.title}</h2>
  <p>{post.data.excerpt}</p>
</article>
```

--------------------------------

### Get Menu API Endpoint

Source: https://docs.emdashcms.com/reference/rest-api

Retrieve a specific menu by its name.

```http
GET /_emdash/api/menus/:name
```

--------------------------------

### GET /_emdash/api/plugins/forms/submissions

Source: https://docs.emdashcms.com/plugins/api-routes

Retrieves a list of form submissions with an optional limit.

```APIDOC
## GET /_emdash/api/plugins/forms/submissions

### Description
Retrieves a list of form submissions. You can specify a limit for the number of submissions to retrieve.

### Method
GET

### Endpoint
https://your-site.com/_emdash/api/plugins/forms/submissions

#### Query Parameters
- **limit** (integer) - Optional - The maximum number of submissions to return.

### Response
#### Success Response (200)
- **submissions** (array) - A list of form submission objects.
- **submission** (object) - Represents a single form submission.
  - **id** (string) - The unique identifier of the submission.
  - **formData** (object) - The data submitted in the form.
  - **submittedAt** (string) - The timestamp when the form was submitted.

#### Response Example
```json
{
  "submissions": [
    {
      "id": "sub_123",
      "formData": {
        "name": "John Doe",
        "email": "john.doe@example.com"
      },
      "submittedAt": "2023-10-27T10:00:00Z"
    }
  ]
}
```
```