--- title: "File structure" manual: "How to Document" version: "main" permalink: "https://docs.typo3.org/permalink/h2document:file-structure" source: "Reference/FileStructure.rst" rendered: "2026-09-19T10:25:29+00:00" --- # File structure {#file-structure} This page explains the general file structure of a TYPO3 documentation that can be rendered with the [rendering toolchain](https://docs.typo3.org/permalink/h2document:rendering-docs). **Table of Contents:** - [Prerequisites for rendering documentation to docs.typo3.org](https://docs.typo3.org/permalink/h2document:prerequisites-for-rendering-documentation-to-docs-typo3-org) - [Full documentation in reST](https://docs.typo3.org/permalink/h2document:full-documentation-in-rest) - [Full documentation in reST Markdown](https://docs.typo3.org/permalink/h2document:full-documentation-in-rest-markdown) - [Single file documentation (README)](https://docs.typo3.org/permalink/h2document:single-file-documentation-readme) ## Prerequisites for rendering documentation to `docs.typo3.org` {#file-structure-general} In order for the documentation to be rendered, you need at least - A valid [composer.json](https://docs.typo3.org/m/typo3/reference-coreapi/14.3/en-us/ExtensionArchitecture/FileStructure/ComposerJson.html#files-composer-json) And one of the following files: - Documentation/Index.rst ([Full documentation in reST](https://docs.typo3.org/permalink/h2document:full-documentation)) - Documentation/Index.md ([Full documentation in reST Markdown](https://docs.typo3.org/permalink/h2document:full-documentation-md)) - README.rst ([Single file documentation (README)](https://docs.typo3.org/permalink/h2document:single-file-documentation)) - README.md ([Single file documentation (README)](https://docs.typo3.org/permalink/h2document:single-file-documentation)) Further conventions are: - [Included reST files](https://docs.typo3.org/permalink/h2document:including-files) **should** have the extension `.rst.txt`. - Use **CamelCase** for directory and file names, for example: `Documentation/GeneralConventions/FileStructure.rst`. - Each directory **shall** have a file named `Index.rst` it is used as fallback if a page is not found during switching versions. - Code examples to be included should start with an underscore, for example `_Services.yaml`. > [!NOTE] > Do not place symbolic links inside the `Documentation` folder. The > rendering walks the directory tree literally; a symlink (for example an > `AGENTS.md` or `CLAUDE.md` link created by AI tooling) breaks > the file walk and thereby the rendering. ## Full documentation in reST {#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 `Documentation\Index.rst` and a configuration file called `Documentation\guides.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` {#start-file} 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: ```rst See :ref:`TYPO3 Explained `. ``` 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 {#index-rst-table-of-contents} The `toctree` on the start page can be hidden, it then only influences the main navigation: ```rst .. 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: ```rst .. 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](https://docs.typo3.org/permalink/h2document:toctree). 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** ```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/Includes.rst.txt` {#optional-file-documentation-includes-rst-txt} The `Includes.rst.txt` is optional for Extension documentation. We use it by convention in all official documentation. By default it only contains a comment: **Documentation/Includes.rst.txt** ```rst .. You can put central messages to display on all pages here ``` In the official documentation we use it to mark outdated and eLTS versions: **Documentation/Includes.rst.txt** ```rst .. You can put central messages to display on all pages here .. attention:: TYPO3 v10 has reached end-of-life as of April 30th 2023 and is no longer being maintained. [...] ``` Before [migration](https://docs.typo3.org/permalink/h2document:migrate) to the new rendering it also contained configuration settings. All those have been moved to the [guides.xml](https://docs.typo3.org/permalink/h2document:guides-xml) or have been replaced by defaults in our theme implementation. ### Optional: `Documentation/Sitemap.rst` {#sitemap-rst} The `Sitemap.rst` contains the sitemap of the documentation. It is an almost empty file that is automatically filled during rendering. ```rst :template: sitemap.html .. include:: /Includes.rst.txt ======= Sitemap ======= .. The sitemap.html template will insert here the page tree automatically. ``` ### Settings: `Documentation/guides.xml` {#settings-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](https://docs.typo3.org/permalink/h2document:guides-xml). > [!TIP] > **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](https://docs.typo3.org/permalink/h2document:migrate-guides-xml). Example: **Documentation/guides.xml** ```xml ``` ## Full documentation in reST Markdown {#full-documentation-md} The TYPO3 documentation rendering pipeline supports rendering of CommonMark Markdown plus a few additional constructs like tables. The main entry point for Markdown documentation **must** be `Documentation/Index.md`. Each folder in the `Documentation` directory **should** contain a file called `Index.md` if it contains Markdown at all. **Documentation/guides.xml** ```xml ``` Lines 6-8 are different from reST documents. - line 6: Set the input format to Markdown (md) - line 7-8: Automatically create a menu with all Markdown files and folders found. Folders must have a `Index.md` to be added. ## Single file documentation (README) {#single-file-documentation} 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/](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. 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 **Rest** **Documentation/README.rst** ```rst ========= ========= Installation ============ .. Configuration ============= .. Usage ====== .. .. csv-table:: :header: "", "URL" **Repository:**, :samp:`https://{}` **Read online:**, :samp:`https://docs.typo3.org/p/{}/main/en-us/` **TER:**, :samp:`https://extensions.typo3.org/extension/{}/` ``` **Markdown** ```md # | | URL | |------------------|---------------------------------------------------------------| | **Repository:** | https:// | | **Read online:** | https://docs.typo3.org/p//main/en-us/ | | **TER:** | https://extensions.typo3.org/extension// | ```