[FEATURE] Make templates overridable

[CybotTM]

Summary

Allow users to override Twig templates when rendering documentation locally via Docker or a custom CI pipeline. Two methods are supported:

1. Docker volume mount at /templates (highest priority)
2. Project-bundled templates at resources/custom-templates (relative to project root)

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.

Background

This is a takeover of upstream PR #1085 by @linawolf, with all review feedback addressed:

• @jaapio: Use /templates instead of /project/custom-templates to avoid Docker volume mount ordering issues when both paths are under /project
• @kaystrobach: Fix documentation to use --entrypoint=cat / --entrypoint=sh — the container entrypoint routes all commands to the PHP guides binary, so bare cat fails with "Command 'cat' is not defined"
• @kaystrobach: Implement and document the project-bundled resources/custom-templates path (was mentioned in original docs but never coded)
• Remove duplicate "Finding the Original Templates" section
• Priority bug fix: The original PR's array_reverse logic caused project-bundled templates to incorrectly override Docker volume templates. Fixed by building the array in final priority order, eliminating array_reverse

Changed files

File	Change
Dockerfile	Add mkdir -p /templates
Typo3DocsThemeExtension.php	Detect /templates and /project/resources/custom-templates, build template path array in priority order
Documentation/Templating/Index.rst	New comprehensive documentation page
Documentation/Index.rst	Add Templating to toctree

Verification

• PHPStan: no errors
• php-cs-fixer: no fixable issues
• Documentation renders successfully (15 files, no warnings)
• 3-cycle code review completed (correctness, edge cases, code quality)
• TYPO3 docs skill RST validation passed

Test plan

• Build Docker image and verify /templates directory exists
• Mount custom templates via -v ./my-templates:/templates:ro and confirm they override built-in templates
• Place templates in resources/custom-templates/ in a project and confirm auto-detection without extra volume mount
• Verify both methods can coexist, with Docker volume taking priority
• Verify rendering without any custom templates still works as before

[gemini-code-assist]

Summary of Changes

Hello @CybotTM, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request introduces a robust mechanism for users to customize the Twig templates used in local documentation rendering environments. It provides two flexible methods for injecting custom templates, either through Docker volume mounts or by bundling them directly within the project, and ensures a consistent priority order for their application. This enhancement significantly improves the adaptability of the documentation rendering process for local development and custom CI/CD pipelines, without impacting the official TYPO3 documentation build system.

Highlights

• Template Overriding Mechanism: Enabled the ability for users to override Twig templates when rendering documentation locally, supporting both Docker volume mounts and project-bundled templates.
• Template Priority: Established a clear priority order for custom templates: Docker volume mounted templates at '/templates' take highest precedence, followed by project-bundled templates at 'resources/custom-templates', and then the built-in theme templates.
• Bug Fix: Addressed and fixed a critical bug from the original upstream PR related to 'array_reverse' logic, ensuring that template priority is correctly applied.
• Comprehensive Documentation: Introduced a new, detailed documentation page explaining the template overriding process, including setup instructions, directory structure, and examples.

Changelog

• Dockerfile
  • Created the '/templates' directory within the Docker image to serve as a mount point for custom templates.
• Documentation/Index.rst
  • Included the new 'Templating/Index' documentation page in the main table of contents.
• Documentation/Templating/Index.rst
  • Added a new documentation page detailing the template overriding feature, including how it works, the two supported methods, directory structure, and examples.
• Typo3DocsThemeExtension.php
  • Implemented logic to detect the presence of '/templates' (Docker volume) and '/project/resources/custom-templates' (project-bundled) directories.
  • Adjusted the template search path to prepend detected custom template directories, ensuring they take precedence over built-in templates.
• composer.lock
  • Updated the 'friendsofphp/php-cs-fixer' dependency from 'v3.94.0' to 'v3.94.2'.

Activity

• This pull request is a takeover of an upstream PR ([FEATURE] Make templates overridable TYPO3-Documentation/render-guides#1085 by @linawolf), with all previous review feedback addressed.
• Feedback from @jaapio was incorporated, leading to the use of '/templates' for Docker volume mounts to avoid nesting issues.
• Feedback from @kaystrobach was addressed, including fixes for documentation regarding '--entrypoint=cat' / '--entrypoint=sh' and the implementation of project-bundled templates.
• A critical priority bug fix was implemented to correct 'array_reverse' logic, ensuring the proper precedence of custom templates.
• All verification steps, including PHPStan, php-cs-fixer, documentation rendering, 3-cycle code review, and TYPO3 docs skill RST validation, have been completed.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces a valuable feature allowing users to override Twig templates, which enhances customization capabilities. The implementation is clean and follows the logic described, correctly prioritizing template paths from Docker volumes and the project's resource directory. The accompanying documentation is comprehensive and clear, providing excellent examples for users.

I have a suggestion to improve the robustness of the directory checking logic in Typo3DocsThemeExtension.php. Overall, this is a solid contribution.

[Copilot]

Pull request overview

Enables end users to override TYPO3 Docs theme Twig templates when rendering docs locally (e.g., via Docker) by adding higher-priority template search paths ahead of the built-in theme templates, and documents the supported override mechanisms.

Changes:

• Add custom template discovery in the theme DI extension (Docker-mounted /templates, and project-bundled /project/resources/custom-templates) with defined precedence.
• Add a new documentation page explaining template override structure and Docker usage, and link it from the docs index.
• Update the Docker image to create /templates, and bump friendsofphp/php-cs-fixer in composer.lock.

Reviewed changes

Copilot reviewed 4 out of 5 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
packages/typo3-docs-theme/src/DependencyInjection/Typo3DocsThemeExtension.php	Prepends override template directories (if present) before built-in theme templates.
Dockerfile	Creates /templates directory inside the runtime image.
Documentation/Templating/Index.rst	Adds end-user docs for overriding templates via /templates or resources/custom-templates.
Documentation/Index.rst	Adds the new Templating page to the toctree.
composer.lock	Updates dev tooling dependency (php-cs-fixer) lock entry.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.