Snippet Generators

The Snippet Generator lives at workspace.matters.ai/content/snippet-generator. It lets the content team build complex WordPress block snippets (testimonials, video players, stats grids, FAQs, spacers, etc.) by filling out forms, then copy-paste the generated HTML into the WordPress post body.

The public site (matters.ai) renders blog posts via BlogContent.tsx, which parses the post HTML with html-react-parser and intercepts specific markers in the markup to swap in custom React components. That hand-off — generator HTML in WordPress → parser interceptor in Next.js — is the core of the system.

When to use a snippet block (vs. ACF or a CPT)#

Snippet blocks are perfect when:

• The same component needs to appear in many posts at the editor's discretion
• The component has visual structure that's painful to recreate in raw HTML
• Editors should preview the result before copy-pasting

Data flow#

┌──────────────────────────────────────────────────────────────────────┐
│  Workspace: /content/snippet-generator                               │
│                                                                      │
│   ┌────────────┐    ┌─────────────────┐    ┌────────────────────┐   │
│   │   Form     │ →  │  generator-     │ →  │ Generated HTML     │   │
│   │ (per block)│    │  logic.ts       │    │ + Live preview     │   │
│   └────────────┘    └─────────────────┘    └────────────────────┘   │
│                                                  │                   │
│                                                  ▼                   │
│                                      Copy to clipboard               │
└──────────────────────────────────────────────────────────────────────┘
                                                  │
                                                  ▼
┌──────────────────────────────────────────────────────────────────────┐
│  WordPress post editor                                               │
│   Editor pastes HTML as a Custom HTML block                          │
│   (no plugins; the markup is portable + accessible)                  │
└──────────────────────────────────────────────────────────────────────┘
                                                  │
                                                  ▼
┌──────────────────────────────────────────────────────────────────────┐
│  matters.ai/blogs/<slug>                                             │
│                                                                      │
│   getEnrichedPost(slug)                                              │
│        │                                                             │
│        ▼                                                             │
│   BlogContent renders post HTML with html-react-parser               │
│        │                                                             │
│        ├─ <videoplayer>             → <VideoPlayer/>                 │
│        ├─ div[data-testimonial-id]  → <TestimonialCard/>             │
│        ├─ div.matters-faq-block     → <FAQAccordion/>                │
│        ├─ div.wp-block-spacer       → native HTML (CSS only)         │
│        └─ everything else           → native HTML                    │
└──────────────────────────────────────────────────────────────────────┘

Block catalog#

As of 2026-05-29 the generator supports 20 component types (19 distinct blocks; statements has a statements-large variant, so the ComponentType union has 20 members). Source: types.ts ComponentType.

Each block has:

1. A data interface and a toggles interface in types.ts
2. An icon and label in constants.ts
3. A <XxxForm> component in apps/workspace/app/(workspace)/content/components/generators/
4. A case "xxx" in generator-logic.ts
5. State + form rendering in client-page.tsx
6. (Optional) A preview branch in PreviewRenderer.tsx
7. (Optional, if the block needs React hydration on the public site) A parser interceptor in BlogContent.tsx

Round-trip editing (import & edit an existing snippet)#

Historically the generator was one-directional: fill a form → copy HTML. There was no way to reopen a previously generated snippet and tweak it — you rebuilt it from scratch. It now round-trips.

How it works — embedded config metadata#

Every generated snippet ends with an invisible HTML comment that carries the full editor config (type + data + toggles) as UTF-8-safe base64 JSON, wrapped in a versioned marker:

<!-- matters-snippet v1 eyJ2IjoxLCJ0eXBlIjoic3RhdHMtZ3JpZCIsImRhdGEiOnsuLi59fQ== -->

• It renders as nothing in the browser (HTML comment) and survives copy-paste into the WordPress block.
• It is versioned (v1) so a future schema change can be detected and migrated.
• The serialize/parse helpers live in utils/snippet-config.ts (serializeSnippetConfig, parseSnippetConfig). Encoding is btoa(encodeURIComponent(json)) — pure-ASCII, so it handles emoji / accents / smart quotes without escape/unescape.

The Import / Edit flow#

The Import / Edit button in the Source-Component header opens a modal. Paste any previously generated snippet → it parses the trailing comment, validates the type against COMPONENT_LABELS, restores the exact data/toggles into the right form (merged onto current defaults so newer fields stay populated), and switches selectedComponent to that type. The modal is role="dialog" + aria-modal, closes on Esc or backdrop click, and autofocuses the textarea.

