Directories and file names

If the documentation follows these conventions, the documentation rendering toolchain automatically detects the documentation and renders it correctly on the documentation server.

For documentation to be rendered, you need at least:

Hint

For some example texts, please see Examples.

The other files listed here may not be required, but are recommended.

Further conventions:

  • reStructueredText files have ending .rst
  • Markdown files have ending .md
  • Included files have ending .rst.txt
  • Use CamelCase for directories and .rst file names (e.g. Index.rst, ExtensionArchitecture.rst).

Minimal setup (“classic”)

This is the recommended setup. It is used by the official documentation.

.
├── composer.json
└── Documentation
    ├── Index.rst
    └── Settings.cfg
    └── ...

For alternative start page (e.g. README.rst or README.md), see “start file”.

composer.json

– required

The composer.json file must be valid and contain TYPO3 CMS as requirement. In order to validate the composer.json, the following command can be used within the folder containing the file:

composer validate

The following two examples demonstrate the minimum content for different supported TYPO3 versions.

Example for TYPO3 CMS > 8.7.7:

{
    "name": "vendor/package-key",
    "type": "typo3-cms-extension",
    "description": "An example extension",
    "license": "GPL-2.0-or-later",
    "require": {
        "typo3/cms-core": "^8.7.8"
    },
    "extra": {
        "typo3/cms": {
            "extension-key": "extension_key"
        }
    }
}

For extensions supporting TYPO3 versions lower then 8.7.7, typo3/cms is required as dependency instead of typo3/cms-core:

{
    "name": "vendor/package-key",
    "type": "typo3-cms-extension",
    "description": "An example extension",
    "license": "GPL-2.0-or-later",
    "require": {
        "typo3/cms": "^7.6"
    },
    "extra": {
        "typo3/cms": {
            "extension-key": "extension_key"
        }
    }
}

The extra section can be used to provide an TYPO3 extension_key for the package. This will be used when found. If not provided, the package-key will be used, where all - get replaced by _, to follow TYPO3 and packagist conventions.

Start file

– required

The recommended start file is Documentation/Index.rst. This is what is used for official manuals.

Use Index.rst in this manual as an example.

The following is also supported (in this priority):

  1. Documentation/Index.rst
  2. Documentation/index.rst
  3. Documentation/Index.md
  4. Documentation/index.md
  5. README.rst
  6. README.md

If none of these files exist, no documentation will be rendered.

The files ending in .md contain Markdown, the files ending in .rst contain reStructuredText (reST).

For information about what texts can be on the start page, please see Start page.

Tip

Official manuals often contain both: README.rst and Documentation/Index.rst. Because Documentation/Index.rst has higher priority, this will be used as start page. The additional README.rst is used as an “about file”.

Warning

If you use a single file solution (everything in one file without toctree), there is still an open issue concerning the menu. See the workaround.

Example - “classic” with toctree

A similar structure is used by the official documentation.

Files

.
├── ...
├── composer.json
└── Documentation
    ├── Index.rst
    ├── Settings.cfg
    └── Introduction.rst
    └── Configuration.rst

Content

Index.rst:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
.. include:: /Includes.rst.txt

=====
Title
=====

some text


.. toctree::
   :hidden:

   Introduction
   Configuration
  • line 1: every .rst file should include /Includes.rst.txt
  • line 3-5: the header
  • line 10-14: the toctree defines which other pages will be included and combined. The menu is generated from all combined files (recursively). Here we include the files Introduction.rst, Configuration.rst

Introduction.rst:

.. include:: /Includes.rst.txt

============
Introduction
============

some text

A subsection
============

Alternatively, the introduction file may include a toctree as well.

Example - single file

This uses an alternative start file README.rst on the top level, instead of Documentation/Index.rst.

This may be better suited for extensions.

Files

.
├── ...
├── README.rst
└── Documentation
    ├── Settings.cfg
    └── ...

Content

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
=====
Title
=====


Introduction
============

... text with introduction ...

Configuration
=============

... text with configuration ...
  • line 1: every .rst file should include /Includes.rst.txt
  • line 3-5: the title
  • Here, all text is contained in one file.

