Add portableText as a Block Kit field type for nested rich text in custom PT blocks

[wojtekpiskorz]

Summary

Plugin-declared Portable Text blocks currently support Block Kit form fields for editing (text_input, select, toggle, media_picker, repeater, etc.). This covers structured data well — but there's no way to include rich text content inside a custom block.

I propose adding a portableText Block Kit field type that renders a full TipTap rich text editor inline within a custom PT block's editing form. This would unlock layout composition — blocks like "section with columns" where each column contains its own rich text content.

Problem

Plugin-declared PT blocks only support scalar Block Kit fields (text_input, select, toggle, etc.). Consider a typical custom block:

portableTextBlocks: [
  {
    type: "contentSection",
    label: "Content Section",
    fields: [
      { type: "text_input", action_id: "title", label: "Title" },
      { type: "text_input", action_id: "body", label: "Body text", multiline: true },
      // ... image, CTA fields
    ]
  }
]

The body field is text_input with multiline: true — plain text, no formatting. Editors can't add links, bold, headings, or embed images inside a section's body. They get WYSIWYG in the main post content, but not inside custom blocks.

This means we can't build compositional layouts like:

• A two-column section where each column has independent rich text
• A card block with a rich text description (not just a plain text blurb)
• A tab/accordion where each panel contains rich text content
• A callout block with formatted text inside

Proposed Solution

Add portableText as a Block Kit field type for PT block declarations:

portableTextBlocks: [
  {
    type: "twoColumnSection",
    label: "Two Columns",
    fields: [
      { type: "text_input", action_id: "title", label: "Section title" },
      {
        type: "portableText",        // <-- NEW field type
        action_id: "leftColumn",
        label: "Left column"
      },
      {
        type: "portableText",
        action_id: "rightColumn",
        label: "Right column"
      }
    ]
  }
]

Data shape

The portableText field stores its content as a Portable Text array (same format as the main post content):

{
  "_type": "twoColumnSection",
  "_key": "abc123",
  "title": "Our Approach",
  "leftColumn": [
    { "_type": "block", "_key": "b1", "children": ["..."], "markDefs": [] },
    { "_type": "image", "_key": "b2", "asset": {} }
  ],
  "rightColumn": [
    { "_type": "block", "_key": "b3", "children": ["..."], "markDefs": [] }
  ]
}

This is the same format EmDash already uses for content fields — no new serialization format needed.

Admin editing

In the TipTap-based editor, when a user clicks into a PT block with portableText fields:

1. The block's NodeView renders each portableText field as an inline TipTap sub-editor
2. Each sub-editor supports the full PT editing surface (paragraphs, headings, lists, links, images, slash commands for other blocks)
3. Editing happens inline — no separate modal needed for rich text content
4. Nested PT blocks can also be inserted via slash commands inside these sub-editors (recursion limited to a configurable depth, e.g. 2 levels)

Site-side rendering

The Astro component receives the nested PT arrays and renders them with <PortableText>:

---
// TwoColumnSection.astro
const { title, leftColumn, rightColumn } = Astro.props.node;
---
<section class="two-column">
  {title && <h2>{title}</h2>}
  <div class="grid">
    <div class="col">
      <PortableText content={leftColumn} />
    </div>
    <div class="col">
      <PortableText content={rightColumn} />
    </div>
  </div>
</section>

Why this approach (not full block-in-block nesting)

There are two ways to enable composition:

Approach	Description	Complexity
A. portableText field type (this proposal)	Named rich text slots inside a block. Editors fill content into predefined slots.	Lower — one new Block Kit field type, TipTap sub-editors
B. Full block nesting	A PT block contains a drop zone for other PT blocks (arbitrary nesting). Editors compose freely.	Higher — recursive PT-in-PT, drag-and-drop reordering, depth limits

Approach A is the pragmatic first step. It covers the most common layout patterns (column sections, cards, accordions) with predictable structure. It's easier for editors to understand ("fill these columns") vs. free-form block composition.

Approach B could be a future enhancement — a blocks field type that accepts an array of any registered PT block type.

Scope considerations

• Depth limit: Nested portableText fields should support inserting PT blocks via slash commands, but with a configurable max depth (default: 1 level of nesting) to prevent infinite recursion in the editor.
• Performance: Inline TipTap sub-editors should lazy-load — only initialize when the block is expanded/focused.
• Data migration: No migration needed. Existing blocks without portableText fields are unaffected. The data shape is additive.

[wojtekpiskorz]

(I'lll gladly prepare a PR ofc :)