[DOCS] Documentation overhaul

TYPO3 · Dec 7, 2024 · 6184e5d · 6184e5d
1 parent 5ecd828
commit 6184e5d
Show file tree

Hide file tree

Showing 23 changed files with 1,062 additions and 539 deletions.
diff --git a/Documentation/Development/Decisions.rst b/Documentation/Development/Decisions.rst
diff --git a/Documentation/Development/Index.rst b/Documentation/Development/Index.rst
@@ -2,15 +2,13 @@
 
 .. _development:
 
-===========
-Development
-===========
+===============
+Extending Fluid
+===============
 
-.. toctree::
-    :maxdepth: 2
+..  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/Implementation.rst b/Documentation/Development/Implementation.rst → Documentation/Integrating/Implementation.rst
diff --git a/Documentation/Integrating/Index.rst b/Documentation/Integrating/Index.rst
@@ -0,0 +1,9 @@
+.. include:: /Includes.rst.txt
+
+.. _integrating-fluid:
+
+=================
+Integrating Fluid
+=================
+
+TODO
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>