[TASK] Add site config trouble shooting section (#694)

* [TASK] Add site config trouble shooting section releases: main, 13.4 * Apply suggestions from code review Co-authored-by: Stefan Frömken <[email protected]> * Apply suggestions from code review Co-authored-by: Stefan Frömken <[email protected]> --------- Co-authored-by: Stefan Frömken <[email protected]>
TYPO3-Documentation · Mar 1, 2025 · cb188c4 · cb188c4
1 parent ad56e09
commit cb188c4
Show file tree

Hide file tree

Showing 10 changed files with 136 additions and 5 deletions.
diff --git a/Documentation/FirstProject/SiteManagement/EmptyLanguage.png b/Documentation/FirstProject/SiteManagement/EmptyLanguage.png
diff --git a/Documentation/FirstProject/SiteManagement/Index.rst b/Documentation/FirstProject/SiteManagement/Index.rst
@@ -6,8 +6,10 @@
 Site Management
 ===============
 
-.. _siteconfiguration:
-.. _siterecords:
+..  contents:: Table of contents
+
+..  _siteconfiguration:
+..  _siterecords:
 ..  _site-configuration:
 
 Create a new site configuration
@@ -63,6 +65,135 @@ the reference "TYPO3 Explained".
 
 After saving, a new file should be created in your project:
 
-.. literalinclude:: _config.yaml
-   :language: yaml
-   :caption: config/sites/example_site/config.yaml
+..  literalinclude:: _config.yaml
+    :language: yaml
+    :caption: config/sites/example_site/config.yaml
+
+..  _site-management-trouble:
+
+Site management: Trouble shooting
+=================================
+
+..  accordion::
+    :name: siteManagementTrouble
+
+    ..  accordion-item:: Set of Site Package not available
+        :name: site-trouble-set-unavailable
+        :header-level: 2
+        :show:
+
+        If the set of your site package is not available make sure, that the
+        site package extension is `Installed <https://docs.typo3.org/permalink/t3start:installing-extensions>`_.
+
+        If the site package is installed but the site package set is still not
+        available the set or one of its dependencies might be corrupted.
+
+        ..  versionadded:: 13.4.5
+
+        ..  figure:: /FirstProject/SiteManagement/InvalidSiteSet.png
+            :alt: Screenshot of the "Site Configuration" module with an invalid site set displayed
+
+            Invalid site sets are listed in the "Site Configuration" module with reasons why they are invalid.
+
+        The site sets are cached. If you change the site set configuration and
+        see no difference, `clear the caches <https://docs.typo3.org/permalink/t3start:how-to-clear-cache>`_.
+
+    ..  accordion-item:: This site depends on invalid site sets
+        :name: site-trouble-set-invalid
+        :header-level: 2
+
+        If a set or one of its dependencies becomes corrupted after it has
+        already been added to a site configuration, an error box appears in
+        the table of configurations.
+
+        ..  figure:: /FirstProject/SiteManagement/InvalidDependency.png
+            :alt: Screenshot of the site configuration module with a site set that displays the error message "This site depends on invalid site sets".
+
+        This can happen for example when you uninstall an extension on which
+        your site package depends. In this case install the extension again or
+        remove the dependency from your site package.
+
+        The site sets are cached. If you change the site set configuration and
+        see no difference, `clear the caches <https://docs.typo3.org/permalink/t3start:how-to-clear-cache>`_.
+
+    ..  accordion-item:: On saving TYPO3 keeps creating empty language configurations
+        :name: site-trouble-duplicate-language
+        :header-level: 2
+
+        On saving the site settings TYPO3 keeps creating empty language
+        configurations.
+
+        This can happen if you deleted the language configuration with uid 0.
+        If you only need to use one language this one language has to have the
+        uid 0.
+
+        Edit the auto created language to fit your language needs.
+
+        ..  figure:: /FirstProject/SiteManagement/EmptyLanguage.png
+            :alt: An empty language configuration in the site settings prevents saving
+
+            Invalid site sets are listed in the "Site Configuration" module with reasons why they are invalid.
+
+        Sometimes it is easier to just edit the site configuration file:
+
+        ..  code-block:: diff
+
+             base: 'https://site-introduction.ddev.site/'
+             languages:
+               -
+                 title: English
+                 enabled: true
+                 locale: en-US
+                 hreflang: ''
+                 base: /
+                 websiteTitle: ''
+                 navigationTitle: ''
+                 flag: global
+            -    languageId: 1
+            +    languageId: 0
+             rootPageId: 1
+             websiteTitle: ''
+
+        Change the language id of the only language from 1 to 0.
+
+    ..  accordion-item:: Malformed inline YAML string at line 17
+        :name: site-trouble-yaml
+        :header-level: 2
+
+        If you manually edited the site configuration and it contains a syntax
+        error, the whole backend module might stop working:
+
+        ..  figure:: /FirstProject/SiteManagement/MalformedYAML.png
+            :alt: Whoops, looks like something went wrong: Malformed inline YAML string at line 17.
+
+            Malformed YAML can only be corrected by editing the config file.
+
+        Fix or delete the affected site configuration by editing the file, for
+        example :file:`config/sites/my-site/config.yaml`.
+
+    ..  accordion-item:: No pages found
+        :name: site-trouble-no-pages
+        :header-level: 2
+
+        If you see the following you cannot add any site configuration until
+        you fix the problem in the page tree:
+
+        ..  figure:: /FirstProject/SiteManagement/NoPagesFound.png
+            :alt: No pages found! Please add at least one page through the Page module.
+
+            Malformed YAML can only be corrected by editing the config file.
+
+        If you have not created any pages yet,
+        `create a root page <https://docs.typo3.org/permalink/t3start:create-root-page>`_
+        first.
+
+        If you have created pages but still see the message, set the flag
+        "Use as Root Page" in the page properties, tab "Behavior" for the page
+        that should be the startpage of your site. A root page is displayed with
+        a globe icon in the page tree.
+
+        ..  figure:: /FirstProject/SiteManagement/MarkPageAsRootpage.png
+            :alt: Option "Use as Root Page" in the page properties.
+
+            At least one root page is required before you can create a site configuration.
+
diff --git a/Documentation/FirstProject/SiteManagement/InvalidDependency.png b/Documentation/FirstProject/SiteManagement/InvalidDependency.png
diff --git a/Documentation/FirstProject/SiteManagement/InvalidSiteSet.png b/Documentation/FirstProject/SiteManagement/InvalidSiteSet.png
diff --git a/Documentation/FirstProject/SiteManagement/MalformedYAML.png b/Documentation/FirstProject/SiteManagement/MalformedYAML.png
diff --git a/Documentation/FirstProject/SiteManagement/MarkPageAsRootpage.png b/Documentation/FirstProject/SiteManagement/MarkPageAsRootpage.png
diff --git a/Documentation/FirstProject/SiteManagement/NewSite.png b/Documentation/FirstProject/SiteManagement/NewSite.png
diff --git a/Documentation/FirstProject/SiteManagement/NewSitePage1.png b/Documentation/FirstProject/SiteManagement/NewSitePage1.png
diff --git a/Documentation/FirstProject/SiteManagement/NewSitePageLanguage.png b/Documentation/FirstProject/SiteManagement/NewSitePageLanguage.png
diff --git a/Documentation/FirstProject/SiteManagement/NoPagesFound.png b/Documentation/FirstProject/SiteManagement/NoPagesFound.png