Add notes about imports usage in site config and settings

Documentation/ApiOverview/SiteHandling/Basics.rst

@@ -104,14 +104,16 @@ Root pages are identified by one of these two properties:
     same root page ID is used multiple times.
 
 
-.. _sitehandling-basics-websiteTitle:
+..  _sitehandling-basics-websiteTitle:
 
 websiteTitle
 ------------
 
 The title of the website which is used in :html:`<title>` tag in the frontend.
 
 
+..  _sitehandling-basics-base:
+
 base
 ----
 
@@ -147,6 +149,8 @@ a `converter`_ to get the ACE format of the domain name.
     In this case, the site administrator must set unique site base prefixes.
 
 
+..  _sitehandling-basics-languages:
+
 languages
 ---------
 
@@ -155,6 +159,8 @@ both the availability of the language and the behavior. For a detailed
 description see :ref:`Language configuration <sitehandling-addingLanguages>`.
 
 
+..  _sitehandling-basics-errorHandling:
+
 errorHandling
 -------------
 
@@ -164,6 +170,8 @@ more. For a detailed description, see :ref:`error handling
 <sitehandling-errorHandling>`.
 
 
+..  _sitehandling-basics-routes:
+
 routes
 ------
 
@@ -173,6 +181,8 @@ The routes section is used to add static routes to a site, for example a
 Read more at :ref:`static routes<sitehandling-staticRoutes>`.
 
 
+..  _sitehandling-basics-routeEnhancers:
+
 routeEnhancers
 --------------
 
@@ -181,3 +191,43 @@ routeEnhancers
 While page routing works out of the box without any further settings, route
 enhancers allow configuring routing for TYPO3 extensions. Read more at
 :ref:`routing-advanced-routing-configuration`.
+
+
+..  _sitehandling-basics-settings:
+
+settings
+--------
+
+The `settings` section can be used to define custom site settings. These values
+are available in PHP code, TypoScript and Fluid templates. For further details,
+see :ref:`sitehandling-settings`.
+
+..  note::
+    If a folder contains a `settings.yaml` file, all `settings` defined in
+    `config.yaml` are ignored. Only the values from `settings.yaml` are
+    applied.
+
+    When you or your customer manage site settings via the *Site Settings* module
+    in the TYPO3 backend, TYPO3 automatically creates (or updates) the
+    `settings.yaml` file. As a result, the configuration in `config.yaml` is
+    no longer considered.
+
+    To avoid confusion, it is recommended to **remove** the obsolete `settings`
+    section from `config.yaml` if `settings.yaml` is in use.
+
+
+..  _sitehandling-basics-imports:
+
+imports
+-------
+
+The imports section can be used to import additional YAML files into the site
+configuration. This can be used to split large configurations into smaller
+parts or to share common configuration parts between multiple sites. The path
+is relative to the site configuration folder.
+
+..  code-block:: yaml
+    :caption: EXT:site_package/Configuration/Sets/SitePackage/config.yaml
+
+    imports:
+      - { resource: 'RouteEnhancers.yaml' }

Documentation/ApiOverview/SiteHandling/SiteSettingDefinitions.rst

@@ -22,8 +22,8 @@ TypoScript Constants.
 
 All available settings are displayed in the :ref:`site-settings-editor`.
 
-The site settings provided by an extension can be automatically documented in the
-extensions manual, see
+The site settings provided by an extension can be automatically documented in
+the extensions manual, see
 :ref:`site settings documentation <h2document:reference-site-settings>`.
 
 ..  contents:: Table of contents
@@ -122,6 +122,10 @@ Site setting definition properties
             ..  literalinclude:: _Settings/_enum_settings.definitions.yaml
                 :caption: EXT:my_extension/Configuration/Sets/MySet/settings.definitions.yaml
 
+..  note::
+    The `settings.definitions.yaml` does not allow any kind of imports. All
+    settings must be defined in a single file.
+
 ..  _definition-types:
 
 Definition types

Documentation/ApiOverview/SiteHandling/SiteSettings.rst

@@ -34,8 +34,25 @@ For instance, settings can be used in custom frontend code to deliver features
 which might vary per site for extensions. An example may be to configure
 storage page IDs.
 
-The settings are defined in the :file:`config/sites/<my_site>/settings.yaml <set-settings-yaml>`
-file.
+All changes made in the site settings editor are stored in the `settings.yaml`
+file located in `config/sites/<my_site>/`. If this file does not exist, TYPO3
+will create it automatically.
+
+..  note::
+    You *can* use `imports` in `settings.yaml`. However, as soon as you save
+    changes in the site settings editor, TYPO3 rewrites the file and all
+    `imports` will be removed.
+
+To store values independently of the site settings editor, use the
+`settings.yaml` file in the folder `Configuration/Sets/<my_site>/` of your
+site package. This file itself remains untouched, but its values are
+overwritten by values from the `settings.yaml` in `config/sites/<my_site>/`.
+
+..  note::
+    As this file is not modified by the site settings editor, you can safely
+    use `imports` here if needed. Absolute paths, relative paths and the
+    `EXT:` syntax are supported.
+
 
 ..  _sitehandling-settings-add: