diff --git a/Documentation/GeneralConventions/FileStructure.rst b/Documentation/GeneralConventions/FileStructure.rst index 03bd4257..b96764d1 100644 --- a/Documentation/GeneralConventions/FileStructure.rst +++ b/Documentation/GeneralConventions/FileStructure.rst @@ -8,9 +8,7 @@ File structure ============== This page explains the general file structure of a TYPO3 documentation that can -be rendered with the :ref:`rendering toolchain `. The toolchain -itself uses a `Sphinx theme `__ -for converting reStructuredText (reST) or Markdown to HTML. +be rendered with the :ref:`rendering toolchain `. .. contents:: Table of Contents: :backlinks: top @@ -18,7 +16,6 @@ for converting reStructuredText (reST) or Markdown to HTML. :depth: 2 :local: - .. _file-structure-general: General @@ -26,31 +23,23 @@ General In order for the documentation to be rendered, you need at least -#. an index file in one of the following locations in weighted order: - - - :file:`Documentation/Index.rst` - - :file:`Documentation/index.rst` - - :file:`Documentation/Index.md` - - :file:`Documentation/index.md` - - :file:`README.rst` - - :file:`README.md` +* A valid :ref:`composer.json ` +* A documentation entry point either for a :ref:`multi-page manual ` + or for the rendering of a :ref:`single README file `. -#. and a theme configuration file under +The following rules are mandatory or your documentation will not render: - - :file:`Documentation/Settings.cfg`. +* :abbr:`reST (reStructured Text)` files MUST have the extension :file:`.rst'. +* Markdown files MUST have the extension :file:`.md'. Further conventions are: -* reST files have the extension **.rst**. -* Markdown files have the extension **.md**. -* Included reST files have the extension **.rst.txt**. -* Use **CamelCase** for directory and file names, - for example: Documentation/GeneralConventions/FileStructure.rst. - -These conventions pave the way for the *full documentation* and the -*single file documentation* style, the first being preferred for several -reasons. - +* :ref:`Included reST files ` SHOULD have the extension + :file:`.rst.txt'. +* Use **CamelCase** for directory and file names, + for example: :file:`Documentation/GeneralConventions/FileStructure.rst`. +* Each directory SHOULD have a file called :file:`Index.rst` it is used as + fallback if a page is not found during switching versions. .. index:: Full documentation .. _full-documentation: @@ -100,7 +89,6 @@ repository, the published documentation and - if available - the TYPO3 Extension Repository (TER) page to guide the reader to the next steps. This could be for example: - .. tabs:: .. group-tab:: With placeholders