Restoring config is a per-type dispatch in client-page.tsx (getActiveConfig reads the active type's state, applyImportedConfig writes it). Both switches end in a never-typed exhaustiveness guard, so adding a new ComponentType without wiring both halves is a compile error — the round-trip can't silently drift.

Pre-existing snippets (generated before this feature shipped) have no embedded comment, so they can't be auto-parsed — reverse-parsing 19 different HTML shapes would be unreliable. Anything generated from now on round-trips; regenerate old high-value snippets once to make them editable.

Rich-text fields#

Any multi-line content field across every generator form can be edited as plain text or as a WYSIWYG (Tiptap) editor — the choice is the user's, per field. This is built into the shared SmartInput primitive (so it propagates to every generator form — 19 *Form.tsx files under content/components/generators/), not hand-wired per form.

• Per-field "Rich text" toggle appears on every type="textarea" field.
• Initial mode auto-detects HTML in the value (/<\/?[a-zA-Z][^>]*>/). Fields whose content already contains markup (pull-quote <mark>, FAQ <a>, statements <strong>) open in rich mode; plain fields stay plain. This is how the editing mode "persists" — the formatting lives in the saved HTML, so on re-import the field re-opens correctly.
• Tiptap is lazy-loaded via next/dynamic (ssr:false), so it only downloads when a field is actually switched to rich mode — SmartInput's other usages across the workspace don't pay the ~100 KB cost.
• Opt out with richText={false} for raw HTML/CSS/JSON fields that must stay literal: Custom Div content/styles/attributes, Video Player Metadata (JSON).

Single-line fields (titles, labels, URLs, hex colors) intentionally stay plain — rich text is a multi-line content concern, and a WYSIWYG toolbar on a hex field would be wrong.

Stats Grid — variants & columns#

The Stats Grid block (StatsGridForm.tsx) has the richest layout config. Its CSS lives in components/blogs/styles.css under .stats-grid.

Variants (stats-grid--<variant>): spotlight, editorial, minimal, bordered, tiles, filled. The Tiles variant reuses the Bordered-cards theme but collapses the cards into one seamless grid — gap: 0, no radius/shadow, and shared hairline borders (the container draws the top+left edge; each tile draws its own right+bottom edge, so adjacent borders merge into a single line at any column count).

Columns (stats-grid--cols-<n>): 1 / 2 / 3 / 4 / 5 / auto, default auto. Fixed counts use explicit repeat(N, minmax(0, 1fr)) so "2 columns" really means two columns; only auto uses repeat(auto-fit, …) and lets the browser choose by card density. Fixed counts collapse responsively (3/4/5 → 2 under 768px, all → 1 under 480px).

A subtle earlier bug: every column count used auto-fit, so "2 columns" still packed 4 cards across on a wide blog container. The fix was to use explicit track counts for the numbered options and reserve auto-fit for auto only.

Block markup contract#

For blocks that don't need React hydration on the public site, the generator just emits plain HTML that styles itself via Tailwind classes or inline CSS. The Spacer block is the cleanest example — see below.

For blocks that do need React hydration (TestimonialCard, VideoPlayer, FAQ accordion), the markup must include a stable selector the parser can detect. Conventions:

The marker must be stable — once content is published with one marker, changing it requires a content migration.

Adding a new block — step-by-step#

The shortest path is to mirror the Spacer block (the most recent addition, cleanest example). Concrete file map:

1. Extend ComponentType + add interfaces#

In types.ts:

export type ComponentType =
  | "inlineblockquote"
  // ...existing...
  | "spacer"
  | "your-block";   // ← add

export interface YourBlockData { /* ... */ }
export interface YourBlockToggles { /* ... */ }

2. Register icon + label#

In constants.ts:

import { YourIcon } from "lucide-react";

export const COMPONENT_ICONS: Record<ComponentType, React.ElementType> = {
  // ...
  "your-block": YourIcon,
};

export const COMPONENT_LABELS: Record<ComponentType, string> = {
  // ...
  "your-block": "Your Block",
};

3. Build the form#

Create apps/workspace/app/(workspace)/content/components/generators/YourBlockForm.tsx following the existing pattern (use SpacerForm.tsx as the template — it uses the shared SmartForm wrapper for boilerplate-free field rendering).

4. Generate HTML#

In generator-logic.ts, add a new case:

case "your-block": {
  if (!yourBlockData || !yourBlockToggles) return "";
  // …build a string of HTML…
  return html;
}

5. Wire state into the snippet-generator client#

In client-page.tsx:

const [yourBlockData, setYourBlockData] = useState<YourBlockData>(/* defaults */);
const [yourBlockToggles, setYourBlockToggles] = useState<YourBlockToggles>(/* defaults */);

// In the form-render switch:
{selectedComponent === "your-block" && (
  <YourBlockForm
    data={yourBlockData}
    setData={setYourBlockData}
    toggles={yourBlockToggles}
    setToggles={setYourBlockToggles}
  />
)}

And in the useEffect that calls generateComponentCode:

yourBlockData,
yourBlockToggles,

6. Optional — add a preview branch#

If the generated HTML doesn't render correctly in isolation (e.g. Tailwind JIT can't see dynamic classes), add a preview branch in PreviewRenderer.tsx. The Spacer block uses this because Tailwind can't precompile its arbitrary classes.

7. Optional — add a public-site parser interceptor#

If the block needs to hydrate to a React component on the public site (e.g. accordion behavior, video player, registry lookup), add an interceptor in BlogContent.tsx inside MemoizedArticleContent:

const parserOptions: HTMLReactParserOptions = {
  replace: (domNode) => {
    if (
      domNode instanceof DOMElement &&
      domNode.name === "div" &&
      domNode.attribs?.class?.includes("matters-your-block")
    ) {
      // Extract data, return your React component
      return <YourBlock ... />;
    }
    // ... existing interceptors
  },
};