Workaround for single file

Warning

If you use a single file solution (everything in one file), there is still an open issue concerning the menu.

Currently, there is a workaround: Remove the title:

Introduction
============

... text with introduction ...

Configuration
=============

... text with configuration ...

Settings.cfg

– required

Documentation/Settings.cfg

Important

This file must be adapted for the manual.

The file consists of sections, which start with a keyword in brackets, such as [general]. Make sure that all directives exist in the correct section.

Intersphinx mapping

Settings.cfg contains start urls for the Cross referencing (:ref:) linking mechanism.

Every manual used for cross referencing must be uncommented in the section intersphinx_mapping.

This is an up-to-date list of mappings commonly used:

[intersphinx_mapping]

# ----------------
# official manuals
# ----------------

# h2document     = https://docs.typo3.org/m/typo3/docs-how-to-document/master/en-us/
# t3contribute   = https://docs.typo3.org/m/typo3/guide-contributionworkflow/master/en-us/
# t3coreapi      = https://docs.typo3.org/m/typo3/reference-coreapi/master/en-us/
# t3docteam      = https://docs.typo3.org/m/typo3/team-t3docteam/master/en-us/
# t3editors      = https://docs.typo3.org/m/typo3/tutorial-editors/master/en-us/
# t3extbase      = https://docs.typo3.org/m/typo3/guide-extbasefluid/master/en-us/
# t3extbasebook  = https://docs.typo3.org/m/typo3/book-extbasefluid/master/en-us/
# t3install      = https://docs.typo3.org/m/typo3/guide-installation/master/en-us/
# t3l10n         = https://docs.typo3.org/m/typo3/guide-frontendlocalization/master/en-us/
# t3start        = https://docs.typo3.org/m/typo3/tutorial-getting-started/master/en-us/
# t3sitepackage  = https://docs.typo3.org/m/typo3/tutorial-sitepackage/master/en-us/
# t3tca          = https://docs.typo3.org/m/typo3/reference-tca/master/en-us/
# t3templating   = https://docs.typo3.org/m/typo3/tutorial-templating/master/en-us/
# t3ts45         = https://docs.typo3.org/m/typo3/tutorial-typoscript-in-45-minutes/master/en-us/
# t3tsconfig     = https://docs.typo3.org/m/typo3/reference-tsconfig/master/en-us/
# t3tsref        = https://docs.typo3.org/m/typo3/reference-typoscript/master/en-us/
# t3vhref        = https://docs.typo3.org/other/typo3/view-helper-reference/master/en-us/

# ----------------
# system extension
# ----------------

# ckedit         = https://docs.typo3.org/c/typo3/cms-rte-ckeditor/master/en-us/
# core           = https://docs.typo3.org/c/typo3/cms-core/master/en-us/
# form           = https://docs.typo3.org/c/typo3/cms-form/master/en-us/
# fsc            = https://docs.typo3.org/c/typo3/cms-fluid-styled-content/master/en-us/
# sched          = https://docs.typo3.org/c/typo3/cms-scheduler/master/en-us/

Tip

Uncomment only the manuals to which you will be linking to in your manual For example, change:

# t3tsref        = https://docs.typo3.org/m/typo3/reference-typoscript/master/en-us/

to:

t3tsref        = https://docs.typo3.org/m/typo3/reference-typoscript/master/en-us/

Example

This is Settings.cfg for this manual.

# Sphinx setup file for this project
#
# This document lives here:
#    https://github.com/TYPO3-Documentation/TYPO3CMS-Guide-HowToDocument/blob/master/Documentation/Settings.cfg
# See sample file:
#    https://github.com/TYPO3-Documentation/TYPO3CMS-Guide-HowToDocument/blob/master/Documentation/Settings.cfg
# Documentation:
#    https://docs.typo3.org/typo3cms/HowToDocument/GeneralConventions/DirectoryFilenames.html#settings-cfg

[general]

# .................................................................................
# ...   (required) title (displayed in left sidebar (desktop) or top panel (mobile)
# .................................................................................

