[DOCS] Documentation overhaul

TYPO3 · Dec 7, 2024 · 82c5e5f · 82c5e5f
1 parent 5ecd828
commit 82c5e5f
Show file tree

Hide file tree

Showing 24 changed files with 1,116 additions and 543 deletions.
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
@@ -48,5 +48,6 @@ jobs:
 
       - name: Documentation integrity
         run: |
-          FLUID_DOCUMENTATION_OUTPUT_DIR=Documentation/ViewHelpers vendor/bin/fluidDocumentation generate vendor/t3docs/fluid-documentation-generator/config/fluidStandalone/*
+          FLUID_DOCUMENTATION_OUTPUT_DIR=DocumentationTemp vendor/bin/fluidDocumentation generate vendor/t3docs/fluid-documentation-generator/config/fluidStandalone/*
+          cp -r DocumentationTemp/Fluid DocumentationTemp/Fluid.json Documentation/ViewHelpers/ && rm -r DocumentationTemp
           git add Documentation/*; git status; git status | grep -q "nothing to commit, working tree clean"
diff --git a/Documentation/Development/Decisions.rst b/Documentation/Development/Decisions.rst
diff --git a/Documentation/Development/Expressions.rst b/Documentation/Development/Expressions.rst
@@ -8,7 +8,7 @@ Creating ExpressionNodes
 
 To understand what an ExpressionNode is and which cases can be solved by
 implementing custom ones, first read the
-:doc:`chapter about implementing Fluid </Development/Implementation>`. Once you
+:ref:`chapter about integrating Fluid <implementations>`. Once you
 grasp what an ExpressionNode is and how it works, a very brief example is all
 you need.
 

diff --git a/Documentation/Development/Index.rst b/Documentation/Development/Index.rst
@@ -2,15 +2,34 @@
 
 .. _development:
 
-===========
-Development
-===========
+===============
+Extending Fluid
+===============
 
-.. toctree::
-    :maxdepth: 2
+..  card-grid::
+    :columns: 1
+    :columns-md: 2
+    :gap: 4
+    :class: pb-4
+    :card-height: 100
+
+    ..  card:: ViewHelpers
+
+        Learn how to extend Fluid by creating custom ViewHelpers
+
+        ..  card-footer:: :ref:`Learn about ViewHelpers <creating-viewhelpers>`
+            :button-style: btn btn-secondary stretched-link
+
+    ..  card:: ExpressionNodes
+
+        Learn how to extend Fluid by creating custom expression syntax
+
+        ..  card-footer:: :ref:`Learn about ExpressionNodes <creating-expressionnodes>`
+            :button-style: btn btn-secondary stretched-link
+
+..  toctree::
+    :hidden:
     :titlesonly:
 
-    Implementation
     CreatingViewHelpers
     Expressions
-    Decisions
diff --git a/Documentation/Index.rst b/Documentation/Index.rst
@@ -14,8 +14,7 @@ Fluid Rendering Engine
     en
 
 :Author:
-    Claus Due, Sebastian Kurfürst, Karsten Dambekalns, Robert Lemke & Fluid
-    contributors
+    Fluid contributors
 
 :License:
     This document is published under the
@@ -38,15 +37,33 @@ If using Fluid in combination with TYPO3 CMS, a look at the documentation of
 
 **Table of Contents:**
 
-.. toctree::
-   :maxdepth: 2
-   :titlesonly:
-
-   Installation/Index
-   Usage/Index
-   Development/Index
-   ViewHelpers/Index
-   Changelog/Index
+..  toctree::
+    :caption: About Fluid
+    :maxdepth: 1
+    :titlesonly:
+
+    Introduction/Index
+    Installation/Index
+    Usage/Index
+    Syntax/Index
+
+..  toctree::
+    :caption: ViewHelper Reference
+    :maxdepth: 1
+    :titlesonly:
+
+    ViewHelpers/Fluid/Index
+    ViewHelpers/SchemaFiles
+
+..  toctree::
+    :caption: Appendix
+    :maxdepth: 1
+    :titlesonly:
+
+    Development/Index
+    Integrating/Index
+    Internals/Index
+    Changelog/Index
 
 .. Meta Menu
 

diff --git a/Documentation/Installation/Index.rst b/Documentation/Installation/Index.rst
@@ -6,18 +6,13 @@
 Installation
 ============
 
-1.  Include as composer dependency using
+Fluid is distributed through composer. It can be added to your project by
+executing the following command:
 
-    .. code-block:: bash
+..  code-block:: bash
 
-        composer require typo3fluid/fluid
+    composer require typo3fluid/fluid
 
-2.  Run
-
-    .. code-block:: bash
-
-        composer install
-
-    to generate the vendor class autoloader.
-
-3.  The classes from `TYPO3.Fluid` can now be used in your composer project.
+To get started with Fluid, take a look at the
+:ref:`Fluid Syntax <fluid-syntax>` as well as the
+:ref:`Getting Started Guide <getting-started>`.
diff --git a/Documentation/Development/Implementation.rst → Documentation/Integrating/Index.rst b/Documentation/Development/Implementation.rst → Documentation/Integrating/Index.rst
@@ -2,9 +2,9 @@
 
 .. _implementations:
 
-==================
-Implementing Fluid
-==================
+=================
+Integrating Fluid
+=================
 
 `TYPO3.Fluid` provides a standard implementation which works great on simple MVC
 frameworks and as standalone rendering engine. However, the standard

diff --git a/Documentation/Internals/Index.rst b/Documentation/Internals/Index.rst
@@ -0,0 +1,13 @@
+.. include:: /Includes.rst.txt
+
+.. _fluid-internals:
+
+===============
+Fluid Internals
+===============
+
+.. toctree::
+    :maxdepth: 2
+    :titlesonly:
+
+    *
diff --git a/Documentation/Usage/RunningExamples.rst → Documentation/Internals/RunningExamples.rst b/Documentation/Usage/RunningExamples.rst → Documentation/Internals/RunningExamples.rst
diff --git a/Documentation/Introduction/Index.rst b/Documentation/Introduction/Index.rst
@@ -0,0 +1,25 @@
+.. include:: /Includes.rst.txt
+
+.. _introduction:
+
+============
+Introduction
+============
+
+Fluid is a PHP-based templating engine for web projects. In contrast to other
+templating engines, it uses an XML-based syntax in its templates, which allows
+template authors to apply their existing HTML knowledge in Fluid templates.
+
+Fluid originated in the TYPO3 and Neos ecosystem before it was extracted
+from these projects into a separate PHP package. While its main usage nowadays
+is within TYPO3 projects, it can also be used as an independent templating
+language in PHP projects.
+
+In Fluid, all dynamic output is escaped by default, which makes the templating
+engine secure by default. This prevents common XSS (Cross Site Scripting)
+mistakes that can easily happen in HTML templates.
+
+Fluid comes with a range of so-called ViewHelpers that allow various formatting
+and output modification directly in the template. Custom logic can be added
+by providing custom ViewHelper implementations through a straightforward
+PHP API.
diff --git a/Documentation/Syntax/Comments.rst b/Documentation/Syntax/Comments.rst
@@ -0,0 +1,33 @@
+.. include:: /Includes.rst.txt
+
+:navigation-title: Comments
+
+.. _fluid-syntax-comments:
+
+======================
+Fluid Syntax: Comments
+======================
+
+If you want to completely skip parts of your template, you can make use of
+the :ref:` <f:comment> ViewHelper <typo3fluid-fluid-comment>`.
+
+..  versionchanged:: Fluid 4.0
+    The content of the :ref:` <f:comment> ViewHelper <typo3fluid-fluid-comment>` is removed
+    before parsing. It is no longer necessary to combine it with CDATA tags
+    to disable parsing.
+
+..  code-block:: xml
+
+    <f:comment>
+        This will be ignored by the Fluid parser and will not appear in
+        the source code of the rendered template
+    </f:comment>
+
+You can also use the :ref:` <f:comment> ViewHelper <typo3fluid-fluid-comment>` to temporarily comment
+out invalid Fluid syntax while debugging:
+
+..  code-block:: xml
+
+    <f:comment>
+        <x:someBrokenFluid>
+    </f:comment>