[FEATURE] Make templates overridable#1190
Open
CybotTM wants to merge 2 commits intoTYPO3-Documentation:mainfrom
Open
[FEATURE] Make templates overridable#1190CybotTM wants to merge 2 commits intoTYPO3-Documentation:mainfrom
CybotTM wants to merge 2 commits intoTYPO3-Documentation:mainfrom
Conversation
Member
|
@kaystrobach would this solution work for you? |
|
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) |
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>
52c03ca to
a3ee246
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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:
/templates(highest priority)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:
/templatesinstead of/project/custom-templatesto avoid Docker volume mount ordering issues when both paths are
nested under
/project--entrypoint=cat/--entrypoint=sh— the container entrypoint routes all commands tothe PHP guides binary, so bare
catfails with"Command 'cat' is not defined"
resources/custom-templatespath (was mentioned in original docsbut not implemented)
precedence over project-bundled templates
Changed files
DockerfileTypo3DocsThemeExtension.php/templatesand/project/resources/custom-templateswithis_dir()+is_readable()guards, build template path array in priority orderDocumentation/Templating/Index.rstDocumentation/Index.rst