[DOCS] Document usage of "htmlSupport" option in EXT:rte_ckeditor

Additionally:
- Use "page TSconfig" over "Page TSconfig"
- Add captions to make clearer where to store the configuration as an example

Resolves: #102126
Resolves: https://github.com/TYPO3-Documentation/Changelog-To-Doc/issues/686
Related: #99738
Releases: main, 12.4
Change-Id: I983a9411c3c30ddf040eba0c296a2bee6c0ab509
Reviewed-on: https://review.typo3.org/c/Packages/TYPO3.CMS/+/81383


Reviewed-by: Torben Hansen <derhansen@gmail.com>
Tested-by: Torben Hansen <derhansen@gmail.com>
Tested-by: Benjamin Franzke <ben@bnf.dev>
Tested-by: core-ci <typo3@b13.com>
Reviewed-by: Benjamin Franzke <ben@bnf.dev>

typo3/sysext/rte_ckeditor/Documentation/Configuration/Concepts.rst

@@ -145,16 +145,17 @@ can be set via :ref:`t3tca:columns-text-properties-richtextConfiguration`, setti
 
 .. _override-configuration-via-page-tsconfig:
 
-Overriding Configuration via Page TSconfig
+Overriding Configuration via page TSconfig
 ------------------------------------------
 
 Instead of overriding all TCA fields to use a custom preset, it is possible
-to override this information via Page TSconfig.
+to override this information via page TSconfig.
 
 The option :typoscript:`RTE.default.preset = news` can also be set on a per-field
 and per-type basis:
 
 .. code-block:: typoscript
+   :caption: EXT:my_sitepackage/Configuration/page.tsconfig
    :linenos:
 
    # per-field
@@ -172,10 +173,13 @@ line #4
 
 Of course, any other specific option set via YAML can be overridden via Page TSconfig as well:
 
+Specific options set via YAML can be overridden via page TSconfig as well - but
+be aware that boolean values can not be set, and arrays are not merged but
+overridden.
+
 .. code-block:: typoscript
+   :caption: EXT:my_sitepackage/Configuration/page.tsconfig
 
-   # Allow iframe tag with all attributes and all styles in bodytext field of content elements (Requires additional processing configuration)
-   RTE.config.tt_content.bodytext.editor.config.extraAllowedContent = iframe[*]{*}
    # Restrict format_tags to h2 in bodytext field of content elements
    RTE.config.tt_content.bodytext.editor.config.format_tags = h2
 
@@ -183,7 +187,7 @@ The loading order for configuration is:
 
 #. ``preset`` defined for a specific field via PageTS
 #. ``richtextConfiguration`` defined for a specific field via TCA
-#. general preset defined via PageTS
+#. general preset defined via page TSconfig
 #. ``default``
 
 

typo3/sysext/rte_ckeditor/Documentation/Configuration/Examples.rst

@@ -10,9 +10,10 @@ How do I use a different preset?
 ================================
 
 Instead of using the default "default" preset, you can change this, for example
-to "full", using **Page TSconfig**:
+to "full", using **page TSconfig**:
 
 .. code-block:: typoscript
+   :caption: EXT:my_sitepackage/Configuration/page.tsconfig
 
    RTE.default.preset = full
 
@@ -24,6 +25,7 @@ Additionally, you can set specific presets for specific types of textfields.
 For example to use preset "full" for the field "bodytext" of all content elements:
 
 .. code-block:: typoscript
+   :caption: EXT:my_sitepackage/Configuration/page.tsconfig
 
    RTE.config.tt_content.bodytext.preset = full
 
@@ -31,6 +33,7 @@ To use preset "minimal" for the field "bodytext" of only content elements
 with ctype="text":
 
 .. code-block:: typoscript
+   :caption: EXT:my_sitepackage/Configuration/page.tsconfig
 
    RTE.config.tt_content.bodytext.types.text.preset = minimal
 
@@ -46,16 +49,20 @@ In :file:`ext_localconf.php`, replace `my_extension` with your extension key, re
 with the name of your preset.
 
 .. code-block:: php
+   :caption: EXT:my_sitepackage/ext_localconf.php
 
    $GLOBALS['TYPO3_CONF_VARS']['RTE']['Presets']['my_preset'] = 'EXT:my_extension/Configuration/RTE/MyPreset.yaml';
 
-In :file:`Configuration/RTE/MyPreset.yaml`, create your configuration, for example::
+In :file:`Configuration/RTE/MyPreset.yaml`, create your configuration, for example:
+
+.. code-block:: yaml
+   :caption: EXT:my_sitepackage/Configuration/RTE/MyPreset.yaml
 
    # Import basic configuration
    imports:
-    - { resource: "EXT:rte_ckeditor/Configuration/RTE/Processing.yaml" }
-    - { resource: "EXT:rte_ckeditor/Configuration/RTE/Editor/Base.yaml" }
-    - { resource: "EXT:rte_ckeditor/Configuration/RTE/Editor/Plugins.yaml" }
+     - { resource: "EXT:rte_ckeditor/Configuration/RTE/Processing.yaml" }
+     - { resource: "EXT:rte_ckeditor/Configuration/RTE/Editor/Base.yaml" }
+     - { resource: "EXT:rte_ckeditor/Configuration/RTE/Editor/Plugins.yaml" }
    # Add configuration for the editor
    # For complete documentation see http://docs.ckeditor.com/#!/api/CKEDITOR.config
    editor:
@@ -73,6 +80,7 @@ configuration of the minimal editor setup included in file
 :file:`EXT:rte_ckeditor/Configuration/RTE/Minimal.yaml`:
 
 .. code-block:: yaml
+   :caption: EXT:my_sitepackage/Configuration/RTE/MyPreset.yaml
 
    # Minimal configuration for the editor
    editor:
@@ -101,6 +109,7 @@ possible to group several items into a dropdown as shown in the following
 example:
 
 .. code-block:: yaml
+   :caption: EXT:my_sitepackage/Configuration/RTE/MyPreset.yaml
 
    # Minimal configuration for the editor
    editor:
@@ -112,6 +121,33 @@ example:
            - { label: 'Additional', icon: 'threeVerticalDots', items: [ 'specialCharacters', 'horizontalLine' ] }
 
 
+How do I allow a specific tag?
+==============================
+
+Allowed content in CKEditor5 is to be configured via the General HTML Support
+plugin option :yaml:`config.htmlSupport`.
+
+.. code-block:: yaml
+   :caption: EXT:my_sitepackage/Configuration/RTE/MyPreset.yaml
+
+   # Allow the <iframe> tag with all attributes, all classes and all styles:
+   RTE:
+     config:
+       htmlSupport:
+         allow:
+           - { name: 'iframe', attributes: true, classes: true, styles: true }
+
+.. note::
+   :yaml:`config.htmlSupport` only applies to elements that are "known" to
+   CKEditor5. Tags like :html:`<svg>` or custom elements like
+   :html:`<my-element>` are not configurable this way as
+   :yaml:`htmlSupport.allow` can only handle
+   elements that are defined in the `CKEditor5 schema`_.
+
+.. _CKEditor5 schema: https://ckeditor.com/docs/ckeditor5/latest/features/html/general-html-support.html#enabling-custom-elements
+
+
+
 .. _config-example-customplugin:
 
 How do I create a custom plugin?