From 46e99ece566c5ffd1a57f74d5e6ed9592562b4eb Mon Sep 17 00:00:00 2001
From: "github-actions[bot]"
 <41898282+github-actions[bot]@users.noreply.github.com>
Date: Sun, 22 Dec 2024 22:41:11 +0100
Subject: [PATCH] [Backport 12.4] [TASK] Fix description of
 additionalCanonicalizedUrlParameters (#5158)

---
 .../ApiOverview/Seo/CanonicalApi.rst          | 33 +++++++++++--------
 .../Configuration/Typo3ConfVars/FE.rst        |  3 +-
 2 files changed, 21 insertions(+), 15 deletions(-)

diff --git a/Documentation/ApiOverview/Seo/CanonicalApi.rst b/Documentation/ApiOverview/Seo/CanonicalApi.rst
index ba40f1a84d..22dfabb8f5 100644
--- a/Documentation/ApiOverview/Seo/CanonicalApi.rst
+++ b/Documentation/ApiOverview/Seo/CanonicalApi.rst
@@ -16,27 +16,32 @@ cHash.
    EXT:seo. You can find information about how to install and use it in the
    :doc:`EXT:seo manual <ext_seo:Index>`.
 
-Excluding arguments from the generation
-=======================================
+.. _canonicalapi-additionalparameters:
 
-TYPO3 will fallback to building a URL of current page and appending query strings.
-It is possible to exclude specific arguments from being appended.
-This is achieved by adding those arguments to a PHP variable:
+Including specific arguments for the URL generation
+===================================================
 
-.. code-block:: php
-   :caption: EXT:site_package/ext_localconf.php
+TYPO3 will building a URI of the current page and append query strings
+which are needed for the cHash calculation (vital arguments to uniquely identify
+the given content URI). This is especially important with for example detail pages of records. The query parameters are crucial to show the right content.
 
-   $GLOBALS['TYPO3_CONF_VARS']['FE']['additionalCanonicalizedUrlParameters'][] = 'example_argument_name';
+It is possible to additionally include specific arguments.
+This is achieved by adding those arguments to the configuration:
 
-It is possible to exclude nested arguments:
+..  code-block:: php
+    :caption: EXT:site_package/ext_localconf.php
 
-.. code-block:: php
-   :caption: EXT:site_package/ext_localconf.php
+    $GLOBALS['TYPO3_CONF_VARS']['FE']['additionalCanonicalizedUrlParameters'][] = 'example_argument_name';
 
-   $GLOBALS['TYPO3_CONF_VARS']['FE']['additionalCanonicalizedUrlParameters'][] = 'example_argument_name[second_level]';
+It is possible to include nested arguments:
 
-Arguments in general should be excluded from cHash as well as ``additionalCanonicalizedUrlParameters``.
-See the possible options in :ref:`caching`, regarding excluding arguments from cHash.
+..  code-block:: php
+    :caption: EXT:site_package/ext_localconf.php
+
+    $GLOBALS['TYPO3_CONF_VARS']['FE']['additionalCanonicalizedUrlParameters'][] = 'example_argument_name[second_level]';
+
+Non-vital arguments in general should be excluded from cHash and not be listed as ``additionalCanonicalizedUrlParameters``.
+See the possible options in :ref:`caching` regarding excluding arguments from cHash.
 
 The idea behind that is:
 
diff --git a/Documentation/Configuration/Typo3ConfVars/FE.rst b/Documentation/Configuration/Typo3ConfVars/FE.rst
index 69c8745871..d31a118e02 100644
--- a/Documentation/Configuration/Typo3ConfVars/FE.rst
+++ b/Documentation/Configuration/Typo3ConfVars/FE.rst
@@ -462,7 +462,8 @@ the TYPO3 frontend:
     :type: array
     :Default: []
 
-    The given parameters will be included when calculating canonicalized URL
+    The given parameters will be included when calculating canonicalized URL.
+    See :ref:`canonicalapi-additionalparameters` for details.
 
 ..  _typo3ConfVars_fe_cacheHash: