Drupal theme folder structure

A Drupal theme is a collection of files that control the presentation layer, which defines how your site's content is structured and styled. Drupal supports custom themes and sub-themes (variations on an existing theme). The only required file for a theme is the .info.yml file, but most themes utilize additional files for styles, scripts, templates, and more.

Location of themes

Themes should be organized within the themes directory of your Drupal installation:

• Core Themes like Olivero and Claro are located in core/themes.
• Contributed Themes should be placed in themes/contrib, which Composer uses as the default path, facilitating updates and management.
• Custom Themes should be placed in themes/custom, segregating site-specific customizations from community contributions.

Note on Deprecation: As of Drupal 10, Bartik and Seven have been deprecated and replaced by Olivero and Claro. These older themes remain in older installations and may be available through contributed modules.

Theme Structure

Each theme resides in its own directory and should adhere to specific naming conventions for compatibility and ease of management. For example, a theme directory must be all lowercase, start with a letter, and use underscores instead of spaces (e.g., my_new_theme). This convention is crucial due to Drupal's file system and module discovery mechanisms relying on consistent naming patterns.

The (partial) structure of your Drupal installation could look as follows:

  |-core
  |  |-modules
  |  |-themes
  |  |  |-claro
  |  |  |-olivero
  ..
  |-modules
  |-themes
  |  |-contrib
  |  |  |-zen
  |  |  |-basic
  |  |  |-bluemarine
  |  |-custom
  |  |  |-my_new_theme

Custom Theme Folder Structure

A typical custom theme folder might include the following structure:

  |-my_new_theme.breakpoints.yml
  |-my_new_theme.info.yml
  |-my_new_theme.libraries.yml
  |-my_new_theme.theme
  |-config
  |  |-install
  |  |  |-my_new_theme.settings.yml
  |  |-schema
  |  |  |-my_new_theme.schema.yml
  |-css
  |  |-my_new_theme.css
  |-js
  |  |-my_new_theme.js
  |-images
  |  |-buttons.png
  |-logo.svg
  |-screenshot.png
  |-templates
  |  |-maintenance-page.html.twig
  |  |-node.html.twig

StarterKit Theme Introduction

With the release of Drupal 10, the StarterKit theme provides a new way for developers to initiate theme development. Unlike traditional methods that require extending a base theme like Classy for customization, StarterKit acts as a direct starting point that can be copied to create a new theme. This method allows for greater flexibility and customization, making it ideal for projects requiring a unique design approach.

To quickly start your own theme using the StarterKit:

php web/core/scripts/drupal generate-theme my_new_theme

Core Theme Example: Olivero

Let's examine the Olivero folder structure located at core/themes/olivero:

  |-olivero.breakpoints.yml
  |-olivero.info.yml
  |-olivero.libraries.yml
  |-olivero.theme
  |-color
  |  |-color.inc
  |  |-preview.css
  |  |-preview.html
  |  |-preview.js
  |-config
  |  |-schema
  |  |  |-olivero.schema.yml
  |-css
  |  |-colors.css
  |  |-layout.css
  |  |-maintenance-page.css
  |  |-print.css
  |-images
  |  |-add.png
  |  |-required.svg
  |  |-tabs-border.png
  |-logo.svg
  |-screenshot.png
  |-templates
  |  |-block--search-form-block.html.twig
  |  |-block--system-branding-block.html.twig
  |  |-block--system-menu-block.html.twig
  |  |-block.html.twig
  |  |-comment.html.twig
  |  |-field--taxonomy-term-reference.html.twig
  |  |-maintenance-page.html.twig
  |  |-node.html.twig
  |  |-page.html.twig
  |  |-status-messages.html.twig

Below is a description of the most common files that you can find in a theme.

*.info.yml

A theme must contain an .info.yml file to define the theme. Among other things the .info.yml files define metadata, libraries, and block regions. This is the only required file in the theme.

*.libraries.yml

The .libraries.yml file is used to define JavaScript and CSS libraries that can be loaded by the theme.

*.breakpoints.yml

Breakpoints define where a responsive design needs to change in order to respond to different devices. Breakpoints are defined in a .breakpoints.yml file.

*.theme

The .theme file is a PHP file that contains all the conditional logic and data (pre)processing of the output. It may also extend basic theme settings. Creating advanced theme settings.

css/

It is good practice to store .css files in the 'css' subfolder. Drupal 8 core themes organize CSS files following the SMACSS style guide. For a theme to load CSS files they must be defined in .libraries.yml file and can be overridden or removed in .info.yml file.

js/

Theme specific JavaScript files are stored in the 'js' folder. For a theme to load JavaScript files they must be defined in .libraries.yml file.

images/

It is good practice to store images in the 'images' subfolder.

screenshot.png

If a screenshot.png file is found in the theme folder, then it will be used on the Appearance page. Alternatively, you can define a screenshot in .info.yml file.

logo.svg

If a SVG vector file of your theme's logo is found in the theme folder, then it may be used in the header of the website. Logos can also be uploaded at Appearance > Settings.

templates/

Contains Twig files that define the HTML markup and logic. Drupal replaces default core templates with your custom templates if they follow the correct naming conventions. Drupal uses the Twig templating engine to handle its HTML structure. Twig is a modern, secure, and powerful templating language designed for flexibility and security. For more information on using Twig, you can refer to the official Twig documentation.

Overriding Core Templates

You can override core templates by following specific naming conventions based on what you're overriding. For example:

• To override the default node template for the article content type, use node--article.html.twig.
• To override a specific block, use block--BLOCKNAME.html.twig (replace BLOCKNAME with the block's machine name).

Best Practices for Organizing Templates:

• Place block templates in the templates/block/ folder, e.g., templates/block/block--custom.html.twig.
• Place views templates in templates/views/, e.g., templates/views/views-view--front-page.html.twig.

More information

Coding standards: CSS file organization