Start extension documentation from the example manual¶
This page is a “quick start”. If you are just getting started, you may want to look at How to document an extension and some of the resources listed there first.
This description uses the example extension manual:
Clone 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
Move or copy the entire
Documentationdirectory, so that the Documentation directory is a direct subdirectory of the extension, for example
cp -r TYPO3CMS-Example-ExtensionManual/Documentation <extension-directory>/
Add or modify additional files
- (required) Make sure composer.json is up to date.
- (required) Make sure Settings.cfg is up to date.
- (recommended) .gitignore is useful, in order to
prevent accidentally commiting the generated documentation in
Documentation-GENERATED-tempto the Git repository.
- (recommended) .editorconfig is useful, so the recommended Coding Guidelines will be used within editor or IDE. EditorConfig Plugin contains further information for PhpStorm.
# cp .gitignore (make sure you don't accidentally overwrite existing one though!) cp -n TYPO3CMS-Example-ExtensionManual/.gitignore <extension-directory>/.gitignore # cp .editorconfig (make sure you don't accidentally overwrite existing one though!) cp -n TYPO3CMS-Example-ExtensionManual/.editorconfig <extension-directory>/.editorconfig
Start editing away. Use the existing text to guide you. Look at other extension manuals (for example form) for inspiration. (You can find a link to the repository in the footer.)
Fill out composer.json
Be sure to fill out
composer.jsoncorrectly as described in composer.json.
Fill out Settings.cfg
Be sure to fill out
Settings.cfgcorrectly as described in Settings.cfg.
Before publishing changes, make sure the documentation is rendered correctly.
Look at Rendering the documentation with Docker for a quick start, how to render locally.
There is also a draft branch that allows to render a preview at docs.typo3.org.
Publish when done
If you are working on your own extension, make it publicly available
In order to trigger documentation rendering on the documentation server you have to add a webhook, see Webhook.
Think about hosting your extension repository on GitHub, Bitbucket or GitLab. That way others can report issues and assist you by creating change requests for the documentation and code!