diff --git a/Documentation/MinimalExample/Index.rst b/Documentation/MinimalExample/Index.rst index 564310e4..2c85d98e 100644 --- a/Documentation/MinimalExample/Index.rst +++ b/Documentation/MinimalExample/Index.rst @@ -8,10 +8,11 @@ Generate a site package ======================= -A site package is a custom TYPO3 extension which contains configuration, -templates, assets, etc that are used for the site it belongs to. +A site package is a TYPO3 extension that you can customize to contain the configuration, +templates, assets, etc, for your site. It therefore acts as a kind of main "theme" for +your site. -So first we generate a minimal extension. +So we start by generating a basic extension. .. contents:: @@ -21,31 +22,31 @@ So first we generate a minimal extension. Generate and download a site package ==================================== -You can download a site package by using the official Site Package Builder at +You can download a site package using the official Site Package Builder at https://get.typo3.org/sitepackage or by using curl. -You have the choice of three site packages types: +You can choose between three site packages types: -* Bootstrap Package: This site package comes with a ready to use theme +* Bootstrap Package: This site package comes with a ready-to-use theme * Fluid Styled Content: A minimal site package where you can build your own custom theme. -* Site Package Tutorial: Contains all files that are used as examples in +* Site Package Tutorial: Contains all the files that are used as examples in this tutorial. -To follow this tutorial, chose "Site Package Tutorial" as type of the site package. +To follow this tutorial, choose the "Site Package Tutorial". -Download and unzip the zip file, place the result in folder -`packages/my_site_package`, and :ref:`install it `. +Download and unzip the file into the +`packages/my_site_package` folder and :ref:`install it `. .. _extension-installation: Extension installation ====================== -This tutorial assumes that your TYPO3 instance is a brand new installation, +This tutorial assumes that your TYPO3 instance is a brand new installation without any themes, templates, pages or content. -We assume that you are working on your local machine using DDEV and that you +We assume that you are working on your local machine using DDEV and that you have followed these steps: :ref:`Installing TYPO3 with DDEV ` @@ -55,13 +56,13 @@ followed these steps: Install the site package you just created ----------------------------------------- -If you used the Site Package Builder, file :file:`packages/my_site_package/README.md` +If you have used the Site Package Builder, the :file:`packages/my_site_package/README.md` file contains instructions on how to install your site package. -Move / unzip your extension folder :path:`my_site_package/` into the :path:`packages/` +Move / unzip your :path:`my_site_package/` extension folder into the :path:`packages/` folder. Then *require* the extension via Composer using the -package name defined in the site package extension's :file:`composer.json` now located -at :file:`packages/my_site_package/` +package name defined in the site package extension's :file:`composer.json` (now located +at :file:`packages/my_site_package/`) .. code-block:: json :caption: packages/my-site-package/composer.json @@ -70,7 +71,7 @@ at :file:`packages/my_site_package/` "name": "my-vendor/my-site-package" } -require it by: +*require* it with: .. code-block:: bash :caption: Execute in directory page_root @@ -130,16 +131,16 @@ Your project should now have the following structure: .. _minimal-extension-siteset: -Look at the a basic site set +A look at the basic site set ============================ .. versionadded:: 13.1 :ref:`Site sets ` have been introduced. -The site package build by Site Package Builder comes with a ready to use +The site package built by Site Package Builder comes with a ready-to-use site set in folder :path:`packages/my_site_package/Configuration/Sets/SitePackage/`. -The set itself is defined within this folder in the file :file:`config.yaml`: +The set itself is defined in the :file:`config.yaml` file inside this folder: .. literalinclude:: /CodeSnippets/my_site_package/Configuration/Sets/SitePackage/config.yaml :caption: packages/my-site-package/Configuration/Sets/SitePackage/config.yaml @@ -148,23 +149,22 @@ The set itself is defined within this folder in the file :file:`config.yaml`: You will learn more about site sets in chapter :ref:`site_set`. -You can find the complete reference in TYPO3 explained: +The TYPO3 Explained complete reference is here: :ref:`Site sets `. During installation of your site package a page tree with example content was -created, and should already have a site configuration in folder -:path:`config/sites/main`. +created. The site configuration folder is :path:`config/sites/main`. -When you look at the site configuration in module :guilabel:`Site Management > Sites` -it should already contain the set "My Site package". Other sets, for example -if you want to use :composer:`typo3/cms-form` can be added here. +If you look at the site configuration in module :guilabel:`Site Management > Sites` +it should already contain the "My Site package" set. Other sets can be added here, +for example :composer:`typo3/cms-form`. .. figure:: AddSiteSet.png :alt: Screenshot demonstrating adding the "My Site package" to the site main Use module :guilabel:`Site Management > Sites` to add the "Example: My Site package" -If you made no changes, the site configuration should look like this: +If you haven't made any changes, the site configuration should look like this: .. literalinclude:: /CodeSnippets/my_site_package/Initialisation/Site/main/config.yaml :caption: config/sites/main/config.yaml @@ -178,17 +178,17 @@ The site set as TypoScript Provider .. versionadded:: 13.1 A site set can be used as :ref:`TypoScript provider `. -TYPO3 uses TypoScript as configuration language. The TypoScript is used to -configure the templates, which are created with the templating language Fluid. +TYPO3 uses TypoScript as a configuration language. TypoScript is used to +configure templates created with the Fluid templating language. A file called :path:`packages/my_site_package/Configuration/Sets/SitePackage/setup.typoscript` -provides the TypoScript to your site. This file contains imports of files from +provides the TypoScript for your site. This file contains imports of files from folder :path:`packages/my_site_package/Configuration/Sets/SitePackage/TypoScript` -which contain the actual configuration. +(which contain the actual configuration). -You can learn more about the TypoScript syntax used here in chapter +Learn more about the TypoScript syntax used here in chapter :ref:`A minimal page created by pure TypoScript ` -of the "Getting Started Tutorial". +in the "Getting Started Tutorial". .. _minimal-extension-fluid: @@ -196,15 +196,15 @@ The TYPO3 Fluid version ======================= File :path:`packages/my_site_package/Configuration/Sets/SitePackage/TypoScript/page.typoscript` -Defines how the output of all pages of the site is rendered with Fluid templates: +below defines the rendering of the site with Fluid templates: .. literalinclude:: /CodeSnippets/my_site_package/Configuration/Sets/SitePackage/TypoScript/page.typoscript :caption: packages/my_site_package/Configuration/Sets/SitePackage/TypoScript/page.typoscript :emphasize-lines: 6 :linenos: -Line 6 defines from what directory the Fluid Templates are loaded. Line 7 allows -to override this part via settings. +Line 6 sets the directory the Fluid Templates are loaded from. Line 7 sets a value +from the site package settings. Learn more about using Fluid Templates in chapter :ref:`fluid-templates`. @@ -213,16 +213,16 @@ Learn more about using Fluid Templates in chapter :ref:`fluid-templates`. Preview page ============ -Whenever we have made changes to the Fluid templates or TypoScript files, it is -necessary to :guilabel:`Flush frontend caches` in the menu in the -top bar before you can preview the page properly: +Whenever you make changes to Fluid templates or TypoScript files, +you need to :guilabel:`Flush frontend caches` in the menu in the +top bar before previewing the page: .. figure:: /Images/AutomaticScreenshots/FlushFrontendCaches.png :class: with-shadow Flush the frontend cache after changing template files -You can then preview your page by clicking on the button :guilabel:`View webpage` +You can then preview your page by clicking on the :guilabel:`View webpage` button in the page module. .. _extension-configuration-composer: @@ -230,7 +230,7 @@ in the page module. Composer configuration :file:`composer.json` ============================================ -In step :ref:`Create a minimal TYPO3 extension ` +In :ref:`Create a minimal TYPO3 extension ` a file called :file:`composer.json` was created for you: .. literalinclude:: /CodeSnippets/my_site_package/composer.json @@ -243,7 +243,7 @@ extension key in the extra section - :file:`my_site_package` (with an underscore The Composer "name" consists of a vendor name followed by a forward slash and the lowercase extension name with dashes. -When you reference files in your extension, the extension key is used, for +When you reference files in your extension use your extension key, for example when setting your favicon in TypoScript: .. code-block:: typoscript