Drupal Theme Primer Part 1: Creating a Drupal Sub-theme

This article is a theming primer for someone new to Drupal, it assumes you already have a site set up and you have the ability to upload the theme to the server either using FTP, CLI or can upload via the UI.

In this article, we will first look at overriding one of the themes that come out of the box with a fresh Drupal 9 site. I will use Olivero for the demonstration, the new Drupal 9 theme which has some nice features. For more on Olivero, you can read about it on Drupal.org, in the strategic initiatives section.

To override any theme we need to create a child theme, this keeps the parent theme untouched and easy to update in the future. The process of creating a child theme is the first step in developing any Drupal theme, even if you start with the most basic theme that comes with Drupal, that being the plain canvas of Stark theme or the hidden base theme of Stable. So let's look at how to create a child theme.

Creating A Child Theme

The idea of creating a child theme is at the core of all theme development in Drupal and it is unlikely you will ever build a theme from the ground up, i.e you will at least take advantage of the HTML output by Stable theme.

As stated we will override the Olivero theme. I will keep this straightforward and only override the background. If you read the top of the  olivero.info.yml  file it is suggested to only make minor modifications in child themes to more complex themes such as Olivero as they are in active development and therefore there is a chance of it breaking your overrides at some time in the future.   

To make a child theme you only need a directory named the theme name and then an info file with the same name with the following settings at the least. I'll call my child theme Kodomo.

Image

name: Kodomo 2.0
type: theme
base theme: olivero
description: 'An extension with basic overrides to Olivero: a clean, accessible, and flexible Drupal front-end theme.'
alt text: 'Screenshot of Kodomo 2.0, Drupal front-end theme.'
package: Core
version: VERSION
core_version_requirement: ^9

Upload it to the root theme folder and you will see it is registered in the system. nice work!

Image

Theme Directories

A note on the theme folder in the root, this won't be overridden when you make core Drupal updates.
Themes that come with Drupal are in the core/themes directory and you are best not to touch these.

Add the Regions to the THEME_NAME.info.yml

One last step to make your sub-theme work with the parent base theme is to add the regions. We will be looking at regions and adding your own in a later part but even if you are only doing basic overrides to a base theme you need to add the regions in your info YAML. If you don't then you get a somewhat random order of core regions that won't match the theme you are overriding. So grab the regions from the core/themes/olivero/olivero.info.yml and put them in your new theme info YAML. You can grab them from the latest version on the git.drupalcode website. Below is what you YAML file should now look,

name: 'Kodomo 2.0'
type: theme
base theme: olivero
description: 'An extension to a clean, accessible, and flexible Drupal front-end theme.'
alt text: 'Screenshot of Olivero 2.0, Drupal front-end theme.'
package: Core
version: VERSION
core_version_requirement: ^9
regions:
  header: Header
  primary_menu: 'Primary menu'
  secondary_menu: 'Secondary menu'
  hero: 'Hero (full width)'
  highlighted: Highlighted
  breadcrumb: Breadcrumb
  social: Social Bar
  content_above: Content Above
  content: Content
  sidebar: 'Sidebar'
  content_below: 'Content Below'
  footer_top: 'Footer Top'
  footer_bottom: 'Footer Bottom'

If you only add a theme info file though the theme will not look or act any different so let's do a few more things like change the background colour.

Making the child theme ours by modifying the CSS

To change the CSS we need to register the CSS as a library in our info file. Add the following to the theme info.

core_version_requirement: ^9
+libraries:
+  - kodomo/global-styling

This code informs Drupal that a libraries file exists so now we need to create it.
Create a THEME_NAME.libraries.yml file and place the following code in it.

global-styling:
  version: VERSION
  css:
    theme:
      css/base.css: {}

This code registers the global styles and tells the system where to find them. In our case, we have added the CSS base.css file inside the CSS directory. Below is the file structure now, which also includes a screenshot png file so that our theme is recognisable on the appearance theme page in the Drupal backend.

Image

I am going to add a few styles to the base.css, namely a background gradient and a few UI colour changes and then upload it to the remote site.

Once uploaded, clear the cache and refresh the browser and in the back-end, you will see the new screenshot and if you navigate to the site you will see the colour is now green.

Clear the cache

To clear the cache visit /admin/config/development/performance on your site and click Clear all caches button. If you have admin toolbar installed and I suggest you do then you can access this functionality from the admin toolbar.

Related: Setting up Twig debug and Twig cache disable (content coming).

Other Considerations when Setting up a Custom Theme

Something to note when overriding a theme you also get the same theme settings page and the default settings will be enabled. In the case of Olivero you need to include a default logo, disable it (the default) or you can upload your own in the UI, otherwise, you get the home alt text where the logo should be.

Well, that's about it for this theme primer. If you want more info on how adding libraries works I suggest you read the Drupal site. It shows you how to add one-off libraries to global CSS and JS as we have done for CSS. It also shows how you can add them using Twig. I will cover a lot of this stuff in the next parts of this Drupal themeing primer series so be sure to sign up if you are interested in that. I also write about front-end development and design, covering UI/UX and also modern frameworks such as Vue.js.

This may seem a very basic override but with Drupal's amazing content display management, you can actually get a long way to developing quite a unique site that is modern and easily updatable. If you are keen to find out more about display management I have covered it in a few articles about creating blocks and another about adding a field to your Drupal site and configuring the display. Over time I will cover more on this topic but hopefully, those articles will wet your thirst.

Because it is recommended not to do major overrides to complex themes such as Olivero or other core or contributed themes, in the next part we will look at modifying the Stable and Classy themes and what the differences are. 

Thanks for reading!

Related: Drupal Theme Primer Part 2: Using Stable and Classy as Base Themes