docs: document block-level custom formats and image captions for WYSIWYG

[alvarosabu]

Documents the two user-facing additions in directus/directus#28044: block-level custom formats and image captions in the Tiptap-based WYSIWYG interface.

Summary

• New page guides/data-model/rich-text ("Rich Text", between Interfaces and Relationships). Covers the Custom Formats option in full, the gotchas, toggling semantics, <figure> caption output, and how to style the stored HTML on a frontend.
• Corrected guides/data-model/interfaces. The Custom Formats row read "Only inline formats are supported; block, selector, and wrapper formats are ignored", which #28044 makes false. Rewritten, plus a link callout to the new page.
• Renumbered 4.relationships.md → 5.relationships.md to open the slot. Prefix-only change, so the URL is unchanged.

Why a new page

WYSIWYG had one options table row and no page of its own. Nothing in /content covered consuming or styling rich text output, which is where most of this material belongs. The largest topic here (classes have no styling inside the editor) had no existing home, and the most detailed WYSIWYG prose in the repo was a v12 breaking-changes notice that stops being the right shelf as soon as v13 ships.

What the page documents

Custom Formats reference: the four entry keys (inline, block, selector, items), the classes/attributes anchor requirement, the list of tags a block format can target, and the eight reasons an entry gets skipped (all of which surface as browser-console warnings, not UI).

Three gotchas:

• The editor loads no project stylesheet, so custom-format classes have no visual effect in the Data Studio. The Formats dropdown label is the feedback that a format applied, not the rendered content. Includes the figure { display: table; margin: 0.8125rem auto } case, where a float-left figure renders centered in the editor and floated on the frontend.
• styles on a block or selector entry only styles the dropdown label. style is not round-tripped on nodes, which diverges from TinyMCE.
• attributes on a block entry is filtered to the preserved set; div and span cannot carry a block format, the same root cause as stored <div> wrappers being unwrapped on load.

Image captions: the drawer's Caption field, the <figure>/<figcaption> output shape, when clearing a caption unwraps the figure and when it does not, and the Enter/Backspace behavior inside a caption.

Verified against the implementation

Read the source on feat/tiptap-block-custom-formats rather than working from the handover notes. Four things the notes did not mention are documented:

• A selector entry containing one unmodelled tag is skipped entirely, not per-tag (custom-formats.ts:249).
• Inline entries do not filter attributes (custom-formats.ts:171); only block/selector entries do. The notes described only the block side.
• A group whose entries are all invalid is dropped along with them (buildGroup returns null on zero children).
• The notes' apper: true is a typo for wrapper (custom-formats.ts:317).

Wording is kept consistent with interfaces.input-rich-text-html.custom_formats_note in en-US.yaml:2781.

Test plan

• pnpm build exits 0 with zero prerender errors
• /docs/guides/data-model/rich-text prerenders
• /docs/guides/data-model/relationships URL unchanged after the renumber
• Sidebar order is Collections → Fields → Interfaces → Rich Text → Relationships
• All internal links and section anchors resolve in the built HTML
• Prose reviewed against the target release version (see below)

Part of CMS-2921

[linear-code]

CMS-2921

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
docs	Ready	Preview	Aug 7, 2026 12:57pm