[TASK] Improve Introduction Package page

References: #546
Releases: main, 13.4, 12.4

Author: linawolf

Documentation/Extensions/InstallingExtensions.rst

@@ -1,6 +1,6 @@
-.. include:: /Includes.rst.txt
+..  include:: /Includes.rst.txt
 
-.. _installing-extensions:
+..  _installing-extensions:
 
 =====================
 Installing extensions
@@ -10,7 +10,7 @@ Both system extensions and third-party extensions are managed using Composer. Co
 the installation of the extension and also installs any dependencies that may be
 required. Composer is also used to uninstall extensions.
 
-.. _install-extension-with-composer:
+..  _install-extension-with-composer:
 
 Find the Composer package name for an extension
 -----------------------------------------------
@@ -37,53 +37,58 @@ Composer package name
     :composer:`friendsoftypo3/extension-builder`
 
 
+..  _installing-extensions-require:
+
 Use :bash:`composer require` to install the extension
 -----------------------------------------------------
 
-.. code-block:: bash
-   :caption: /var/www/site/$
+..  code-block:: bash
+    :caption: /var/www/site/$
 
-   composer require <packagename>
+    ddev composer require <packagename>
 
 To install the news extension:
 
+..  code-block:: bash
+    :caption: /var/www/site/$
 
-.. code-block:: bash
-   :caption: /var/www/site/$
-
-   composer require georgringer/news
+    ddev composer require georgringer/news
 
 This will add the extension requirement to the installations :file:`composer.json`
 and install the extension.
 
 Whilst the extension is installed and activated automatically, it still needs to be set up before it can be used:
 
+..  _installing-extensions-setup:
+
 Setup the extension
 -------------------
 
-.. code-block:: bash
-   :caption: /var/www/site/$
+..  code-block:: bash
+    :caption: /var/www/site/$
 
-   ./vendor/bin/typo3 extension:setup
+    ddev typo3 extension:setup
 
 The extension setup command takes care of executing additional installation procedures, such as database migrations and
 clearing caches if necessary. The extension setup command is not specific to a single extension but instead looks at the overall
 state and executes all necessary steps.
 
+..  _uninstalling-extensions:
+
 Uninstalling extensions
 =======================
 
 The composer command `remove` uninstalls an extension.
 
-.. code-block:: bash
-   :caption: /var/www/site/$
+..  code-block:: bash
+    :caption: /var/www/site/$
 
-   composer remove georgringer/news
+    ddev composer remove georgringer/news
 
 The updated :file:`composer.lock` file needs to be committed to the version
 control system.
 
-.. _install_local_extensions_using_composer:
+..  _install_local_extensions_using_composer:
 
 Installing local extensions
 ===========================
@@ -97,8 +102,8 @@ Once this directory exists, update the installations `composer.json` and add thi
 as a new repository:
 
 
