Overriding templates

By default, the render-guides container uses the Twig templates shipped with the official TYPO3 Documentation theme. You can provide your own templates to customize or extend the rendering output without modifying the container image.

Important

Custom templates are only supported when you build the documentation locally (for example using Docker or DDEV) or within your own CI/CD pipeline.

When your project documentation is built and deployed automatically via the official TYPO3 documentation workflow (to https://docs.typo3.org), custom templates are not supported.

The central rendering service uses a fixed, controlled version of the official theme to ensure consistency across all published manuals.

How template overriding works

The TYPO3 Documentation theme registers a list of template search paths. When rendering, the Twig template engine resolves templates by checking these paths in order and using the first match.

When custom template directories are present, they are prepended to the search path, giving them higher priority than the built-in templates.

The resolution order is:

Custom templates mounted via Docker volume at /templates (highest priority)
Custom templates bundled in the project at resources/custom-templates (relative to the project root)
TYPO3-specific theme templates
Bootstrap 5 theme templates (fallback)
Base phpDocumentor templates (fallback)

Method 1: mount a Docker volume

Mount a local directory into the container at the path /templates.

For example, if your custom templates are stored in a folder named my-custom-templates in your current working directory:

Render with templates mounted via Docker volume

docker run --rm \
  --pull always \
  -v "$(pwd):/project" \
  -v "$(pwd)/my-custom-templates:/templates:ro" \
  -it ghcr.io/typo3-documentation/render-guides:latest \
  --progress --config=Documentation

Note

The /templates path is separate from the /project mount point. This avoids volume mount ordering issues that can occur when nesting volumes.

Method 2: bundle templates in your project

Place your custom templates in a directory named resources/custom-templates at the root of your repository:

Project layout with bundled custom templates

my-project/
|-- Documentation/
|   |-- Index.rst
|   +-- ...
|-- resources/
|   +-- custom-templates/
|       +-- structure/
|           +-- layout.html.twig
+-- ...

When you mount your project into the container with -v "$(pwd):/project", the path /project/resources/custom-templates is detected automatically. No extra volume mount is needed:

Render with project-bundled templates

docker run --rm \
  --pull always \
  -v "$(pwd):/project" \
  -it ghcr.io/typo3-documentation/render-guides:latest \
  --progress --config=Documentation

Directory structure for custom templates

Your custom templates must mirror the internal directory structure of the built-in templates you want to override.

For example, if the original file is located at:

Original template path inside the theme package

typo3-docs-theme/resources/template/structure/layout.html.twig

then your custom file must be placed at:

Matching path in your custom templates directory

my-custom-templates/structure/layout.html.twig

When both files exist, your version is used instead of the original. Any template you do not override continues to use the built-in version.

Finding the original templates

To create a customized version of a template, first copy the original from the container image.

Open a shell inside the container to browse all available templates:

Open a shell inside the container

docker run --rm -it \
  --entrypoint=sh \
  ghcr.io/typo3-documentation/render-guides:latest

Note

The --entrypoint=sh flag is required because the container's default entrypoint routes all commands to the PHP guides application. Without it, shell commands like cat or ls would be interpreted as guides subcommands.

Once inside, the templates live under /opt/guides/:

TYPO3-specific templates: In the typo3-docs-theme package, at packages/typo3-docs-theme/resources/template/
Bootstrap 5 theme templates: In the guides-theme-bootstrap package, at vendor/phpdocumentor/guides-theme-bootstrap/resources/template/
reStructuredText (reST) templates: In the guides-restructured-text package, at vendor/phpdocumentor/guides-restructured-text/resources/template/html/
Base templates (shared core): In the guides package, at vendor/phpdocumentor/guides/resources/template/html/

Copying a template from the container

To copy a specific template to your local machine, use --entrypoint=cat. The examples below set TMPL to the template's relative path so the same value can be reused for the source and target:

Copy a theme template out of the container

TMPL=structure/layout.html.twig
SRC=/opt/guides/packages/typo3-docs-theme/resources/template

mkdir -p "my-custom-templates/$(dirname "$TMPL")"

docker run --rm \
  --entrypoint=cat \
  ghcr.io/typo3-documentation/render-guides:latest \
  "$SRC/$TMPL" \
  > "my-custom-templates/$TMPL"

Edit the copied file locally. The next time you run the container with your custom templates mounted, your modified version will automatically be used.

Examples

Override the page layout

Override the theme's main page layout

TMPL=structure/layout.html.twig
SRC=/opt/guides/packages/typo3-docs-theme/resources/template

mkdir -p "my-custom-templates/$(dirname "$TMPL")"

docker run --rm \
  --entrypoint=cat \
  ghcr.io/typo3-documentation/render-guides:latest \
  "$SRC/$TMPL" \
  > "my-custom-templates/$TMPL"

# Edit my-custom-templates/structure/layout.html.twig to your liking

docker run --rm \
  -v "$(pwd):/project" \
  -v "$(pwd)/my-custom-templates:/templates:ro" \
  -it ghcr.io/typo3-documentation/render-guides:latest \
  --progress --config=Documentation

Override block quote rendering

Override the core block quote template

TMPL=body/quote.html.twig
SRC=/opt/guides/vendor/phpdocumentor/guides/resources/template/html

mkdir -p "my-custom-templates/$(dirname "$TMPL")"

docker run --rm \
  --entrypoint=cat \
  ghcr.io/typo3-documentation/render-guides:latest \
  "$SRC/$TMPL" \
  > "my-custom-templates/$TMPL"

# Edit and render as above