Articles

This section covers how to work with themes in Drupal.

Translation of the official documentation from Drupal.org. Authors are listed under each article.

A theme is a collection of files that define the presentation layer. You can also create one or more "sub-themes" or theme variations. Only a .info.yml file is required, but most themes and sub-themes will use additional files. This page lists the files and folders found in a typical theme or sub-theme.

Theme Location

You should place themes in the "themes" folder of your Drupal installation. Note that core Drupal themes like Bartik and Seven are located in the core/themes folder of your installation.

Adding regions to your theme requires:

• Adding region metadata in the THEMENAME.info.yml file.
• Editing the page.html.twig file and printing the new regions.

Note: If you declare any regions in your theme—even just one—the default regions will no longer apply, and you are responsible for declaring all the regions you intend to use.

This documentation is for themes. For information about modules, see Adding stylesheets (CSS) and JavaScript (JS) to a Drupal 8 module.

In Drupal 8, stylesheets (CSS) and JavaScript (JS) are loaded using the same system for both modules (code) and themes: asset libraries.

For clarity, these instructions are intended ONLY for working in themes and do not apply to modules.

Twig is a templating engine for PHP and is part of the Symfony2 framework.

In Drupal 8, Twig replaces PHPTemplate as the default templating engine. As a result of this change, all theme_* functions and *.tpl.php files based on PHPTemplate have been replaced by *.html.twig template files.

Drupal allows you to override all templates used to generate HTML markup, so you can fully control the output markup in your custom theme. There are templates for every part of the page, from the high-level HTML down to small fields.

Overriding Templates

You can override Drupal core templates by adding templates to your theme folder that follow specific naming conventions.

To override templates, you need to:

Drupal loads templates based on specific naming conventions. This allows you to override templates by adding them to your theme and assigning specific names.

After adding a template, you must rebuild the cache so that Drupal can detect your new template.

About Twig

Twig is a compiled template language based on PHP. When your web page is rendered, the Twig engine takes the template and converts it into a "compiled" PHP template, which is stored in a secure directory at sites/default/files/php/twig. Compilation happens once, template files are cached for reuse, and recompiled when the Twig cache is cleared.

The Drupal Twig initiative shares the same motivation as Symfony’s: to introduce a modern, powerful, object-oriented engine that allows developers to properly focus on Drupal.

When working with a Twig template file, most variables are documented in the file’s comments. However, when they’re not, or when themes or modules introduce new variables, we need a way to discover all available variables within the template scope. Twig provides the dump() function for inspecting variables in templates.

The dump() function will not output anything unless debugging is enabled. Learn how to enable Twig debugging.