-.. code-block:: bash
-   :caption: /var/www/site/composer.json
+..  code-block:: bash
+    :caption: /var/www/site/composer.json
 
      {
          "repositories": [
@@ -112,21 +117,22 @@ as a new repository:
 Then run `composer require` to the install the local extension `my-local-extension` with vendor `vendor`:
 
 
-.. code-block:: bash
-   :caption: /var/www/site/$
+..  code-block:: bash
+    :caption: /var/www/site/$
 
-   composer require vendor/my-local-extension:@dev
+    ddev composer require vendor/my-local-extension:@dev
 
 By executing this command, Composer locates `vendor/my-local-extension` and then symlinks
 it to `typo3conf/ext/my-local-extension` once `composer install` is executed.
 The setup from above defines that the extension is to be placed by composer into the folder `:file:packages/my-local-extension`
 if it has not been already there.
 
+..  _installing-extensions-additional:
 
 Additional information
 ======================
 
-.. _find-out-extension-key:
+..  _find-out-extension-key:
 
 Find out the extension key for an extension
 -------------------------------------------

Documentation/FirstProject/CreateSitePackage.rst

@@ -1,10 +1,11 @@
+:navigation-title: Site package
 ..  include:: /Includes.rst.txt
 
 ..  _creating-a-site-package:
 
-=======================
-Creating a site package
-=======================
+======================================================
+Site package - extend or provide a theme for your site
+======================================================
 
 The next step is to create a site package. In TYPO3, a site package is a
 structured package that organizes the layout, design, and essential

Documentation/FirstProject/Index.rst

@@ -23,6 +23,13 @@ First project setup
         ..  card-footer:: :ref:`Set up a prebuild site <introductionpackage_index>`
             :button-style: btn btn-secondary stretched-link
 
+    ..  card:: :ref:`Site package - extend or provide a theme for your site <creating-a-site-package>`
+
+        Next steps after setting up your first project.
+
+        ..  card-footer:: :ref:`Creating a site package <creating-a-site-package>`
+            :button-style: btn btn-secondary stretched-link
+
     ..  card:: :ref:`Root page <create-root-page>`
 
         Learn how to create the first page, the so called root page.
@@ -46,19 +53,12 @@ First project setup
         ..  card-footer:: :ref:`Manage settings <settings>`
             :button-style: btn btn-secondary stretched-link
 
-    ..  card:: :ref:`Creating a site package <creating-a-site-package>`
-
-        Next steps after setting up your first project.
-
-        ..  card-footer:: :ref:`Creating a site package <creating-a-site-package>`
-            :button-style: btn btn-secondary stretched-link
-
 ..  toctree::
     :hidden:
     :titlesonly:
 
     IntroductionPackage/Index
+    CreateSitePackage
     CreateRootPage
     SiteManagement/Index
     Settings
-    CreateSitePackage

Documentation/FirstProject/IntroductionPackage/Index.rst

@@ -1,6 +1,6 @@
 ..  include:: /Includes.rst.txt
 
-..  _introductionpackage_index:
+..  _introductionpackage-index:
 
 ====================
 Introduction Package
@@ -10,6 +10,13 @@ If you are using TYPO3 for the first time you may want to
 see a working example of the CMS before you start work on
 your own project.
 
+..  contents::
+
+..  _introductionpackage-about:
+
+About the Introduction Package
+==============================
+
 The Official Introduction Package :composer:`typo3/cms-introduction`
 showcases many of
 TYPO3's capabilities and gives you the ability to try them first hand.
@@ -21,6 +28,18 @@ It also features examples of the different kinds page content that you
 typically see on a website, such as paragraphs of text, images, tables
 and navigation menus.
 
+..  _installing-introduction-package-prerequisites:
+
+Prerequisites
+=============
+
+*   You should have a fresh TYPO3 installation, Composer-based and using DDEV
+    as described here: :ref:`Installing TYPO3 with DDEV <t3start:installation-ddev-tutorial>`.
+*   You should know about basic TYPO3 concepts such as
+    :ref:`Backend <t3start:backend>` and :ref:`Frontend <t3start:frontend>`.
+*   You need very basic knowledge about `DDEV <https://ddev.readthedocs.io/en/stable/>`__
+    and `Composer <https://getcomposer.org/>`__.
+
 ..  _installing-introduction-package-with-composer:
 ..  _installing-distributions-wit-composer:
 
@@ -29,65 +48,82 @@ Installing the Introduction Package
 
 To install the Introduction Package run the following command:
 
-..  tabs::
-
-    ..  group-tab:: bash
-
-        ..  code-block:: bash
-
-            composer require typo3/cms-introduction
-
-    ..  group-tab:: powershell
-
-        ..  code-block:: powershell
-
-            composer require typo3/cms-introduction
+..  code-block:: bash
 
-    ..  group-tab:: ddev
-
-        ..  code-block:: bash
-
-            ddev composer require typo3/cms-introduction
+    ddev composer require typo3/cms-introduction
 
 Then run:
 
-..  tabs::
+..  code-block:: bash
 
-    ..  group-tab:: bash
+    ddev typo3 extension:setup
 
-        ..  code-block:: bash
+This will set up the extension ready for immediate use.
 
-            vendor/bin/typo3 extension:setup
+..  _install-intro-first-steps:
 
-    ..  group-tab:: powershell
+First steps with the Introduction Package
+=========================================
 
-        ..  code-block:: powershell
+The "Introduction Package" creates a number of pre-built pages within the
+page tree. The top level page is named "Congratulations".
 
-            vendor/bin/typo3 extension:setup
+The following DDEV command tells you how to open the
+:ref:`Frontend <t3start:frontend>`:
 
-    ..  group-tab:: ddev
+..  code-block:: bash
 
-        ..  code-block:: bash
+    ddev describe
 
-            ddev typo3 extension:setup
+In section "All URLs" choose the first suggested URL and open it in a browser
+of your choice. This could be for example: `https://my-first-project.ddev.site`
 
-This will set up the extension ready for immediate use.
+..  figure:: /Images/AutomaticScreenshots/Frontend/IntroductionPackageHome.png
+    :class: with-shadow
+    :alt: Screenshot of the front page of a TYPO3 project with introduction package installed
 
-..  _install-intro-first-steps:
+    Frontend of the TYPO3 Introduction Package
 
-First steps with the Introduction Package
-=========================================
+Open the backend of the site by adding `/typo3` to this URL, for example
+`https://my-first-project.ddev.site/typo3` (This URL is configurable, if you
+followed this guide it should however not have been changed yet:
+:ref:`Backend entry point <t3coreapi:backend-entry-point>`).
+
+..  figure:: /Images/AutomaticScreenshots/Frontend/IntroductionPackageHome.png
+    :class: with-shadow
+    :alt: Screenshot of the backend of a TYPO3 project with introduction package installed
 
-The "Introduction Package" creates a number of pre-built pages within the page tree. The top level page is named "Congratulations".
+    Backend of the TYPO3 Introduction Package
 
-..  rst-class:: bignums-xxl
+You can look and click around, try to change the content of the page etc.
+The :ref:`Editors Guide <t3editors:start>` explains how to change the content
+as an editor.
 
-#.  Click on "Congratulations" in the page tree.
+..  _install-intro-next-steps:
 
+Next steps
+==========
 
-#.  View the page in the frontend:
+You can use this installation to improve your understanding of some of the
+concepts of TYPO3:
 
-    Click on the :guilabel:`"View webpage"` icon (with an eye) to view the page
-    in the frontend.
+*   Compare the directory structure that was generated and compare it with
+    chapter :ref:`TYPO3 concepts: Project structure <t3start:project-structure>`.
+*   The introduction package you just installed is a TYPO3 extension.
+    The extension key is `introduction` and the Composer name is
+    :composer:`typo3/cms-introduction` you can find its source code in
+    directory :path:`vendor/typo3/cms-introduction` and have a look a the
+    code, especially the :file:`vendor/typo3/cms-introduction/composer.json`
+    Compare it with chapter :ref:`TYPO3 concepts: Extensions <t3start:concepts-extensions>`.
+*   The introduction package depends on the third party extension
+    "Bootstrap Package" with extension key `bootstrap_package` and Composer name
+    :composer:`bk2k/bootstrap-package`. You can finde its code at
+    :path:`vendor/bk2k/bootstrap-package`. This is a very complex example of
+    what a generic site package that can be extended for specific sites looks
+    like.
+*   The introduction package only contained some data that was already loaded
+    into your TYPO3 installation if the frontend worked. It is not needed
+    anymore and can be uninstalled. See :ref:`uninstalling-extensions`.
 
-..  include:: /Images/AutomaticScreenshots/Frontend/IntroductionPackageHome.rst.txt
+Once you are ready for your first project start by
+:ref:`Creating a site package <t3start:creating-a-site-package>`.