As a web developer who spends a significant amount of time fine-tuning Drupal themes, one of the most common hurdles is figuring out exactly which Twig template is rendering a particular piece of markup. In this article, I’ll walk you through some effective strategies and tools for debugging Twig templates in Drupal, helping you get from confusion to clarity faster.

1. Enable Twig Debugging

The most essential step is enabling Twig debugging. Doing this gives you invaluable hints directly in your page markup, showing which templates are used and what suggestions are available.

How to enable Twig debug:

1. Edit your sites/default/services.yml file.
2. Set the following Twig configuration:

parameters:
  twig.config:
    debug: true
    auto_reload: true
    cache: false

3. Then, clear the cache with Drupal’s UI or with Drush:

drush cache-rebuild

4. Inspect the page source. You will now see HTML comments around content blocks, indicating exactly which Twig template files are being used and the options available for overrides.

2. Use the Devel Module

Drupal’s Devel module is a must-have for developers. Among its many features, it offers comprehensive debugging tools, including a feature that lets you inspect the render arrays and see which templates are involved.

• Install via Composer: composer require drupal/devel
• Enable the module: drush en devel
• Use the “Twig debug” tab that Devel adds to the admin toolbar, or use the “Theme info” tray on the page.

3. Drupal’s Theme Debug Class

When debugging, it’s useful to add a custom class to body or other wrappers to distinguish between templates. You can do this temporarily via preprocessing functions in your theme’s .theme file:

function MYTHEME_preprocess_page(&$variables) {
  $variables['attributes']['class'][] = 'debug-page-template';
}

This makes it easy to search your markup and identify where a certain template starts and ends.

4. Use Kint for Powerful Variable Inspection

The Devel module also comes with Kint, an advanced variable dumper. Calling kint($variables); or {{ kint(_context) }} (if Devel Kint Twig is enabled) in your Twig files or preprocess functions lets you inspect what data is available to the template.

5. Practice Template Suggestion Discovery

One hidden gem: In the Twig debug HTML comments, Drupal lists not only the current template, but also the suggestion chain. If you want to customize a specific block or node type, look for the most specific suggestion (like node--article.html.twig) and place your custom template there.

---

Debugging templates in Drupal can be tricky at first, but with these tools and techniques, you’ll reduce guesswork and speed up theme development tremendously. If you have any other tricks for mastering Twig in Drupal, drop them in the comments below!

Happy debugging!

— Drew