Note

This version of the guide covers the new PHP-based rendering of Documentation with the TYPO3 Documentation theme.

If the project you are looking at has a file Documentation/guides.xml it is using the new rendering.

Otherwise, consider to migrate the Documentation or head over to the legacy version of this guide: How to document, Sphinx based.

File structure¶

This page explains the general file structure of a TYPO3 documentation that can be rendered with the rendering toolchain.

Table of Contents:

General¶

In order for the documentation to be rendered, you need at least

A valid composer.json
A documentation entry point either for a multi-page manual or for the rendering of a single README file.

The following rules are mandatory or your documentation will not render:

reST files MUST have the extension :file:`.rst'.
Markdown files MUST have the extension :file:`.md'.

Further conventions are:

Included reST files SHOULD have the extension :file:`.rst.txt'.
Use CamelCase for directory and file names, for example: Documentation/GeneralConventions/FileStructure.rst.
Each directory SHOULD have a file named Index.rst it is used as fallback if a page is not found during switching versions.

Full documentation¶

To render a complete documentation manual you need a folder called Documentation with at least a reStructured Text file as entry point named DocumentationIndex.rst and a configuration file called Documentationguides.xml. Add more files as needed.

You can keep a README.md or README.rst file with basic information and a link to the published manual in the root folder of the extension. These files will be commonly displayed on GitHub and GitLab.

.
├── composer.json
├── README.rst
└── Documentation
    ├── guides.xml
    ├── Index.rst
    ├── Sitemap.rst
    └── ..

Start page: `Documentation/Index.rst`¶

The documentation start page (Documentation/Index.rst) is the entry point of the main documentation. It usually contains general information about the manual, a summary of its purpose and a table of contents that refers to further pages.

The start page should contain an anchor target .. _start: above its document title. This way you can link to a documents start page by:

See :ref:`TYPO3 Explained <t3coreapi:start>`.

If your manual has more pages then this start page it must contain a table of content directive called .. toctree::. The toctree on the start page defines which pages will be displayed in main navigation of the rendered manual.

Configure the menu - the toctree¶

The toctree on the start page can be hidden, it then only influences the main navigation:

..  toctree::
    :hidden:

    Introduction/Index
    Installation/Index
    Configuration/Index
    Usage/Index
    Contribution/Index

Or it can be inserted visibly into the start page to provide an entry point:

..  toctree::
    :maxdepth: 2
    :titlesonly:

    Introduction/Index
    Installation/Index
    Configuration/Index
    Usage/Index
    Contribution/Index

For large pages it is advisable to limit the number of menu levels that will be displayed on the startpage by setting :maxdepth:. This will not limit the level of pages displayed in the main navigation.

For more information on possible options on the toctree directive see chapter Toctrees in the reST reference.

It is possible to use more then one toctree directive on the start page. Each toctree should have a :caption: in this case.

The main navigation will then be divided into sections labeled by those captions. The menu of the manual you are currently reading is an example for that:

Documentation/Index.rst

..  toctree::
    :hidden:
    :caption: Basics

    About
    HowToGetHelp
    ...

.. toctree::
    :hidden:
    :caption: Howtos

    WritingContent/Index
    WritingDocForExtension/Index
    ...

..  toctree::
    :hidden:
    :caption: Advanced

    HowToAddTranslation/Index
    GeneralConventions/HowToUpdateDocs
    GeneralConventions/ReviewInformation

..  toctree::
    :hidden:
    :caption: Maintainers

    Maintainers/Index

Optional: `Documentation/Sitemap.rst`¶

The Sitemap.rst contains the sitemap of the documentation. It is an almost empty file that is automatically filled during rendering.

:template: sitemap.html

.. include:: /Includes.rst.txt

=======
Sitemap
=======

.. The sitemap.html template will insert here the page tree automatically.

Settings: `Documentation/guides.xml`¶

This file contains the metadata and configuration for the rendering with the TYPO3 theme.

Read more about the Configuration of the rendering - guides.xml.

Hint

If you are migrating from the legacy Sphinx-based rendering and still have a Documentation/Settings.cfg you can use an automatic migration tool to migrate the settings.cfg into a guides.xml.

Example:

<?xml version="1.0" encoding="UTF-8"?>
<guides xmlns="https://www.phpdoc.org/guides" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="https://www.phpdoc.org/guides ../vendor/phpdocumentor/guides-cli/resources/schema/guides.xsd"
        links-are-relative="true"
        default-code-language="php"
>
    <extension class="\T3Docs\Typo3DocsTheme\DependencyInjection\Typo3DocsThemeExtension"
               project-home="https://extensions.typo3.org/extension/news/"
               project-contact="https://typo3.slack.com/archives/C03TG7QJT"
               project-repository="https://github.com/georgringer/news"
               project-issues="https://github.com/georgringer/news/issues"
               edit-on-github-branch="main"
               edit-on-github="georgringer/news"
               typo3-core-preferred="11.5"
               interlink-shortcode="georgringer/news"
    />
    <project title="News system" release="main (development)" version="main (development)"
             copyright="since 2010 by Georg Ringer &amp; Contributors"/>
    <inventory id="t3extbasebook" url="https://docs.typo3.org/m/typo3/book-extbasefluid/10.4/en-us/"/>
</guides>

Single file documentation (README)¶

For third-party TYPO3 extensions that do not require extended documentation you can also publish a README.rst or README.md to https://docs.typo3.org/

For this workflow the README(.rst/.md) MUST be situated in the extension's root folder. The :file:`Documentation/' folder can then be omitted.

`README.rst`¶

For single file documentation, the README.rst contains the entire documentation.

This should also contain links to all aspects of the project to guide the reader to the next steps, for example

Documentation/README.rst

<badges>

=========
<project>
=========

<abstract>

Installation
============
..

Configuration
=============
..

Usage
======
..

..  csv-table::
    :header: "", "URL"

    **Repository:**,        :samp:`https://{<vcs-repository>}`
    **Read online:**,       :samp:`https://docs.typo3.org/p/{<package-name>}/main/en-us/`
    **TER:**,               :samp:`https://extensions.typo3.org/extension/{<extension-key>}/`

<badges>

# <project>

<abstract>

|                  | URL                                                           |
|------------------|---------------------------------------------------------------|
| **Repository:**  | https://<vcs-repository>                                      |
| **Read online:** | https://docs.typo3.org/p/<package-name>/main/en-us/           |
| **TER:**         | https://extensions.typo3.org/extension/<extension-key>/       |