Additionally Supported Filenames and Formats


For best results, follow the guidelines in Conventions, specifically Directories and Files.

Name of Start Page

It is recommended to name the startpage Documentation/Index.rst. The following is also supported (in this order):

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

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).

Rendering Formats

Using reStructuredText (reST) is strongly recommended.


TYPO3 documentation uses reStructuredText for markup. The rendering chain and tools are built and optimized to process reST markup. Please go ahead and use that format.

The file ending of reST files is .rst.

The tool pandoc can convert existing markdown file into reST format. Do this once and you are in line with the TYPO3 conventions.


Currently, you can also use markdown for your documentation.

One problem with markdown is that there are many dialects. Since a while there is a standard “commonmark”. At people are trying to make commonmark available. See for the details. Without doing lots of investigations we have implemented the same solution for TYPO3 documentation as well.

This means that our rendering tools detect markdown files as well. They have .md as file ending.

If you’re encountering problems with the rendering of your markdown files, consider switching to reST.

Drawbacks of Other Formats and Filenames

Drawbacks of Markdown

Not everything is currently rendered correctly with the existing toolchain in Markdown.

See this open issue