project     = Writing Documentation

# .................................................................................
# ...   (recommended) version, displayed next to title (desktop) and in <meta name="book-version"
# ...   Set during rendering based on rendered version
# .................................................................................

release     = 2.0.0

# .................................................................................
# ...  (recommended) displayed in footer
# .................................................................................

copyright   = since 1999 by the TYPO3 Documentation Team

[html_theme_options]

# .................................................................................
# ...  (recommended) to get the "Edit on GitHub Button"
# .................................................................................

github_branch        = master
github_repository    = TYPO3-Documentation/TYPO3CMS-Guide-HowToDocument

# .................................................................................
# ...  (recommended) Fill in values to get links in the footer of rendered page
# .................................................................................

project_contact      = https://typo3.org/community/teams/documentation/#c9886
project_discussions  =
project_home         = https://github.com/TYPO3-Documentation/TYPO3CMS-Guide-HowToDocument
project_issues       = https://github.com/TYPO3-Documentation/TYPO3CMS-Guide-HowToDocument/issues
project_repository   = https://github.com/TYPO3-Documentation/TYPO3CMS-Guide-HowToDocument

[intersphinx_mapping]

# .................................................................................
# for cross-referencing across manuals (intersphinx) with :ref:
#
# You must uncomment all manuals you use in your cross-references
#
# Example usage:
#   :ref:`t3contribute:start` will link to start page of Contribution Guide
# .................................................................................

# ----------------
# official manuals
# ----------------

h2document     = https://docs.typo3.org/m/typo3/docs-how-to-document/master/en-us/
t3contribute   = https://docs.typo3.org/m/typo3/guide-contributionworkflow/master/en-us/
t3coreapi      = https://docs.typo3.org/m/typo3/reference-coreapi/master/en-us/
t3docteam      = https://docs.typo3.org/m/typo3/team-t3docteam/master/en-us/
# t3editors      = https://docs.typo3.org/m/typo3/tutorial-editors/master/en-us/
# t3extbase      = https://docs.typo3.org/m/typo3/guide-extbasefluid/master/en-us/
t3extbasebook  = https://docs.typo3.org/m/typo3/book-extbasefluid/master/en-us/
t3install      = https://docs.typo3.org/m/typo3/guide-installation/master/en-us/
# t3l10n         = https://docs.typo3.org/m/typo3/guide-frontendlocalization/master/en-us/
t3start        = https://docs.typo3.org/m/typo3/tutorial-getting-started/master/en-us/
t3sitepackage  = https://docs.typo3.org/m/typo3/tutorial-sitepackage/master/en-us/
t3tca          = https://docs.typo3.org/m/typo3/reference-tca/master/en-us/
# t3templating   = https://docs.typo3.org/m/typo3/tutorial-templating/master/en-us/
# t3ts45         = https://docs.typo3.org/m/typo3/tutorial-typoscript-in-45-minutes/master/en-us/
t3tsconfig     = https://docs.typo3.org/m/typo3/reference-tsconfig/master/en-us/
t3tsref        = https://docs.typo3.org/m/typo3/reference-typoscript/master/en-us/
# t3vhref        = https://docs.typo3.org/other/typo3/view-helper-reference/master/en-us/

# ----------------
# system extension
# ----------------

# ckedit         = https://docs.typo3.org/c/typo3/cms-rte-ckeditor/master/en-us/
t3core           = https://docs.typo3.org/c/typo3/cms-core/master/en-us/
# form           = https://docs.typo3.org/c/typo3/cms-form/master/en-us/
# fsc            = https://docs.typo3.org/c/typo3/cms-fluid-styled-content/master/en-us/
# sched          = https://docs.typo3.org/c/typo3/cms-scheduler/master/en-us/

[extensions]

# .................................................................................
# ; Add to list of extensions[] as defined in 'conf.py'.
# ; Mention the extensions you need. Some are loaded automatically
# ; and don't need to be mentioned.
#
# .................................................................................

# This is required for embedding YouTube videos

any_name_youtube = sphinxcontrib.youtube

