diff --git a/Documentation/FirstProject/Index.rst b/Documentation/FirstProject/Index.rst index 9b0a1e0c..d88d21cc 100644 --- a/Documentation/FirstProject/Index.rst +++ b/Documentation/FirstProject/Index.rst @@ -7,10 +7,11 @@ First project setup =================== -In this chapter you will: +This chapter demonstrates how to create your first small project in an empty +`TYPO3 Installation `_. -* create a new site and set up its basic structure -* create and integrate a custom site package +Instead of following this chapter you can use a +`Project template for a quick start `_. .. card-grid:: :columns: 1 @@ -19,15 +20,6 @@ In this chapter you will: :class: pb-4 :card-height: 100 - .. card:: The "Introduction Package" - - The "Introduction Package" is a great place to start if you are looking - to test drive TYPO3 and see a prebuilt site that contains - a range of example page templates and content. - - .. card-footer:: :ref:`Set up a prebuild site ` - :button-style: btn btn-secondary stretched-link - .. card:: :ref:`Root page ` Learn how to create the first page, the so called root page. @@ -62,7 +54,6 @@ In this chapter you will: :hidden: :titlesonly: - IntroductionPackage/Index CreateRootPage SiteManagement/Index Settings diff --git a/Documentation/Index.rst b/Documentation/Index.rst index 85f827e6..62f7765c 100644 --- a/Documentation/Index.rst +++ b/Documentation/Index.rst @@ -94,6 +94,7 @@ system and detailed information on how to install TYPO3. Concepts/Index Installation/Index FirstProject/Index + ProjectTemplates/Index Administration/Index Troubleshooting/Index Extensions/Index diff --git a/Documentation/ProjectTemplates/GitLabTemplate/Backend.png b/Documentation/ProjectTemplates/GitLabTemplate/Backend.png new file mode 100644 index 00000000..511eb054 Binary files /dev/null and b/Documentation/ProjectTemplates/GitLabTemplate/Backend.png differ diff --git a/Documentation/ProjectTemplates/GitLabTemplate/GitClone.png b/Documentation/ProjectTemplates/GitLabTemplate/GitClone.png new file mode 100644 index 00000000..78d167f6 Binary files /dev/null and b/Documentation/ProjectTemplates/GitLabTemplate/GitClone.png differ diff --git a/Documentation/ProjectTemplates/GitLabTemplate/Index.rst b/Documentation/ProjectTemplates/GitLabTemplate/Index.rst new file mode 100644 index 00000000..b89b32e9 --- /dev/null +++ b/Documentation/ProjectTemplates/GitLabTemplate/Index.rst @@ -0,0 +1,148 @@ +:navigation-title: GitLab template + +.. include:: /Includes.rst.txt +.. _gitlab-template: + +========================================================== +Creating a TYPO3 project from the official GitLab template +========================================================== + +.. admonition:: Prerequisites + + * Knowledge about Git + * A GitLab account or self-hosted GitLab + * Planning to do deployment + * DDEV and Git installed locally + +.. _gitlab-template-create: + +Create from template +==================== + +Go to page `GitLab - New from template `_ +or to path `/new#create_from_template` on your self-hosted GitLab. And chose +:guilabel:`TYPO3 Distribution` from the list: + +.. figure:: UseTemplate.png + :alt: The "TYPO3 Distribution" entry on the "Create from template" page on GitLab. + + Click on "Use template" + +.. _gitlab-template-create-details: + +Fill in project details +======================= + +.. figure:: ProjectDetails.png + :alt: Detail page when creating a project from a template in GitLab + + Fill in the details + +.. _gitlab-template-clone: + +Clone the project +================= + +Clone the project to your local machine. You can download the SSH link from +the :guilabel:`Code` dropdown: + +.. figure:: GitClone.png + :alt: Screenshot demonstration the location of the Code button where you can copy the Clone with SSH link + + Copy the "Clone with SSH" link + +Then clone the repository: + +.. code-block:: bash + + git clone git@gitlab.com:linawolf/getting-started-with-the-gitlab-template.git + +.. note:: + You need an `SSH key (GitLab docu) ` to + do this. + +.. _gitlab-template-setup: + +Start DDEV and setup TYPO3 +========================== + +You can start and setup the project locally in DDEV using the built-in command: + +.. code-block:: bash + + ddev typo3-init + +See also file :file:`Readme.md` in the root of your project. + + +This step automatically creates several files that should be added to git: + +.. code-block:: bash + + $ git status + On branch main + Your branch is up to date with 'origin/main'. + + Untracked files: + (use "git add ..." to include in what will be committed) + composer.lock + config/sites/ + package-lock.json + + nothing added to commit but untracked files present (use "git add" to track) + + $ git add . + + :file:`composer.lock` + This file contains the information which exact versions of PHP packages + are installed. + :file:`package-lock.json` + This file contains the information which exact versions of npm packages + are installed. + :file:`config/sites/` + Contains configuration and settings of the site that was created during + setup. + +.. _gitlab-template-login: + +Log into the TYPO3 backend +========================== + +If allowed by your system the TYPO3 backend login will be automatically opened +in a browser. Otherwise you can open a browser of your choice with the +link displayed in the console. + +A default user has been created. Username and password are displayed in your +console. + +.. figure:: Backend.png + :alt: TYPO3 Backend of a project created with the GitLab Template + +Once logged in, you can preview a page and see it rendered with a basic theme. + +.. _gitlab-template-directory: + +Directory structure of the project +================================== + +.. directory-tree:: + + * :path:`.ddev` DDEV configuration + * :path:`assets` assets for a basic theme that will be built by vite + * :path:`config` system and site configuration created during setup + * :path:`node_modules` Managed by npm and vite + * :path:`packages` + + * :path:`site-distribution` basic site package that you can adjust + + * :path:`public` webroot of the server + * :path:`var` you can find the logs and other temporary files here + * :path:`vendor` all packages are installed here + * :file:`composer.json` constraints for + * :file:`composer.lock` contains the information which exact versions + of PHP packages are installed. + * :file:`package.json` constraints for frontend libraries + * :file:`package-lock.json` contains the information which exact versions + of npm packages are installed. + * :file:`vite.config.js` predefined vite configuration + diff --git a/Documentation/ProjectTemplates/GitLabTemplate/ProjectDetails.png b/Documentation/ProjectTemplates/GitLabTemplate/ProjectDetails.png new file mode 100644 index 00000000..f003ec26 Binary files /dev/null and b/Documentation/ProjectTemplates/GitLabTemplate/ProjectDetails.png differ diff --git a/Documentation/ProjectTemplates/GitLabTemplate/UseTemplate.png b/Documentation/ProjectTemplates/GitLabTemplate/UseTemplate.png new file mode 100644 index 00000000..604f5430 Binary files /dev/null and b/Documentation/ProjectTemplates/GitLabTemplate/UseTemplate.png differ diff --git a/Documentation/ProjectTemplates/Index.rst b/Documentation/ProjectTemplates/Index.rst new file mode 100644 index 00000000..0e10146a --- /dev/null +++ b/Documentation/ProjectTemplates/Index.rst @@ -0,0 +1,34 @@ +:navigation-title: Project templates + +.. include:: /Includes.rst.txt +.. _project-templates: + +=================================== +Project templates for a quick start +=================================== + +.. toctree:: + :hidden: + :titlesonly: + + IntroductionPackage/Index + GitLabTemplate/Index + +.. card-grid:: + :columns: 1 + :columns-md: 2 + :gap: 4 + :class: pb-4 + :card-height: 100 + + .. card:: `Introduction Package `_ + + Creates a site with some predefined content based on the extension + :composer:`bk2k/bootstrap-package` for theming. + + .. card:: :ref:`Official GitLab template ` + + Creates a project based on DDEV and Composer for you with a basic site + package, vite and some example data. The project is prepared to be kept + under `Version control `_ + and for deployment with `Deployer `_. diff --git a/Documentation/FirstProject/IntroductionPackage/Index.rst b/Documentation/ProjectTemplates/IntroductionPackage/Index.rst similarity index 100% rename from Documentation/FirstProject/IntroductionPackage/Index.rst rename to Documentation/ProjectTemplates/IntroductionPackage/Index.rst