Creating and customizing a sub-theme

Sub-themes are a powerful way to build in Drupal, since they inherit all elements of their parent theme while being able to override or extend individual elements.

Tip

For developers building a Drupal theme for the first time, start by reading:

The Forty Acres theme includes a sub-theme template called “Starter Kit.” Developers can copy this template to create a sub-theme for extending the elements provided by Forty Acres. Edits should not be made to the Forty Acres theme directly.

Contents

Scaffold a sub-theme

  1. Decide on a descriptive, unique name for your sub-theme. For the purposes of the following steps, the name “College of X Theme” will be used. In this example, the machine name – which may only contain underscores, digits and lowercase letters – will be college_of_x_theme.

  2. Create a new directory at /web/themes/<site-namespace>/college_of_x_theme and copy the contents of /web/themes/custom/forty_acres/STARTERKIT) into it.

  3. Find-replace the text “STARTERKIT” with your sub-theme’s machine name in the following files:

  • /config/install/STARTERKIT.settings.yml

  • package.json

  • STARTERKIT.info.yml (the filename and 2 instances inside this file)

  • STARTERKIT.theme

  • STARTERKIT.libraries.yml

Customize the sub-theme

Customizing templates

Drupal uses Twig html template files to define markup of pages and components, and Forty Acres defines many of these in its /templates directory. To override a Forty Acres theme template, copy it into the templates directory in your new sub-theme.

References in those templates may need to be updated with the namespace of your new sub-theme. For example, if you copy the header.html.twig file into your new sub-theme, you would need to copy the page.html.twig file and reference the include file with the new theme namespace.

In other words, within page.html.twig, you would change:

{% include '@forty_acres/includes/header.html.twig' %}

to

{% include '@your_sub-theme/includes/header.html.twig' %}

Customizing JS

There is an example.custom.js file in the /js directory. It is referenced in the <theme-name>.libraries.yml file. To use it, rename it per your sub-theme machine name, and update the reference in your <theme-name>.libraries.yml file. For more background, read Adding stylesheets (CSS) and JavaScript (JS) to a Drupal theme.

Customizing CSS

There are two ways to add or modify CSS in a sub-theme:

  1. Add CSS to the styles.css file in the /css directory. Any styles here will get read last and override all other styles.

  2. Create SCSS files and compile them. Detailed instructions follow in Theme development with SCSS.