[extlinks]

# .................................................................................
# ...  (optional) If you want to be able to refer to issues like this:
# ...  :issue:`number`
# .................................................................................

issue = https://github.com/TYPO3-Documentation/TYPO3CMS-Guide-HowToDocument/issues/%s | Issue #

Includes.rst.txt

– optional (recommended for official documentation)

Documentation/Includes.rst.txt

This file can be the same for all Documentation projects!

Example:

.. This is 'Includes.rst.txt'. It is included at the very top of each and
   every ReST source file in THIS documentation project (= manual).

.. This files lives at
   https://github.com/TYPO3-Documentation/TYPO3CMS-Guide-HowToDocument/blob/master/Documentation/Includes.rst.txt

.. More information about this file:
   https://docs.typo3.org/typo3cms/HowToDocument/GeneralConventions/DirectoryFilenames.html#includes-txt

.. Define some additional text roles
   See: https://docs.typo3.org/typo3cms/HowToDocument/WritingReST/InlineCode.html


.. ----------
.. text roles
.. ----------

.. role:: aspect(emphasis)
.. role:: html(code)
.. role:: js(code)
.. role:: php(code)
.. role:: pn(emphasis)
.. role:: rst(code)
.. role:: sep(strong)
.. role:: typoscript(code)

.. role:: ts(typoscript)
   :class: typoscript

.. role:: yaml(code)

.. default-role:: code

.. ---------
.. highlight
.. ---------

.. By default, code blocks are php

.. highlight:: php

.editorconfig

– optional (strongly recommended)

.editorconfig

For more information, see .editorconfig.

Example:

.gitignore

– optional (strongly recommended)

.gitignore

All files listed in .gitignore will be ignored by Git. This is useful for generated files, that should not be added to your repository or for temporary files (e.g. backup files of your editor).

You can ignore additional files by adding them to your .git/info/exclude file.

The file .gitignore will apply to anyone using the repository, .git/info/exclude is for yourself only and will not be included in the repository on GitHub when you push.

Use the file in this manual: .gitignore as a template.

Minimal example

# Git global ignore file
# for local exclude patterns please edit .git/info/exclude
# Example file see https://github.com/TYPO3-Documentation/TYPO3CMS-Guide-HowToDocument/blob/master/.gitignore

# ignore generated documentation
*GENERATED*

About file (e.g. README.rst)

optional (recommended for official TYPO3 documentation)

This file will be displayed on the Git hoster (e.g. GitHub or Gitlab) when someone browses through the repositories. Use README.rst from this project as an example! (see source).

../_images/github-readme.png

The link “Read online” will help people to jump directly to the rendered version.

Goal:

  • Provide only basic information and point people to rendered docs
  • Look good on Git hosters such as GitHub

Because of the order of the supported file formats (see Start file), if a file such as Documentation/Index.rst exists as well as README.rst and has a higher priority, the README.rst is not rendered on docs.typo3.org. The other file with higher priority is rendered on docs.typo3.org but README.rst is rendered on GitHub, because that is one of the default filenames that GitHub uses to determine what to render.

In the official TYPO3 documentation, we follow this principle:

  • README.rst usually contains 2 links:
    • to the rendered documentation
    • to the GitHub repository

Tip

Because of the flexibility of the supported file names, a README.rst may actually be the documentation start page. This is the case, if no other supported file with higher priority (such as Documentation/Index.rst) exists. Do not do this for official documentation, stick to the conventions. You are however free to do this for your extension documentation.

CONTRIBUTING.rst

– optional (recommended for official TYPO3 documentation)

This file serves the purpose of guiding people who come via GitHub towards our documentation for contributors. As a minimal solution, put a link in there to How to contribute to official documentation.

You can name it CONTRIBUTING.md or CONTRIBUTING.rst, but as we commonly use reST here, it is best to stick to CONTRIBUTING.rst.

Again, use CONTRIBUTING.rst from this manual as an example.

A link to the file will automatically be displayed by GitHub when someone enters the “Issues” area (and has not created an issue yet) or when someone creates an issue.