From f9932d34609a7b22fc77767379006f42b6012803 Mon Sep 17 00:00:00 2001
From: Karl Kemister-Sheppard <karlkemistersheppard@gmail.com>
Date: Tue, 7 Jul 2026 16:27:10 +1000
Subject: [PATCH] DOC-3531: Document expand and split format parameters for
 content formatting

---
 .../ROOT/partials/configuration/formats.adoc  | 54 ++++++++++++++++++-
 1 file changed, 53 insertions(+), 1 deletion(-)

diff --git a/modules/ROOT/partials/configuration/formats.adoc b/modules/ROOT/partials/configuration/formats.adoc
index cf09a164e0..95a493c0eb 100644
--- a/modules/ROOT/partials/configuration/formats.adoc
+++ b/modules/ROOT/partials/configuration/formats.adoc
@@ -321,7 +321,7 @@ So if the selection is from _a_ to _b_ in this html contents `+<h1><b>[a</b></h1
 
 *Type:* `+Boolean+`
 
-+Default value:* `+false+`
+*Default value:* `+false+`
 
 *Possible values:* `+true+`, `+false+`
 
@@ -355,6 +355,58 @@ tinymce.init({
 });
 ----
 
+[[expand]]
+==== `+expand+`
+
+Controls whether the selection is expanded to include the entire matching element before a format is applied or removed. This applies to `+selector+` formats that are not also `+inline+` formats. When enabled, if the selection only partially covers a matching element, the range is expanded to cover the whole element. Setting `+expand+` to `+false+` restricts the operation to the current selection.
+
+*Type:* `+Boolean+`
+
+*Default value:* `+true+` for `+selector+` formats
+
+*Possible values:* `+true+`, `+false+`
+
+===== Example: using `+expand+`
+
+[source,js]
+----
+tinymce.init({
+  selector: 'textarea',  // change this value according to your HTML
+  formats: {
+    removeformat: [
+      // Restrict removal to the current selection instead of expanding to the whole matching element
+      { selector: 'h1,h2,h3,h4,h5,h6', remove: 'all', expand: false, deep: true }
+    ]
+  }
+});
+----
+
+[[split]]
+==== `+split+`
+
+Used when removing a format. Controls whether the element wrapping the selection is split at the selection boundaries so that the format is removed only from the selected text. When set to `+false+`, the wrapping element is not split, so the format is not removed from a partial selection.
+
+*Type:* `+Boolean+`
+
+*Default value:* `+true+` for `+inline+` formats and non-`+selector+` formats; `+false+` for `+selector+` (block) formats.
+
+*Possible values:* `+true+`, `+false+`
+
+===== Example: using `+split+`
+
+[source,js]
+----
+tinymce.init({
+  selector: 'textarea',  // change this value according to your HTML
+  formats: {
+    removeformat: [
+      // Remove the format without splitting the wrapping element at the selection boundaries
+      { selector: 'span', attributes: ['style', 'class'], remove: 'empty', split: false, deep: true }
+    ]
+  }
+});
+----
+
 [[deep]]
 ==== `+deep+`