DOC-3147: New allow_html_in_comments option to allow HTML-like content inside comment data

modules/ROOT/pages/8.0-release-notes.adoc

@@ -1,4 +1,3 @@
-
 = {productname} {release-version}
 :release-version: 8.0.0
 :navtitle: {productname} {release-version}
@@ -110,10 +109,12 @@ For information on using Enhanced Skins & Icon Packs, see: xref:enhanced-skins-a
 
 {productname} {release-version} also includes the following addition<s>:
 
-// === <TINY-vwxyz 1 changelog entry>
-// #TINY-vwxyz1
+=== New `allow_html_in_comments` option to allow HTML-like content inside comment data
+// #TINY-12220
 
-// CCFR here.
+Previously, comments containing HTML-like content were removed from the editor's content by default for security reasons. This was done using DOMPurify's `SAFE_FOR_XML` option, which ensures that any HTML-like content in comments is stripped out.
+
+{productname} introduces a new configuration option, xref:content-filtering.adoc#allow_html_in_comments[allow_html_in_comments], to give users control over whether HTML-like content in comments should be retained or removed. By default, this content is removed for security, but setting the option to `true` allows HTML-like content in comments to be preserved when needed.
 
 
 [[changes]]

modules/ROOT/pages/content-filtering.adoc

@@ -5,6 +5,8 @@
 
 include::partial$configuration/allow_conditional_comments.adoc[]
 
+include::partial$configuration/allow_html_in_comments.adoc[]
+
 include::partial$configuration/allow_html_in_named_anchor.adoc[]
 
 include::partial$configuration/allow_mathml_annotation_encodings.adoc[]

modules/ROOT/pages/security.adoc

@@ -113,6 +113,8 @@ include::partial$configuration/sandbox_iframes.adoc[]
 
 include::partial$configuration/convert_unsafe_embeds.adoc[]
 
+include::partial$configuration/allow_html_in_comments.adoc[]
+
 [[insecure-transmission-and-storage-of-data]]
 === Insecure Transmission and Storage of data
 

modules/ROOT/partials/configuration/allow_html_in_comments.adoc

@@ -0,0 +1,48 @@
+[[allow_html_in_comments]]
+== `allow_html_in_comments`
+
+The `allow_html_in_comments` option allows HTML-like content to be retained in comments within the editor content. By default, {productname} removes comments containing HTML-like content as a security measure (using DOMPurify's `SAFE_FOR_XML` option).
+
+*Type:* `+Boolean+`
+
+*Default value:* `+false+`
+
+[WARNING]
+Setting this option to `true` may expose your application to XSS vulnerabilities. The DOMPurify maintainers have identified potential security risks when HTML-like content is allowed in comments. Only enable this option if you trust your content sources and understand the security implications.
+
+=== Example: using `allow_html_in_comments`
+
+The following example demonstrates how comments containing HTML are handled by default (removed) and how to configure {productname} to retain them:
+
+[source,js]
+----
+tinymce.init({
+  selector: 'textarea',
+  allow_html_in_comments: true,  // Enable HTML in comments
+});
+----
+
+ifeval::["{docname}" != "security"]
+=== Comment behavior examples
+
+With `allow_html_in_comments: false` (default), the editor's content after initialization will be:
+[source,html]
+----
+<section>
+<h1>Some content</h1>
+<h1>Some additional content</h1>
+</section>
+----
+
+With `allow_html_in_comments: true`, the editor's content after initialization will be:
+[source,html]
+----
+<section>
+<h1>Some content</h1>
+<!--
+  <div>This is my comment content</div>
+-->
+<h1>Some additional content</h1>
+</section>
+----
+endif::[]