One of the many changes in Drupal 8 is that all HTML output is rendered via a Twig template. This means that if you want to override the HTML for a given page, node, region or field, you can copy the Twig template that is being used to your theme and make your changes.
As you can see in the diagram below, a page is made up of many templates.
There are actually more templates than what you see here as this diagram doesn’t go down to field level (each field can have its own template).
For any given page, node, region or field, there is normally more than one template that Drupal could use and it will choose the most specific one. Have a look at Drupal.org to find out more about how Drupal decides which template to use.
So the question is, how do you know which template is being used? And if you override a template, how can you verify that your template is now used?
Fortunately Drupal makes this pretty easy with these steps:
- Turn on Twig debug mode
- View the page source to see the templates in HTML comments
Turn on Twig debug mode
If you haven’t already done so, you need to create a services.yml file for your site:
- Go to sites/default
- Copy
default.services.yml
and name itservices.yml
You’ll notice that undertwig.config
, debug
is set to false.
To turn on Twig’s debug mode, you can run the following Drupal Console command:
$ drupal site:mode dev
Not using Drupal Console?
You can manually make this change in your sites services.yml
file. In the services.yml
file, find twig.config
and set debug
to true.
Don’t have twig.config in your services.yml file?
Don’t worry, you may not have it in your particular setup. All you need to do is add the following in your services.yml
file:
parameters:
twig.config:
debug: true
Check that if you already have parameters
. You may have another entry such as:
parameters:
http.response.debug_cacheability_headers: true
If this is the case, add the twig.config and debug lines to that, like so:
parameters:
http.response.debug_cacheability_headers: true
twig.config:
debug: true
Once you have this set up, it is time to view the page source to see the Twig templates.
View the page source
Go to a node and view the page source. You should now see a whole range of HTML comments that list the Twig templates like so:
<!— THEME DEBUG -->
<!-- THEME HOOK: 'html' -->
<!-- FILE NAME SUGGESTIONS:
html--front.html.twig
html--node.html.twig
x html.html.twig
-->
<!-- BEGIN OUTPUT from 'core/themes/classy/templates/layout/html.html.twig' -->
What is this telling you?
For each template that is used for the page, these comments are telling you the suggested templates. You’ll see a x next to the template that is used. And then the BEGIN OUTPUT line is telling you the location of that template.
In the example above, the following are potential templates:
html--front.html.twig
html--node.html.twig
html.html.twig
If there was a html--front.html.twig
in my sites theme, then that would have been used (assuming I’m on the front page). But because there isn’t a html--front.html.twig
or a html—node.html.twig
in this theme or the parent theme, so html.html.twig
is used.
<!-- BEGIN OUTPUT from 'core/themes/classy/templates/layout/html.html.twig' -->
This is telling you the path to the html.html.twig
template that is used. This includes the theme, classy, which in this case is the parent theme.
If I want to customise this, I could simply copy the template from the classy theme and add to my sub theme. After rebuilding the cache, the output would change to:
<!-- BEGIN OUTPUT from 'core/themes/mytheme/templates/layout/html.html.twig' -->
If you want to make changes to use the front page html.html.twig
template and leave all other pages as is, then you can create a new file in your theme called html-front.html.twig
. As you have seen above, if you are on your sites front page, html-front.html.twig
is at the top of the list. This means it will be used if it is available.
After creating the html-front.html.twig
template, you’ll have an empty file. The easiest method to create a starting point is to copy the contents of html.html.twig
and to html-front.html.twig
and then make your changes (alternatively, you could copy the entire file and change the name to html-front.html.twig
when pasting in your theme).
Wrapping up
Drupal has a set of rules to determine which template it will use. The process for finding the template and making changes to it is:
Overriding an existing template:
- View the page source
- Find the template you are looking for
- Identify the template being used in the code comments
- Copy the template to your theme to override it
- Make your changes
Create a more specific template than the one being used:
- View the page source
- Find the template you are looking for
- Identify the specific template from the list in the code comments
- Create a new template with that name in your theme
- Copy the contents of the generic template to the new template
- Make your changes