How to document an extension

Rendering the documentation locally

Docker is required to run the rendering toolchain locally. By rendering the documentation this way, proofreading and checking for typos and testing links can be carried out before the documentation is committed. The Render documentation with the TYPO3 theme has more information on how this toolchain is set up and configured.

Using the documentation-draft branch to preview changes

Alternatively, a documentation-draft branch can be created in the documentation repository. Once committed, this will render the documentation and make it available publicly, but it will only be visible when the "draft" drop-down is selected when viewing the rendered documentation. Documentation under the draft branch will not be indexed by search engines. Visit the Supported branches section for more information.

Creating extension documentation using the sample manual

1. Clone the sample extension manual

   In a temporary directory, clone the GitHub project sample extension manual

   git clone https://github.com/TYPO3-Documentation/TYPO3CMS-Example-ExtensionManual.git

   Copied!

   Copy the entire Documentation directory, so that it is a subdirectory located within your extension, for example:

   cp -r TYPO3CMS-Example-ExtensionManual/Documentation <my-extension-directory>/

   Copied!

2. Add or modify additional files

   • Make sure composer.json is up to date. (required)
   • Make sure Settings: Documentation/guides.xml is up to date. (required)
   • A .gitignore is useful, in order to prevent accidentally committing the generated documentation in Documentation-GENERATED-temp to the Git repository. (recommended)
   • An .editorconfig is useful, so the recommended Coding Guidelines will be used within an editor or IDE.

   # cp .gitignore (make sure you don't accidentally overwrite existing one though!)
   cp -n TYPO3CMS-Example-ExtensionManual/.gitignore <my-extension-directory>/.gitignore
   # cp .editorconfig (make sure you don't accidentally overwrite existing one though!)
   cp -n TYPO3CMS-Example-ExtensionManual/.editorconfig <my-extension-directory>/.editorconfig

   Copied!

   If you plan to host your extension on a public repository, consider adding a CONTRIBUTING.rst and README.rst to help guide any future contributors.

3. Start adding documentation

   Now it's time to start adding content. Reviewing existing guides can help you structure your own documentation. The news extension is a strong example of how extension documentation should be written and structured.

4. Populate composer.json

   Complete the composer.json as described in composer.json.

5. Populate guides.xml

   Complete the guides.xml as described in Settings: Documentation/guides.xml.

6. Render documentation

   Before publishing changes, make sure the documentation is rendered correctly, either by rendering it locally or by using the draft branch to preview the changes.

7. Publish when ready

   The documentation needs to be made publicly available.

   In order to trigger the documentation rendering process, a webhook needs to be added.