Skip to content

[FEATURE] Make templates overridable#1190

Open
CybotTM wants to merge 2 commits intoTYPO3-Documentation:mainfrom
CybotTM:feature/overridable-templates
Open

[FEATURE] Make templates overridable#1190
CybotTM wants to merge 2 commits intoTYPO3-Documentation:mainfrom
CybotTM:feature/overridable-templates

Conversation

@CybotTM
Copy link
Copy Markdown
Contributor

@CybotTM CybotTM commented Feb 25, 2026

Allow users to override Twig templates when rendering documentation
locally via Docker or a custom CI pipeline, without modifying the
container image.

Two methods are supported:

  1. Docker volume mount at /templates (highest priority)
  2. Project-bundled templates at resources/custom-templates
    (relative to the 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.

Based on

This continues the work from #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
    nested 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 not implemented)
  • Remove duplicate "Finding the Original Templates" section
  • Fix priority ordering: Docker volume templates now correctly take
    precedence over project-bundled templates

Changed files

File Change
Dockerfile No changes needed (Docker creates mount targets automatically)
Typo3DocsThemeExtension.php Detect /templates and /project/resources/custom-templates with is_dir() + is_readable() guards, build template path array in priority order
Documentation/Templating/Index.rst New documentation page covering both override methods, directory structure, and examples
Documentation/Index.rst Add Templating to toctree

@linawolf
Copy link
Copy Markdown
Member

linawolf commented Mar 1, 2026

@kaystrobach would this solution work for you?

@kaystrobach
Copy link
Copy Markdown

kaystrobach commented Mar 1, 2026

Good from reading. Only question left is how to add own logos / css etc.

we can do this after rendering with cp but this feels „hacky“ using the resources folder feels more natural for that. That would be the only missing point from my POV.

removing leftovers files is more a task for external cleanup (should not be done in the container)

CybotTM added 2 commits March 9, 2026 01:25
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>
- Remove mkdir -p /templates from Dockerfile: Docker creates mount
  targets automatically when bind mounts are used, so the directory
  only exists when someone intentionally mounts templates. This avoids
  unnecessary filesystem lookups on every template resolution.
- Add is_readable() checks alongside is_dir() for defensive robustness
  against permission issues.

Signed-off-by: Sebastian Mendel <info@sebastianmendel.de>
@CybotTM CybotTM force-pushed the feature/overridable-templates branch from 52c03ca to a3ee246 Compare March 9, 2026 00:25
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