Skip to content
Tutorials Center
My learning

Topics

Lesson 19 of 37 ยท Themes and Twig

Theme Structure and the Info File

Build a Drupal theme from scratch: the .info.yml file, libraries, regions, the templates folder, base themes and how Drupal finds and loads your theme.

A Drupal theme controls how everything looks: page layout, blocks, forms, fields and error pages. Unlike many systems, a Drupal theme does not contain business logic. It contains markup templates (Twig), CSS, JavaScript and a small amount of PHP for preparing data. Everything the theme shows comes from Drupal core and modules, which is why a good theme can restyle a site without touching content.

This chapter builds up from the file that makes a folder a theme to templates, preprocess functions and libraries. Drupal itself cannot run on this site, so the real code is shown read-only, and the TryIt blocks are small JavaScript stand-ins that mimic what Drupal does behind the scenes (for example discovering a theme and merging its settings). They are labelled each time.

The smallest possible theme

A theme is a folder inside themes/custom/ containing one file named NAME.info.yml. For a theme called sunrise:

TEXT
themes/custom/sunrise/
  sunrise.info.yml
  sunrise.libraries.yml
  sunrise.theme
  css/base.css
  js/menu.js
  templates/
    page.html.twig
    node--article.html.twig

The info file is plain YAML:

YAML
name: Sunrise
type: theme
description: 'A warm, readable theme for the tutorial blog.'
package: Custom
core_version_requirement: ^10 || ^11
base theme: stable9
libraries:
  - sunrise/global
regions:
  header: Header
  primary_menu: Primary menu
  content: Content
  sidebar: Sidebar
  footer: Footer

The important keys are:

  • name, type, description: how the theme appears on the Appearance page. type: theme is mandatory.
  • core_version_requirement: which Drupal versions the theme supports. Without it the theme will not install.
  • base theme: the theme you inherit from. Everything the base provides (templates, libraries, regions) is inherited unless you override it. Use stable9 for a minimal, unopinionated base, false to start from nothing, or Olivero/Claro-based starter kits for more.
  • libraries: asset bundles loaded on every page.
  • regions: the named areas blocks can be placed into. If you omit them, Drupal supplies a default set (header, content, sidebars, footer and so on).

After creating the file, clear the cache (drush cr) and enable the theme on Appearance, or with drush theme:install sunrise followed by drush config:set system.theme default sunrise.

How Drupal discovers a theme

Drupal scans the themes folders for *.info.yml files whose type is theme. The file name (without extension) is the machine name. The stand-in below mimics discovery and base theme resolution, so you can see how a chain such as sunrise to stable9 to false is built.

Node.js Stand-in: discovering themes and base-theme chains

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The chain matters because Drupal looks for each template in the active theme first, then in its base theme, then in modules and core. That is why a subtheme only needs the files it wants to change.

Libraries: CSS and JavaScript

Drupal never lets you simply add a <link> to the page. You declare assets in NAME.libraries.yml, and Drupal handles aggregation, ordering, caching and loading only where needed:

YAML
global:
  version: 1.0
  css:
    theme:
      css/base.css: {}
  js:
    js/menu.js: {}
  dependencies:
    - core/drupal
    - core/once

libraries: - sunrise/global in the info file attaches it everywhere. You can also attach a library to a single template with Twig, covered in Preprocess functions and libraries.

CSS has categories (base, layout, component, state, theme) that control the order they load in. Use theme for your own styling so it comes after the more generic layers. In JavaScript, wrap behaviour in Drupal.behaviors so it runs again after AJAX updates:

JavaScript
(function (Drupal, once) {
  Drupal.behaviors.sunriseMenu = {
    attach(context) {
      once('sunrise-menu', '.menu-toggle', context).forEach((button) => {
        button.addEventListener('click', () => document.body.classList.toggle('menu-open'));
      });
    },
  };
})(Drupal, once);

The once() helper prevents attaching the same listener twice when attach is called again for new content.

Regions and the page template

Regions are the slots of your layout. The page template prints them:

HTML
<header class="site-header">{{ page.header }}</header>
<nav>{{ page.primary_menu }}</nav>
<main>{{ page.content }}</main>
<aside>{{ page.sidebar }}</aside>
<footer>{{ page.footer }}</footer>

If a region has no blocks, page.sidebar is empty and prints nothing, so you can wrap it in {% if page.sidebar %} to avoid empty containers. The next stand-in shows how block placement fills regions, which is how the Block layout page works.

Node.js Stand-in: filling regions with placed blocks

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Theme settings and logos

The Appearance page gives each theme settings (logo, favicon, which page elements to show). Add your own with theme-settings.php and a config/schema file. The values live in configuration, so they move between environments with the rest of your configuration (configuration management).

Common mistakes

  • Forgetting core_version_requirement, so the theme never shows on Appearance.
  • Editing a template and not seeing the change: Twig is compiled and cached. Clear caches or enable Twig debug and disable the render cache in development.
  • Putting code in the theme that belongs in a module. If it must survive switching themes, it is module code.
  • Hard-coding <link> or <script> tags in templates instead of declaring libraries.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which file makes a folder a Drupal theme?

    Drupal discovers themes by scanning for NAME.info.yml files that declare type theme.
  2. 2. Where do you declare a theme's CSS and JavaScript?

    Libraries let Drupal aggregate, order and cache assets and load them only where needed.
  3. 3. What does base theme do?

    A subtheme falls back to its base theme for anything it does not override.
  4. 4. Why wrap JavaScript in Drupal.behaviors?

    Behaviors attach again to new DOM content, and once() prevents double attachment.

Summary

  • A theme is a folder with NAME.info.yml; templates, libraries and PHP hooks sit beside it.
  • base theme lets you override only what you need.
  • Declare assets in NAME.libraries.yml, not with raw tags.
  • Regions are the slots blocks are placed into; the page template prints them.
  • Clear caches after structural changes.

Next: Twig Syntax Basics