docs: place template-override settings inside preUserFunc.

Configuration/TypoScript/ImageRendering/setup.typoscript

@@ -25,18 +25,29 @@ lib.parseFunc_RTE {
         # IMPORTANT: Use the extension key "rte_ckeditor_image" (underscores) in
         # EXT: paths, NOT the Composer package name "rte-ckeditor-image" (hyphens).
         #
-        # To override, add your paths with priority > 0:
+        # To override, add your paths with priority > 0 INSIDE preUserFunc. —
+        # TYPO3's stdWrap_preUserFunc only forwards $conf['preUserFunc.'] to the
+        # callable, so a settings. block placed as a sibling of preUserFunc
+        # never reaches ImageRenderingService::buildTemplatePaths().
         #
-        # settings.templateRootPaths {
-        #     10 = EXT:my_sitepackage/Resources/Private/Templates/
-        # }
-        # settings.partialRootPaths {
-        #     10 = EXT:my_sitepackage/Resources/Private/Partials/
-        # }
-        # settings.layoutRootPaths {
-        #     10 = EXT:my_sitepackage/Resources/Private/Layouts/
+        # preUserFunc {
+        #     settings {
+        #         templateRootPaths {
+        #             10 = EXT:my_sitepackage/Resources/Private/Templates/
+        #         }
+        #         partialRootPaths {
+        #             10 = EXT:my_sitepackage/Resources/Private/Partials/
+        #         }
+        #         layoutRootPaths {
+        #             10 = EXT:my_sitepackage/Resources/Private/Layouts/
+        #         }
+        #     }
         # }
         #
+        # The same settings. block must also be added under
+        # lib.parseFunc_RTE.externalBlocks.figure.stdWrap.preUserFunc for
+        # captioned (figure-wrapped) images.
+        #
         # See Documentation/Examples/Template-Overrides.rst for details.
         #******************************************************
 

Documentation/Examples/Template-Overrides.rst

@@ -190,34 +190,57 @@ In your site package, create the override directory:
 Step 2: Configure TypoScript
 ----------------------------
 
-Add the template path to your TypoScript setup:
+Add the template path to your TypoScript setup. The ``settings.`` block
+must live **inside** ``preUserFunc.`` — that is the only sub-array TYPO3
+forwards to the rendering callable (see
+:php:`ContentObjectRenderer::stdWrap_preUserFunc()`, which passes only
+``$conf['preUserFunc.']`` to the user function). Placing
+``settings.templateRootPaths`` as a sibling of ``preUserFunc`` has no
+effect — the configuration never reaches
+:php:`ImageRenderingService::buildTemplatePaths()`.
 
 ..  code-block:: typoscript
     :caption: EXT:my_sitepackage/Configuration/TypoScript/setup.typoscript
 
-    lib.parseFunc_RTE.tags.img {
+    lib.parseFunc_RTE.tags.img.preUserFunc {
         # Add your templates with higher priority (higher number = higher priority)
-        settings.templateRootPaths {
-            10 = EXT:my_sitepackage/Resources/Private/Templates/
+        settings {
+            templateRootPaths {
+                10 = EXT:my_sitepackage/Resources/Private/Templates/
+            }
+            partialRootPaths {
+                10 = EXT:my_sitepackage/Resources/Private/Partials/
+            }
+            layoutRootPaths {
+                10 = EXT:my_sitepackage/Resources/Private/Layouts/
+            }
         }
-        settings.partialRootPaths {
-            10 = EXT:my_sitepackage/Resources/Private/Partials/
-        }
-        settings.layoutRootPaths {
-            10 = EXT:my_sitepackage/Resources/Private/Layouts/
+    }
+
+    # Captioned images render as <figure> blocks and are processed via
+    # externalBlocks.figure.stdWrap.preUserFunc (renderFigure). The same
+    # settings. block has to be duplicated here for figure rendering.
+    lib.parseFunc_RTE.externalBlocks.figure.stdWrap.preUserFunc {
+        settings {
+            templateRootPaths {
+                10 = EXT:my_sitepackage/Resources/Private/Templates/
+            }
+            partialRootPaths {
+                10 = EXT:my_sitepackage/Resources/Private/Partials/
+            }
+            layoutRootPaths {
+                10 = EXT:my_sitepackage/Resources/Private/Layouts/
+            }
         }
     }
 
 ..  note::
 
-    The configuration must be placed within ``lib.parseFunc_RTE.tags.img``
-    (not directly in ``lib.parseFunc_RTE``). The same configuration can be
-    added to ``externalBlocks.figure.stdWrap`` for images wrapped in
-    ``<figure>`` blocks (captioned images). Figures are processed via
-    ``externalBlocks``, not ``tags.figure`` — placing the configuration
-    under ``tags.figure`` has no effect. Inline images wrapped in ``<a>``
-    are rendered by ``tags.img`` (recursively, inside the link wrapper), so
-    they already pick up the configuration defined under ``tags.img``.
+    Figures are processed via ``externalBlocks``, not ``tags.figure`` —
+    placing the configuration under ``tags.figure`` has no effect. Inline
+    images wrapped in ``<a>`` are rendered by ``tags.img`` (recursively,
+    inside the link wrapper), so they already pick up the configuration
+    defined under ``tags.img.preUserFunc``.
 
 Step 3: Create override templates
 ---------------------------------

Resources/AGENTS.md

@@ -66,15 +66,33 @@ Figure wrappers are only created when there is a caption. Alignment classes with
 
 ## Template Override Mechanism
 
-Integrators can override templates via TypoScript:
+Integrators can override templates via TypoScript. The `settings.` block
+must live inside `preUserFunc.` because TYPO3 only passes
+`$conf['preUserFunc.']` to the rendering callable (see
+`ContentObjectRenderer::stdWrap_preUserFunc()`):
 
 ```typoscript
-lib.parseFunc_RTE.tags.img {
-    settings.templateRootPaths {
-        10 = EXT:my_sitepackage/Resources/Private/Templates/
+lib.parseFunc_RTE.tags.img.preUserFunc {
+    settings {
+        templateRootPaths {
+            10 = EXT:my_sitepackage/Resources/Private/Templates/
+        }
+        partialRootPaths {
+            10 = EXT:my_sitepackage/Resources/Private/Partials/
+        }
     }
-    settings.partialRootPaths {
-        10 = EXT:my_sitepackage/Resources/Private/Partials/
+}
+
+# Figures (captioned images) need the same block under the
+# externalBlocks.figure.stdWrap.preUserFunc that runs renderFigure().
+lib.parseFunc_RTE.externalBlocks.figure.stdWrap.preUserFunc {
+    settings {
+        templateRootPaths {
+            10 = EXT:my_sitepackage/Resources/Private/Templates/
+        }
+        partialRootPaths {
+            10 = EXT:my_sitepackage/Resources/Private/Partials/
+        }
     }
 }
 ```