Skip to content

[FEATURE] Make templates overridable#1085

Open
linawolf wants to merge 1 commit intomainfrom
feature/templates
Open

[FEATURE] Make templates overridable#1085
linawolf wants to merge 1 commit intomainfrom
feature/templates

Conversation

@linawolf
Copy link
Copy Markdown
Member

When using the docker container locally
or in a custom pipeline.

When using the docker container locally
or in a custom pipeline.
ENV TYPO3AZUREEDGEURIVERSION=$TYPO3AZUREEDGEURIVERSION

WORKDIR /project
RUN mkdir -p /project/custom-templates
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
RUN mkdir -p /project/custom-templates
RUN mkdir -p /templates

docker run --rm \
--pull always \
-v "$(pwd):/project" \
-v "$(pwd)/my-custom-templates:/project/custom-templates:ro" \
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would recommend to use a separate root path for the templates. Like /templates this prevents strange behavior in the order of volumes. In the order you wrote it it will work. Otherway around it does not. People might be unaware of that.


.. code-block:: shell

docker run --rm -it ghcr.io/typo3-documentation/render-guides:latest \
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I get the error, that cat is not defined in the container:

docker run --rm -it typo3-docs:local \                                                                                                                              
      cat /opt/guides/packages/typo3-docs-theme/resources/template/structure/layout.html.twig \
      > Documentation-TwigTemplates/structure/layout.html.twig

Result of the command

�[37;41m                                 �[39;49m
�[37;41m  Command "cat" is not defined.  �[39;49m
�[37;41m                                 �[39;49m


.. tip::

You can also use a project-bundled directory named
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What exactly does that mean:

  • git-root/Documentation/resources/custom-templates/
  • git-root/resources/custom-templates/

If it's the later, it would clutter the repository. If the first, atleast i tried and did not get it to work as expected.

with neither of the commands

docker run --rm   -v "${PWD}:/project"   -v "${PWD}/Documentation-TwigTemplates/:/project/custom-templates:ro"   -it typo3-docs:local   --progress --config=Documentation
docker run --rm   -v "${PWD}:/project"   -it typo3-docs:local   --progress --config=Documentation

CybotTM added a commit to CybotTM/render-guides that referenced this pull request Feb 25, 2026
Allow users to override Twig templates when rendering documentation
locally via Docker or a custom CI pipeline. Two methods are supported:

1. Mount a Docker volume at /templates (highest priority)
2. Bundle templates in the project at resources/custom-templates

The theme extension detects these directories and prepends them to
the template search path, so custom templates take precedence over
the built-in theme templates.

Based on the work by linawolf in PR TYPO3-Documentation#1085, with all review feedback
addressed:
- Use /templates instead of /project/custom-templates to avoid
  volume mount ordering issues (jaapio)
- Fix documentation to use --entrypoint=cat/sh to bypass the
  container entrypoint (kaystrobach)
- Implement and document the project-bundled templates path
  (kaystrobach)
- Remove duplicate documentation section

Signed-off-by: Sebastian Mendel <info@sebastianmendel.de>
CybotTM added a commit to CybotTM/render-guides that referenced this pull request Mar 9, 2026
Allow users to override Twig templates when rendering documentation
locally via Docker or a custom CI pipeline. Two methods are supported:

1. Mount a Docker volume at /templates (highest priority)
2. Bundle templates in the project at resources/custom-templates

The theme extension detects these directories and prepends them to
the template search path, so custom templates take precedence over
the built-in theme templates.

Based on the work by linawolf in PR TYPO3-Documentation#1085, with all review feedback
addressed:
- Use /templates instead of /project/custom-templates to avoid
  volume mount ordering issues (jaapio)
- Fix documentation to use --entrypoint=cat/sh to bypass the
  container entrypoint (kaystrobach)
- Implement and document the project-bundled templates path
  (kaystrobach)
- Remove duplicate documentation section

Signed-off-by: Sebastian Mendel <info@sebastianmendel.de>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants