Skip to content

Commit 8c56472

Browse files
CybotTMCybotTM
committed
[FEATURE] Make templates overridable
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>
1 parent c753119 commit 8c56472

File tree

4 files changed

+256
-1
lines changed

4 files changed

+256
-1
lines changed

‎Dockerfile‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,8 @@ ARG TYPO3AZUREEDGEURIVERSION
3131
ENV TYPO3AZUREEDGEURIVERSION=$TYPO3AZUREEDGEURIVERSION
3232

3333
WORKDIR /project
34+
RUN mkdir -p /templates
35+
3436
ENTRYPOINT [ "/opt/guides/entrypoint.sh" ]
3537
CMD ["-h"]
3638

‎Documentation/Index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -45,4 +45,5 @@ to extend the tool.
4545
Developer/Index
4646
Redirects/Index
4747
Migration/Index
48+
Templating/Index
4849
KnownProblems/Index

‎Documentation/Templating/Index.rst‎

Lines changed: 237 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,237 @@
1+
.. include:: /Includes.rst.txt
2+
3+
.. _override-templates:
4+
5+
====================
6+
Overriding templates
7+
====================
8+
9+
By default, the render-guides container uses the Twig templates shipped
10+
with the official TYPO3 Documentation theme. You can provide your own
11+
templates to customize or extend the rendering output **without modifying
12+
the container image**.
13+
14+
.. important::
15+
16+
Custom templates are only supported when you build the documentation
17+
**locally** (for example using Docker or DDEV) or within your **own
18+
CI/CD pipeline**.
19+
20+
When your project documentation is built and deployed automatically via
21+
the **official TYPO3 documentation workflow** (to
22+
`https://docs.typo3.org <https://docs.typo3.org>`_), custom templates
23+
are **not supported**.
24+
25+
The central rendering service uses a fixed, controlled version of the
26+
official theme to ensure consistency across all published manuals.
27+
28+
.. _template-override-mechanism:
29+
30+
How template overriding works
31+
=============================
32+
33+
The TYPO3 Documentation theme registers a list of template search paths.
34+
When rendering, the Twig template engine resolves templates by checking
35+
these paths **in order** and using the first match.
36+
37+
When custom template directories are present, they are prepended to the
38+
search path, giving them higher priority than the built-in templates.
39+
40+
The resolution order is:
41+
42+
#. Custom templates mounted via Docker volume at :file:`/templates`
43+
(highest priority)
44+
#. Custom templates bundled in the project at
45+
:file:`resources/custom-templates` (relative to the project root)
46+
#. TYPO3-specific theme templates
47+
#. Bootstrap 5 theme templates (fallback)
48+
#. Base phpDocumentor templates (fallback)
49+
50+
.. _template-docker-volume:
51+
52+
Method 1: mount a Docker volume
53+
===============================
54+
55+
Mount a local directory into the container at the path :file:`/templates`.
56+
57+
For example, if your custom templates are stored in a folder named
58+
:file:`my-custom-templates` in your current working directory:
59+
60+
.. code-block:: shell
61+
62+
docker run --rm \
63+
--pull always \
64+
-v "$(pwd):/project" \
65+
-v "$(pwd)/my-custom-templates:/templates:ro" \
66+
-it ghcr.io/typo3-documentation/render-guides:latest \
67+
--progress --config=Documentation
68+
69+
.. note::
70+
71+
The :file:`/templates` path is **separate from** the :file:`/project`
72+
mount point. This avoids volume mount ordering issues that can occur
73+
when nesting volumes.
74+
75+
.. _template-project-bundled:
76+
77+
Method 2: bundle templates in your project
78+
==========================================
79+
80+
Place your custom templates in a directory named
81+
:file:`resources/custom-templates` **at the root of your repository**:
82+
83+
.. code-block:: text
84+
85+
my-project/
86+
|-- Documentation/
87+
| |-- Index.rst
88+
| +-- ...
89+
|-- resources/
90+
| +-- custom-templates/
91+
| +-- structure/
92+
| +-- layout.html.twig
93+
+-- ...
94+
95+
When you mount your project into the container with
96+
``-v "$(pwd):/project"``, the path
97+
:file:`/project/resources/custom-templates` is detected automatically.
98+
No extra volume mount is needed:
99+
100+
.. code-block:: shell
101+
102+
docker run --rm \
103+
--pull always \
104+
-v "$(pwd):/project" \
105+
-it ghcr.io/typo3-documentation/render-guides:latest \
106+
--progress --config=Documentation
107+
108+
.. _template-directory-structure:
109+
110+
Directory structure for custom templates
111+
========================================
112+
113+
Your custom templates must mirror the internal directory structure of the
114+
built-in templates you want to override.
115+
116+
For example, if the original file is located at:
117+
118+
.. code-block:: text
119+
120+
typo3-docs-theme/resources/template/structure/layout.html.twig
121+
122+
then your custom file must be placed at:
123+
124+
.. code-block:: text
125+
126+
my-custom-templates/structure/layout.html.twig
127+
128+
When both files exist, your version is used instead of the original.
129+
Any template you do **not** override continues to use the built-in
130+
version.
131+
132+
.. _template-finding-originals:
133+
134+
Finding the original templates
135+
==============================
136+
137+
To create a customized version of a template, first copy the original
138+
from the container image.
139+
140+
Open a shell inside the container to browse all available templates:
141+
142+
.. code-block:: shell
143+
144+
docker run --rm -it \
145+
--entrypoint=sh \
146+
ghcr.io/typo3-documentation/render-guides:latest
147+
148+
.. note::
149+
150+
The ``--entrypoint=sh`` flag is required because the container's
151+
default entrypoint routes all commands to the PHP guides application.
152+
Without it, shell commands like ``cat`` or ``ls`` would be
153+
interpreted as guides subcommands.
154+
155+
Once inside, the templates are organized as follows:
156+
157+
.. list-table::
158+
:header-rows: 1
159+
:widths: 30 70
160+
161+
* - **Theme / Purpose**
162+
- **Location in container**
163+
* - TYPO3-specific templates
164+
- :file:`/opt/guides/packages/typo3-docs-theme/resources/template/`
165+
* - Bootstrap 5 theme templates
166+
- :file:`/opt/guides/vendor/phpdocumentor/guides-theme-bootstrap/resources/template/`
167+
* - reStructuredText (reST) templates
168+
- :file:`/opt/guides/vendor/phpdocumentor/guides-restructured-text/resources/template/html/`
169+
* - Base templates (shared core)
170+
- :file:`/opt/guides/vendor/phpdocumentor/guides/resources/template/html/`
171+
172+
.. _template-copying:
173+
174+
Copying a template from the container
175+
-------------------------------------
176+
177+
To copy a specific template to your local machine, use
178+
``--entrypoint=cat``:
179+
180+
.. code-block:: shell
181+
182+
docker run --rm \
183+
--entrypoint=cat \
184+
ghcr.io/typo3-documentation/render-guides:latest \
185+
/opt/guides/packages/typo3-docs-theme/resources/template/structure/layout.html.twig \
186+
> my-custom-templates/structure/layout.html.twig
187+
188+
Make sure the target directory exists before running the command:
189+
190+
.. code-block:: shell
191+
192+
mkdir -p my-custom-templates/structure
193+
194+
Edit the copied file locally. The next time you run the container with
195+
your custom templates mounted, your modified version will automatically
196+
be used.
197+
198+
.. _template-examples:
199+
200+
Examples
201+
========
202+
203+
Override the page layout
204+
------------------------
205+
206+
.. code-block:: shell
207+
208+
mkdir -p my-custom-templates/structure
209+
210+
docker run --rm \
211+
--entrypoint=cat \
212+
ghcr.io/typo3-documentation/render-guides:latest \
213+
/opt/guides/packages/typo3-docs-theme/resources/template/structure/layout.html.twig \
214+
> my-custom-templates/structure/layout.html.twig
215+
216+
# Edit my-custom-templates/structure/layout.html.twig to your liking
217+
218+
docker run --rm \
219+
-v "$(pwd):/project" \
220+
-v "$(pwd)/my-custom-templates:/templates:ro" \
221+
-it ghcr.io/typo3-documentation/render-guides:latest \
222+
--progress --config=Documentation
223+
224+
Override block quote rendering
225+
------------------------------
226+
227+
.. code-block:: shell
228+
229+
mkdir -p my-custom-templates/body
230+
231+
docker run --rm \
232+
--entrypoint=cat \
233+
ghcr.io/typo3-documentation/render-guides:latest \
234+
/opt/guides/vendor/phpdocumentor/guides/resources/template/html/body/quote.html.twig \
235+
> my-custom-templates/body/quote.html.twig
236+
237+
# Edit and render as above

‎packages/typo3-docs-theme/src/DependencyInjection/Typo3DocsThemeExtension.php‎

Lines changed: 16 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -97,11 +97,26 @@ private function getConfigValue(array $configs, string $key, string $default): s
9797

9898
public function prepend(ContainerBuilder $container): void
9999
{
100+
$templates = [];
101+
102+
// Docker volume mount: highest custom priority
103+
if (is_dir('/templates')) {
104+
$templates[] = '/templates';
105+
}
106+
107+
// Project-bundled templates: second custom priority
108+
if (is_dir('/project/resources/custom-templates')) {
109+
$templates[] = '/project/resources/custom-templates';
110+
}
111+
112+
// Built-in theme templates: lowest priority (fallback)
113+
$templates[] = dirname(__DIR__, 2) . '/resources/template';
114+
100115
$container->prependExtensionConfig('guides', [
101116
'themes' => [
102117
'typo3docs' => [
103118
'extends' => 'bootstrap',
104-
'templates' => [dirname(__DIR__, 2) . '/resources/template'],
119+
'templates' => $templates,
105120
],
106121
],
107122

0 commit comments

Comments
 (0)