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:

1. Turn on Twig debug mode
2. 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 it services.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:

1. View the page source
2. Find the template you are looking for
3. Identify the template being used in the code comments
4. Copy the template to your theme to override it
5. Make your changes

Create a more specific template than the one being used:

1. View the page source
2. Find the template you are looking for
3. Identify the specific template from the list in the code comments
4. Create a new template with that name in your theme
5. Copy the contents of the generic template to the new template
6. Make your changes