Setting up Twig Debug Quick Guide

Published Jun 16, 2021
Updated Jul 14, 2021
By Simon
Table of contents

When developing a theme in Drupal you may want to add custom templates to override certain pages or regions of pages. Sometimes it is easy to use known patterns such as page--node--79.html.twig to override the page of node 79 or node--article.html.twig to override all nodes of article type. However, if you want to check your theme specifically you will want to enable twig debug temporarily.

There are 2 files you need to alter to do this. The files are:

  • settings.php or local.settings.php

The can be found in the sites directory.

# Local development services.
# To activate this feature, follow the instructions at the top of the
# 'example.settings.local.php' file, which sits next to this file.
  http.response.debug_cacheability_headers: true
    class: Drupal\Core\Cache\NullBackendFactory
  1. Find and open in your favourite editor.
  2. Add the twig config with debug true and autoload true setting.
  http.response.debug_cacheability_headers: true
+ twig.config:
+   debug: true
+   auto_reload: true
  1. Save the file

YAML hierarchy and indentation
YAML has strict formatting. I have found for Drupal YAML files you can easily add blocks and use the existing files contents as an example to guide you. If you do have issues I would suggest to double check the YAML formatting, in particuar whitespace and indentation.


Your settings.php should have 444 permissions so you will need to change them or use super doer (sudo) to modify it.

If you are working locally you may have a settings.local.php file otherwise you can use the setting.php file. Just be sure to remove the code added before you deploy to a production environment if you use the settings.php.

Add the following code to the bottom of the file:

$settings['container_yamls'][] = DRUPAL_ROOT . '/sites/';

Flush the caches and check the source and now you will have debugging information printed to the source. The information tells you what options you have to override the output from most specific to sitewide for each template. You can override parts of the page from full HTML to just regions. I wrote about how to find which template to use to override a basic page and a contact form where I walk through an actual use case.

I will be cover this more in a theming series in the coming months so if you are interested in tapping into Drupal as a CMS be sure to sign up for the newsletter.

Thanks for dropping by and see you again soon.