Worked example — Spacer block#

The Spacer block is the canonical "lightweight" snippet — no React hydration, no parser interceptor, pure HTML/CSS that renders the same in the workspace preview, the WP editor preview, and the public site.

Form output#

Users in the workspace pick:

• Direction (top / bottom / vertical / height)
• Per-breakpoint values (mobile, optional tablet, optional desktop)
• Unit (px / rem / em / vh / %)
• Output mode (tailwind or inline)
• aria-hidden, !important, extra classes

Generator output (Tailwind mode)#

<div aria-hidden="true" class="wp-block-spacer h-0 mt-[64px] md:!mt-[80px] lg:!mt-[92px]"></div>

Generator output (Inline mode — portable, no Tailwind dependency)#

<div aria-hidden="true" class="wp-block-spacer matters-spacer-abc123" style="margin-top:64px !important"></div>
<style>@media (min-width:768px){.matters-spacer-abc123{margin-top:80px !important;}} @media (min-width:1024px){.matters-spacer-abc123{margin-top:92px !important;}}</style>

The inline-mode output is self-contained: it works in any rendering context that doesn't have Tailwind. Use this when you're not sure the destination compiles your arbitrary classes. The blog renderer (BlogContent.tsx) does compile them, so Tailwind mode is fine there — but other surfaces (email exports, WP-rendered previews) won't, hence the mode toggle.

Why the Spacer needs a preview branch but no parser interceptor#

• Preview branch in PreviewRenderer.tsx: the workspace preview is a controlled environment where Tailwind doesn't have the JIT context to compile the spacer's arbitrary classes (mt-[64px], etc.). The preview falls back to inline styles so the spacer is always visible during authoring.
• No interceptor in BlogContent.tsx: on the public site, the standard parser passes the div through, and either the Tailwind classes (compiled by the site's Tailwind setup) or the embedded <style> block (in inline mode) does the job.

Worked example — FAQ block (with parser interceptor + auto schema)#

The FAQ block is the canonical "rich hydrated" snippet — its generated markup is collapsible-by-default via <details>, the public site upgrades it to a fancier React accordion, and it auto-generates FAQPage JSON-LD on the blog detail page.

Markup contract#

<div class="matters-faq-block" data-matters-faq>
  <details class="matters-faq-item" data-q="What is Matters AI?">
    <summary>What is Matters AI?</summary>
    <div class="matters-faq-answer"><p>Rich answer HTML…</p></div>
  </details>
  <details class="matters-faq-item" data-q="How is it priced?">
    <summary>How is it priced?</summary>
    <div class="matters-faq-answer"><p>…</p></div>
  </details>
</div>

Key invariants:

• <details> elements work without JavaScript — the markup is accessible everywhere it's pasted, even if no parser interceptor runs.
• data-q on each item carries the question text in clean form, so the schema extractor doesn't have to strip HTML.
• .matters-faq-answer div is the canonical answer container, used by both the schema extractor (to extract plain text) and the React accordion (to inject as dangerouslySetInnerHTML).
• Top-level .matters-faq-block is the selector both the parser interceptor and the schema extractor look for.

Public-site rendering#

BlogContent.tsx intercepts any div.matters-faq-block and replaces it with a React <FAQAccordion> component that:

• Animates open/close (Tailwind transitions + Framer Motion)
• Supports keyboard navigation (focus-visible ring, arrow keys)
• Optionally tracks open/close events to analytics

If JS is disabled or the parser doesn't run, the native <details> markup remains, so the content is never inaccessible.

Auto-generated JSON-LD#

The blog detail page extracts every .matters-faq-block in the post HTML, pulls each data-q + plain-text answer, and emits a FAQPage JSON-LD block alongside the existing Rank Math JSON-LD.

This is gated by the ACF flag disable_auto_faq_schema on the post — set it to true if the FAQ block on a given post is purely visual and shouldn't appear in search.

ACF overrides#

Three optional ACF fields on every blog post let editors override the auto-generated schema:

See ACF Usage for the field-group setup. The injection point is the blog detail page (app/[...slug]/page.tsx for the routed flow, components/templates/BlogPostTemplate.tsx for the render).

Gotchas#

• Don't change a block's markup contract once published. Editors will have hundreds of posts using the old markup; the parser interceptor must keep recognising both shapes, or you need a content migration.
• Don't import the workspace generator from the public site. The generator is a workspace-only tool; the public site only renders the already-generated HTML.
• Don't ship blocks without an accessible fallback. The FAQ block uses native <details> so it works without JS. The Spacer is just a div with CSS. Any new interactive block must degrade gracefully.
• Don't forget to escape user content in the generator. The generator emits HTML that WordPress stores as-is; if a field's value contains </div>, it can break the entire block. Use the existing HTML-escape helpers in generator-logic.ts.

Related#

• Content & CMS — how blog posts get into the public site
• ACF Usage — adjacent editor-controlled pattern
• CPT-Backed Module Pattern — when content needs a full admin UI, not just a snippet
• SEO & Analytics — the FAQ block's auto-generated JSON-LD lives here