Drupal theming tips for web designers starting with Drupal

With this blogpost I, Drupal web designer for 10+ years, will show you how I theme my Drupal websites. How does it work, what is my set up and what do you need to be aware of.
Robert Roose
By Robert Roose

Drupal theming tips for web designers starting with Drupal

Understanding theming in Drupal

In a nutshell: Drupal generates HTML and you can create a theme to style this HTML with CSS and JavaScript.

That being said, it is possible to manipulate the way Drupal generates the HTML but I have learned it’s easier (especially for a beginner) to go with the flow. Use the HTML that Drupal gives you and only try to change it when there is no other solution. Theming this way has some benefits:

  • You don’t have to worry too much about naming things (such as classes) because Drupal does this for you
  • You save time. Changing the way Drupal generates HTML can be a time costly endeavour

The downside being that your HTML might not be as pretty and clean as you want. Drupal generates a lot of div elements which basically means a lot of clicking when inspecting elements.

Create your own boilerplate theme

I’ve made a very clean boilerplate theme which I duplicate and adjust every time I need to theme a new Drupal website. If I’m theming and I feel like I’m doing the same CSS over and over again (such as a sticky header or a fat footer) I will make sure it ends up in my boilerplate theme. This saves time and is in line with the DRY (Don't Repeat Yourself) mantra popular with coders.

It is possible to begin with a starter theme such as Bootstrap or Barrio but I’ve learned it was a lot of hassle to remove things I didn’t use or to revert the default styling. Also using an already bloated theme as your starting point might not be beneficial to the size and speed of your website. This is bad for your SEO and for the environment. Also, you will learn much more creating your own boilerplate theme instead of relying on someone else’s CSS. So let's start creating a (boilerplate) Drupal theme.

Telling Drupal all about your theme

Go to the themes directory located in the root of your Drupal website. Create a folder and give it the name your theme should be called. This can be anything, but make sure it’s all lowercase with no special characters. My boilerplate theme is called bones (cool huh?). Now go into this folder and create the following file mytheme.info.yml. Which in my case would be bones.info.yml. Next add the following to your mytheme.info.yml file:

name: MyTheme

type: theme

description: 'This is MyTheme.'

core_version_requirement: ^9

libraries:

  - mytheme/global-styling

  - mytheme/global-scripts

base theme: classy



regions:

  header: 'Header'

  hero: 'Hero'

  tabs: 'Tabs'

  content: 'Content'

  footer: 'Footer'

  bottom: 'Bottom'



ckeditor_stylesheets:

- css/style.css  

A quick explanation of each element:

  • The name is the name of your theme. This will be shown in the backend when you install this theme
  • The type is theme which is what we are creating
  • The description contains a description of your theme. This will also be shown in the backend.
  • With the core_version_requirement you can determine the compatible Drupal version. In this case this would be Drupal 9.
  • With the libraries element you can determine what CSS and JavaScript will be loaded. We will cover this in more detail in the next step
  • When you set a base theme you will use all the CSS, JavaScript and adjusted template files from this theme. You then have the possibility to override specific CSS, JavaScript or templates. As a base theme I've set classy. This is a theme that comes with the Drupal core and provides extra class names for the rendered HTML elements. So to make your front ending job easier, I would say this is a must.
  • The regions are the areas in your theme where you can place blocks. You can customize this as you please but beware that you have to render the regions in your page.html.twig file as well. I will get into more detail in a later step
  • Setting the ckeditor_stylesheets is a cool feature which makes the styling of your website available in your WYSIWYG editor while creating or editing nodes

Pointing Drupal to your CSS and JavaScript files

Next you need to create a themename.libraries.yml file. In this file you point to the CSS and JavaScript files that your theme will use. My libraries.yml file contains the following:

global-styling:

  version: 1.x

  css:

    theme:

      css/normalize.css: {}

      css/style.css: {}

global-scripts:

  version: 1.x

  js: 

    js/script.js: {}

Creating CSS and JavaScript files

These files and folders don’t exist yet so let’s create them. Go to your theme folder and create a folder named css. In this folder create a style.css file. This will be the main file where you will write your CSS. 

You also want to add normalize.css to this folder. This will make sure all default styles will look the same across browsers saving you a lot of time fixing cross browser issues.

Go to your Drupal theme and create a folder named js. In this folder create a file called script.js. In this file you can put all your custom JavaScript. While theming I tend to not use this file all that much. The only thing I’m currently using it for is adding a class name to the header when the user scrolls down. This way I can make the header, usually containing a logo and navigation, more compact when the user scrolls down.

How to override the HTML that is generated by Drupal

If you want to override HTML that is generated by Drupal, you will need to create a templates folder inside your Drupal theme folder. Here you can create so-called twig files with which you can tell Drupal how the HTML should be generated. 

Creating these twig files from scratch is a lot of work and also unnecessary. The best way is to go to the theme folder of the base theme you’re using, which you have specified in your themename.info.yml. In my case that would be Classy which is located at core/themes/classy. Here you will find a templates folder as well. Within this folder you will find subfolders which categorize specific Drupal elements. One folder, which is particularly important, is the layout folder. In this folder you will find (among others) two files which you want to override, namely:

  • html.html.twig
  • page.html.twig

Copy these files over to your own templates folder in your theme folder. You can also create a layout subfolder, which isn’t required, but does help keep things clear.

If you open the html.html.twig file you can see that this is the file which generates the <html>, <body> and the <head> tag. You can overwrite this file by adding scripts such as Google Fonts (although you might want to load these locally). I always overwrite this file so I can point Drupal to my custom favicon icons which I generate with this favicon generator.

The page.html.twig file renders everything in the <body> tag. This is important because here you can determine which regions should be rendered where. These are the regions you have specified in your themename.info.yml file. Rendering a region is done as follow:

 

  {% if page.hero %}

    {{ page.hero }}

  {% endif %}

 

Basically saying that if there is a block in the hero region then render the region. If you don’t enclose {{ page.hero }} within the if statement Drupal will always generate the (empty) region.  

Your logo and screenshot

If you upload an SVG of your logo called logo.svg to your theme folder this can be used by Drupal in a Site Branding block under Structure > Block layout.

Another file that you can upload is screenshot.png. This will be shown in the themes overview under Appearance. The ideal dimensions of this image are 588 pixels wide and 438 pixels high.

How to go forward

Go to Appearance in the Drupal backend. If all went well you should now see your theme with the correct name, description and screenshot under Uninstalled themes. Click on Install and set as default.

Now you can add your CSS and JavaScript to your theme and start theming! If some changes are not immediately visible it might be because the cache is still turned on. Navigate to Configuration > Development > Performace and uncheck Aggregate CSS files and Aggregate JavaScript files.

If you have any questions about theming a Drupal website let me know by leaving a comment below. Also don't forget to my Drupal newsletter or my Drupal RSS Feed :)

More Drupal web design blogs

The content of this field is kept private and will not be shown publicly.

Restricted HTML

  • Allowed HTML tags: <a href hreflang> <em> <strong> <cite> <blockquote cite> <code> <ul type> <ol start type> <li> <dl> <dt> <dd> <h2 id> <h3 id> <h4 id> <h5 id> <h6 id>
  • Lines and paragraphs break automatically.
  • Web page addresses and email addresses turn into links automatically.