A quote.+``` + +into: + +```html +
A quote.+``` + +Applying it to a paragraph leaves the paragraph untouched, and the editor logs a warning in the browser console when it loads the format. Use `selector` when you never want conversion. + +### Selector formats + +A `selector` entry applies to the block tags you list and never changes the block's type: + +```json +{ "title": "Subheading", "selector": "h2,h3", "classes": "subheading" } +``` + +Applying it to an `
` or `` adds the class, turning:
+
+```html
+Section title
+```
+
+into:
+
+```html
+Section title
+```
+
+Applying it to a paragraph does nothing, because `p` is not in the entry's list:
+
+```html
+
Section title
+``` + +into: + +```html +Section title
+``` + +Applying it to a paragraph does nothing, because `p` is not in the entry's list: + +```html +Section title
+``` + +stays: + +```html +Section title
+``` + +### Grouped formats + +An `items` array groups entries into a submenu in the **Formats** dropdown: + +```json +{ + "title": "Callouts", + "items": [ + { "title": "Info", "block": "p", "classes": "callout callout-info" }, + { "title": "Warning", "block": "p", "classes": "callout callout-warning" } + ] +} +``` + +Groups support one level. A group nested inside another group is skipped, and a group whose entries are all invalid is dropped along with them. + +### Which tags a block format can target + +`block` and `selector` accept only tags the editor models as a node: + +`p`, `h1` through `h6`, `pre`, `blockquote`, `section`, `article`, `figure`, `figcaption`, `details`, `summary`, `dl`, `dt`, `dd`, `hr`, `img`, `ul`, `ol`, `li`, `table`, `tr`, `td`, `th`, `video`, `audio`, `iframe`. + +`div` and `span` are not on the list, so they cannot carry a block format. A `block: 'div'` entry is skipped. This matters when you migrate a TinyMCE configuration, since TinyMCE formats commonly wrap content in a `div`. It is the same reason a stored `` and `
`. The entry is skipped only when none of its tags are modelled.
+
+`selector` takes plain tag names. Compound CSS selectors such as `p.lead`, `div > p`, and `#main` are skipped rather than silently matching nothing.
+
+### Invalid entries are skipped
+
+An entry the editor cannot build is skipped, and the rest of the array still loads. Every skipped entry logs a warning to the **browser console**. Nothing appears in the interface, so check the console when a format does not show up in the dropdown.
+
+Entries are skipped when they:
+
+- Have no `title`.
+- Have none of `inline`, `block`, `selector`, or `items`.
+- Have no `classes` and no `attributes`, unless the entry is an `items` group.
+- Use `wrapper`, which is not supported.
+- Name only tags the editor does not model, such as `block: 'div'` or `selector: 'div,span'`.
+- Pass a compound CSS selector such as `p.lead` or `#main` instead of a plain tag name.
+- Pass a comma-separated list to `block` instead of `selector`.
+- Nest a group inside another group.
+
+## Gotchas
+
+### The editor does not load your frontend CSS
+
+::callout{icon="i-lucide-triangle-alert" color="warning"}
+The editor is not a preview of your site. Classes applied through custom formats have no styling attached in the Data Studio. The exception is [inline formats](#inline-formats), which write a `style` attribute into the content and do render in the editor.
+::
+
+Directus loads no project stylesheet into the editing surface, so a class like `lead`, `float-left`, or `text-center` has no visual effect inside the WYSIWYG. The class is stored and round-trips correctly. It just has nothing styling it in the Data Studio.
+
+This surprises authors, who apply a format, see no change, and assume it is broken. Point them at the **Formats** dropdown instead: it shows the active format in its label and highlights the matching row. That is the confirmation that a format applied, not the rendered content.
+
+The editor's own content styles can also contradict your class. The editor styles `figure` as `display: table; margin: 0.8125rem auto`, so a captioned image with a `float-left` class renders centered in the editor and floated on your frontend. The same applies to anything depending on `display`, `float`, `width`, or a flex or grid context your frontend provides.
+
+There is currently no option to inject custom CSS into the editor. The deprecated **Options Override** (`tinymceOverrides`) option is no longer applied, so TinyMCE's `content_css` has no equivalent.
+
+Because of this, layout classes are the riskiest thing to hand to non-technical authors: no feedback in the editor, and a result that depends entirely on CSS the editor cannot see. Prefer semantic formats such as `lead`, `callout`, or `subheading` over layout ones where you can.
+
+### `styles` on a block entry only styles the dropdown
+
+On an `inline` entry, `styles` is written into the content as a `style` attribute. On a `block` or `selector` entry, `styles` only styles the entry's label inside the **Formats** dropdown. It is not written to the content.
+
+The editor does not round-trip `style` on block nodes. Only `class`, `id`, `title`, `role`, `lang`, `dir`, `data-*`, and `aria-*` survive a save and load cycle. TinyMCE applied block `styles` to the block itself, so this is a behavior change to account for when migrating.
+
+Use `classes` for block styling and define the CSS on your frontend.
+
+### Attributes on a block entry are filtered
+
+`attributes` on a `block` or `selector` entry accepts only `id`, `title`, `role`, `lang`, `dir`, `data-*`, and `aria-*`. Anything else, including `style` and `target`, is dropped with a console warning.
+
+`attributes: { "class": "…" }` is merged into `classes`, so toggling the format off removes those classes too.
+
+Inline entries do not filter `attributes`.
+
+## Toggling behavior
+
+Selecting an active format in the dropdown removes it. Applying and removing a block format behaves as follows:
+
+- Removing a format strips only the classes and attributes that format configured. Unrelated classes, `id`, `data-*`, and `aria-*` on the same block survive.
+- The block keeps its tag. A `block: 'h2'` format does not turn the heading back into a paragraph when you remove it.
+- A format applies to every eligible block in the selection as a single undo step.
+- A format counts as active when every eligible block in the selection carries all of its classes, or all of its attributes for a format anchored on attributes alone.
+
+## Image captions
+
+Adding or editing an image opens a drawer with a **Caption** field. A non-empty caption wraps the image in a `
+
`, but only when the `