[TASK] Improve "Create a root page" chapter

releases: main, 13.4

Author: linawolf

Documentation/FirstProject/CreateRootPage.rst

@@ -1,9 +1,9 @@
 :navigation-title: Root page
 ..  include:: /Includes.rst.txt
 
-.. index:: site, domain configuration, languages
+..  index:: site, domain configuration, languages
 
-.. _create-root-page:
+..  _create-root-page:
 
 =========================
 How to create a root page
@@ -14,55 +14,114 @@ It serves as the top-level page in the page tree and is essential for
 configuring the site and making it available to users. In this tutorial,
 you will learn how to create a root page in TYPO3 v13.
 
-..  note::
+..  admonition:: Prerequisites
+
     *   You have TYPO3 :ref:`installed <t3start:installation-ddev-tutorial>`
         and can log into the backend.
     *   You have access to the Page module and permission to create pages.
-    *   You are familiar with the basic layout of the TYPO3 backend.
+    *   You are familiar with the basic layout of the TYPO3
+        `Backend <https://docs.typo3.org/permalink/t3start:backend>`_.
+
+..  contents:: Steps to create a root package
+
+..  _create-root-page-new-page:
+
+Create a new page on root level
+===============================
+
+Once you log into the TYPO3 backend, locate the :guilabel:`Web > Page` module on the left-hand
+side of the screen. Click on the Page module to open the page tree.
+
+..  figure:: /Images/ManualScreenshots/CreateRootPage/CreateNewPage.png
+    :alt: The "Page" module in the TYPO3 backend with a context menu to create a new page
+
+*   In the page tree, right-click on the "root level" or the top node of the page
+    tree (if no pages exist yet, this will likely be labeled as "site" or similar).
+    A context menu will appear.
+
+*   From the context menu, select "New". This will open a form for creating a new
+    page.
+
+..  _create-root-page-configure:
+
+Configure the newly created page
+================================
+
+Now, you need to configure the new page:
+
+*   In the form that appears, give your new page a name.
+    This will be the label of your root page in the page tree.
+
+*   Under the :guilabel:`Behaviour` tab, look for the checkbox called
+    "Use as Root Page". Ensure this is checked.
+
+..  figure:: /Images/ManualScreenshots/CreateRootPage/SetRootPage.png
+    :alt: Page properties, tab "Behaviour", highlighting the "Use as root page"
+
+..  _create-root-page-save:
+
+Save the page
+=============
+
+Once you have filled in the necessary information and selected the
+"Use as Root Page" option, click the "Save" button at the top of the
+form. Your new root page will now appear in the page tree on the left.
+The page is only visible in the Backend at this point
+
+..  figure:: /Images/ManualScreenshots/CreateRootPage/PageCreated.png
+    :alt: Backend module "Page" with a newly created but still disabled root page
+
+    The root page is disabled, therefore it is marked with the red icon.
+    You can enable it in the context menu.
+
+..  _create-root-page-site:
 
-..  rst-class:: bignums-xxl
-#.  Access the Page module
+Configure the site
+==================
 
-    Once you log into the TYPO3 backend, locate the :guilabel:`Web > Page` module on the left-hand
-    side of the screen. Click on the Page module to open the page tree.
+You need a `Site configuration <https://docs.typo3.org/permalink/t3start:site-management>`_.
+If you started in a freshly installed TYPO3 installation the site configuration
+was auto-created and you can edit it:
 
-    .. figure:: /Images/ManualScreenshots/CreateRootPage/PageModule.png
+..  figure:: /Images/ManualScreenshots/CreateRootPage/AutogeneratedSiteConfig.png
+    :alt: The auto-generated site of a new root page viewed in the "Sites" module
 
-#.  Create a new root page
+    You can find the auto-generated site for your root page in the module :guilabel:`Site Management > Sites`
 
-    *   In the page tree, right-click on the "root level" or the top node of the page
-        tree (if no pages exist yet, this will likely be labeled as "site" or similar).
-        A context menu will appear.
+..  _create-root-page-site-package:
 
-    *   From the context menu, select "New". This will open a form for creating a new
-        page.
+Create a site package for the theme
+===================================
 
-    .. figure:: /Images/ManualScreenshots/CreateRootPage/CreateNewPage.png
+The site needs a theme, called "site package" in the TYPO3 world.
+See chapter
+`site package <https://docs.typo3.org/permalink/t3start:creating-a-site-package>`_.
 
-    *   Alternatively, you can select a new page from the menu above the
-        page tree using drag & drop and place it in the page tree.
+..  admonition:: Trouble shooting
 
-    .. figure:: /Images/ManualScreenshots/CreateRootPage/PageMenu.png
+    TYPO3 does not come with a default theme you need to install
+    or create a site package. Otherwise you will see a message like the
+    following when trying to display the page in the frontend:
 
+    ..  figure:: /Images/ManualScreenshots/CreateRootPage/NoTypoScriptFound.png
+        :alt: Error message: No TypoScript record found!
 
-#.  Set the page type to root
+        Error message when no site package is installed or configured
 
-    Now, you need to configure the new page:
+    *   `How to create a site package <https://docs.typo3.org/permalink/t3start:how-to-create-a-site-package>`_
+    *   `Troubleshooting "No TypoScript found!" <https://docs.typo3.org/permalink/t3tsref:guide-troubleshooting>`_
+    *   Use the `Introduction Package <https://docs.typo3.org/permalink/t3start:introductionpackage-index>`_
+        with a ready to use theme and predefined content.
 
-    *   In the form that appears, give your new page a name.
-        This will be the label of your root page in the page tree.
+..  _create-root-page-enable:
 
-    *   Under the :guilabel:`Behaviour` tab, look for the checkbox called
-        "Use as Root Page". Ensure this is checked.
+Enable the page once ready
+==========================
 
-    .. figure:: /Images/ManualScreenshots/CreateRootPage/SetRootPage.png
+:guilabel:`Enable` the page as newly created pages are hidden by default.
 
-#.  Save the page
+..  figure:: /Images/ManualScreenshots/CreateRootPage/EnablePage.png
+    :alt: A disabled root page and its context menu
 
-    Once you have filled in the necessary information and selected the
-    "Use as Root Page" option, click the "Save" button at the top of the
-    form. Your new root page will now appear in the page tree on the left.
+    Right click on the newly created page and chose `Enable` from the context menu. The red icon should disappear.
 
-    ..  note::
-        By default, a newly created page is disabled. You need to enable it to
-        make the page publicly visible.