---
title: "Overriding templates"
manual: "Render guides"
version: "0.44"
permalink: "https://docs.typo3.org/permalink/t3renderguides:override-templates"
source: "Templating/Index.rst"
rendered: "2026-09-23T14:52:35+00:00"
---

# Overriding templates {#override-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](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 {#template-override-mechanism}

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:

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

## Method 1: mount a Docker volume {#template-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**

```shell
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 {#template-project-bundled}

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

**Project layout with bundled custom templates**

```text
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**

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

## Directory structure for custom templates {#template-directory-structure}

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**

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

then your custom file must be placed at:

**Matching path in your custom templates directory**

```text
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 {#template-finding-originals}

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**

```shell
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 {#template-copying}

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**

```shell
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 {#template-examples}

### Override the page layout {#override-the-page-layout}

**Override the theme's main page layout**

```shell
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-block-quote-rendering}

**Override the core block quote template**

```shell
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
```