@emdash.directory/plugin-custom-blocks

A plugin for emdash CMS that lets you create reusable HTML+CSS blocks and embed them in your content via the editor's slash command menu.

Built by emdash.directory — plugins and resources for emdash CMS.

Perfect for banners, CTAs, newsletter signup forms, announcements, or any reusable HTML snippet that non-technical editors need to insert into posts and pages.

Features

• Create and manage HTML+CSS blocks from the admin UI
• Insert blocks into content using the /customBlock slash command
• Dropdown picker lists all published blocks (no need to remember slugs)
• CSS is automatically scoped to each block
• Blocks can be draft or published — only published blocks are available for insertion
• Astro component included for server-side rendering

Installation

Via Marketplace (recommended)

Install directly from the emdash admin panel under Plugins > Marketplace. Search for "Custom Blocks" and click Install.

Via npm (config mode)

npm install @emdash.directory/plugin-custom-blocks

Setup

1. Register the plugin

In your astro.config.mjs:

import { customBlocksPlugin } from "@emdash.directory/plugin-custom-blocks";
import emdash from "emdash/astro";

export default defineConfig({
  integrations: [
    emdash({
      database: /* your database config */,
      plugins: [
        customBlocksPlugin(),
      ],
    }),
  ],
});

2. Register the Astro component

In your Portable Text rendering setup, register the CustomBlock component for the customBlock type:

---
import { PortableText } from "astro-portabletext";
import { CustomBlock } from "@emdash.directory/plugin-custom-blocks/astro";

const { content } = Astro.props;
---

<PortableText
  value={content}
  components={{
    type: {
      customBlock: CustomBlock,
    },
  }}
/>

Usage

Creating blocks

1. Go to the admin panel
2. Navigate to Plugins > Blocks
3. Click New Block
4. Enter a name, HTML content, and optional CSS
5. Set status to Published and save

Inserting blocks in content

1. In the post/page editor, type /customBlock
2. Select a block from the dropdown
3. Click Insert

The block will appear in your content and render on the public site.

Embed snippet

Each block also provides an embed snippet you can copy and paste into any external HTML page. Find it by clicking Embed code on any block in the admin.

Block scoping

CSS is scoped using a wrapper class .cb-{slug}. For example, a block with slug newsletter-banner will have its CSS wrapped in .cb-newsletter-banner { ... } and the HTML wrapped in <div class="cb-newsletter-banner">...</div>.

API

Public render route

The plugin exposes a public API route for fetching block content:

POST /_emdash/api/plugins/custom-blocks/render
Content-Type: application/json

{ "id": "block-slug" }

Returns { data: { html, css, slug } } for published blocks.

Notes

• Only HTML and CSS are supported (no JavaScript) to keep things safe
• Only published blocks appear in the editor dropdown and public API
• Admins are trusted — HTML is not sanitized since only site admins can create blocks

License

MIT