Skip to content

[DOCS] Overhaul generate a site package #365

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
linawolf merged 1 commit into from
Oct 31, 2025
Merged

[DOCS] Overhaul generate a site package #365

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
84 changes: 42 additions & 42 deletions Documentation/MinimalExample/Index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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::

Expand All @@ -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 <extension-installation>`.
Download and unzip the file into the
`packages/my_site_package` folder and :ref:`install it <extension-installation>`.

.. _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 <t3start:installation-ddev-tutorial>`
Expand All @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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 <t3coreapi: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
Expand All @@ -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 <t3coreapi: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
Expand All @@ -178,33 +178,33 @@ The site set as TypoScript Provider
.. versionadded:: 13.1
A site set can be used as :ref:`TypoScript provider <t3coreapi:site-sets-typoscript>`.

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 <t3start:typoscript>`
of the "Getting Started Tutorial".
in the "Getting Started Tutorial".

.. _minimal-extension-fluid:

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`.

Expand All @@ -213,24 +213,24 @@ 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:

Composer configuration :file:`composer.json`
============================================

In step :ref:`Create a minimal TYPO3 extension <t3sitepackage:minimal-extension>`
In :ref:`Create a minimal TYPO3 extension <t3sitepackage:minimal-extension>`
a file called :file:`composer.json` was created for you:

.. literalinclude:: /CodeSnippets/my_site_package/composer.json
Expand All @@ -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
Expand Down