Render documentation with the TYPO3 theme

Rendering the Documentation folder locally with Docker

You can render the documentation of an official TYPO3 manual or a third-party manual with the following steps:

  1. Clone the repository containing the documentation.
  2. Navigate to the extension's root folder, the directory which contains the composer.json.

  3. Check if there is documentation to be rendered:

    A folder called Documentation containing at least the files Index.rst and guides.xml.

  4. Choose your preferred method of rendering (See below):

Make sure that Docker is installed on your system.

mkdir -p Documentation-GENERATED-temp
docker run --rm --pull always -v $(pwd):/project -it ghcr.io/typo3-documentation/render-guides:latest --config=Documentation
xdg-open "Documentation-GENERATED-temp/Index.html"
Copied! 
mkdir -p Documentation-GENERATED-temp
docker run --rm --pull always -v $(pwd):/project -it ghcr.io/typo3-documentation/render-guides:latest --config=Documentation
open "Documentation-GENERATED-temp/Index.html"
Copied! 
New-Item -ItemType Directory -Force -Path ".\Documentation-GENERATED-temp"
docker run --rm --pull always -v ${PWD}:/project -it ghcr.io/typo3-documentation/render-guides:latest --config=Documentation
start "Documentation-GENERATED-temp/Index.html"
Copied!

Rendering with more WYSIWYG-feeling (automatic re-rendering)

You want to write complex reST markup and directly see the rendered output, browser side-by-side with your editor? Then this section is for you!

Often, especially in the later stages of creating documentation, you just edit small parts of the reST files, render the outcome manually and happily commit your changes.

However, in cases you write larger sections of text, you may want to get more immediate visual feedback on your changes, but do not want to manually trigger the rendering time and again.

To make this easier, the project garvinhicking/typo3-documentation-browsersync has been created. This docker container solution provides an environment which permanently watches changes to any of the reST files and automatically triggers a re-rendering. The generated HTML output is then served with a local web server (vite-based) in which your browser automatically hot-reloads all changes and keeps the scroll position.

This allows you to have a browser window next to your reST file editor to view progress.

Since that whole environment is based on the official TYPO3 documentation rendering container and utilizes a docker container, it is simple to use. Also, all updates to the render-guides project are automatically merged into that project, so all bugfixes and new features of the PHP-based rendering always are in sync with this WYSIWYG-project, with a possibility of this becoming a regular TYPO3-documentation project (given positive feedback).

The project itself has documentation on the technical details but all you need is this docker/podman command:

docker run --rm -it --pull always \
  -v "./Documentation:/project/Documentation" \
  -v "./Documentation-GENERATED-temp:/project/Documentation-GENERATED-temp" \
  -p 5173:5173 ghcr.io/garvinhicking/typo3-documentation-browsersync:latest
xdg-open "http://localhost:5173/Documentation-GENERATED-temp/Index.html"
Copied! 
docker run --rm -it --pull always \
  -v "./Documentation:/project/Documentation" \
  -v "./Documentation-GENERATED-temp:/project/Documentation-GENERATED-temp" \
  -p 5173:5173 ghcr.io/garvinhicking/typo3-documentation-browsersync:latest
open "http://localhost:5173/Documentation-GENERATED-temp/Index.html"
Copied! 
docker run --rm -it --pull always \
  -v "./Documentation:/project/Documentation" \
  -v "./Documentation-GENERATED-temp:/project/Documentation-GENERATED-temp" \
  -p 5173:5173 ghcr.io/garvinhicking/typo3-documentation-browsersync:latest
start "http://localhost:5173/Documentation-GENERATED-temp/Index.html"
Copied!

The command above can also be added to your project's Makefile or you can create a bash alias like:

alias render-wysiwyg="docker run --rm -it --pull always \
                        -v './Documentation:/project/Documentation' \
                        -v './Documentation-GENERATED-temp:/project/Documentation-GENERATED-temp' \
                        -p 5173:5173 ghcr.io/garvinhicking/typo3-documentation-browsersync:latest'"
Copied!

Publishing extension documentation to docs.typo3.org

For your documentation to be published to https://docs.typo3.org, your TYPO3 extension has to have a valid composer.json and either a folder called Documentation with a Documentation/Index.rst and a Documentation/guides.xml or a README.rst / README.md in the extension's root directory.

The extension has to be publicly available on GitHub or GitLab. You have to establish a Webhook and the Documentation Team has to approve your first rendering.

Introduce automatic testing for extension documentation

It is recommended to make sure your documentation always renders without warning. On GitHub or GitLab you can introduce actions that test your documentation automatically:

.github/workflows/documentation.yml 
name: test documentation

on: [ push, pull_request ]

jobs:
  tests:
    name: documentation
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Test if the documentation will render without warnings
        run: |
          mkdir -p Documentation-GENERATED-temp \
          && docker run --rm --pull always -v $(pwd):/project \
             ghcr.io/typo3-documentation/render-guides:latest --config=Documentation --no-progress --minimal-test
Copied!
.gitlab-ci.yml 
stages:
  - test

test_documentation:
  stage: test
  image:
    name: ghcr.io/typo3-documentation/render-guides:latest
    entrypoint: [""]
  script:
    - mkdir -p Documentation-GENERATED-temp
    - /opt/guides/entrypoint.sh --config=Documentation --no-progress --minimal-test
Copied!