2) Getting Started with a Drupal 8 Theme

August 13, 2015

Lessons From the Road

Back in 2014, I set out on an adventure with Memorial Sloan Kettering and multiple web and design agencies to begin building the first fully-operational, enterprise-level Drupal 8 website. We succesfully launched the site in May of 2015. I want to share some of the real-world lessons I learned over the past year, so that hopefully you can start adopting Drupal 8.

Overview of files and folders

When you look into Drupal’s root folder, there is a new folder there called “themes” wherein your custom theme folder will reside. While the old D7 path (sites/SITENAME/themes/) is still valid location, let’s start using the new root level themes folder, as it seems destined to happily be accepted as the best practice. So create a folder with your theme’s name and place it inside DRUPAL_ROOT/themes/

The basic files and structure in your theme is as follows:

Basic Drupal 8 Theme Folder Structure

configuration

install

MYTHEME.settings.yml

templates

favicon.ico

MYTHEME.info.yml

MYTHEME.libraries.yml

MYTHEME.theme

screenshot.png

MYTHEME.settings.yml

default configuration to be used when theme is enabled.

templates directory

a directory in which you can place your custom twig template files for overriding core templates.

favicon.ico

default place that Drupal will look for your theme’s favicon.

MYTHEME.info.yml

the basic meta data about your theme (more below)

MYTHEME.libraries.yml

defines css and js libraries and dependencies that can be included in your theme

default place that Drupal will look for a screenshot of your theme which will be used on the admin/appearance page when enabling themes.

Now you are also going to need a place for your custom CSS, javaScript, images, fonts, and other assets. How you organize these in your theme is a bit of personal taste. If you are pulling in these assets from a prototype system such as pattern lab, you may want to have your grunt automation place all of these things into one assets folder organized like so:

Example assets folder

assets

css

js

images

fonts

Or for example if you are developing right in your Drupal theme, with tools such as sass, compass, bundlr, bower, and Grunt you can put your config.rb, Gemfile, Gruntfile.js, etc. right in your theme root.

Example Drupal 8 Theme Folder Structure

configuration

install

MYTHEME.settings.yml

css

MYTHEME.css

js

MYTHEME.js

sass

MYTHEME.scss

templates

config.rb

favicon.ico

Gemfile

Gemfile.lock

MYTHEME.info.yml

MYTHEME.libraries.yml

MYTHEME.theme

screenshot.png

However you decide to organize your assets, we will need to let Drupal know where to find things and what to include which I will be covering in a future installment.

the parent theme being used. If not using any just omit the line altogether.

libraries

defining which css and JS libraries will be used

regions

machine_name: ‘Friendly Name’ of regions in which you can place blocks.

stylesheets-override/stylesheets-remove

a list of core stylesheets that you would like to override and a list of that you would like to remove.

A note on base themes:
A parent theme’s preprocessing code, templates, and css are used by default, however the regions defined in a parent theme are not automatically available to the child them, so you need to define the regions again in your theme.

Quick intro to YAML

YAML is a format that is used to represent serialized data, but does so in a way that makes it more human readable than other options (such as JSON). Ways that it achieves better human readablity is by not using enclosures (such as brackets) or open/close-tags and representing hierarchy via whitespace indentation. Keep in mind that even though it is human readable, it still has a syntax that needs to be learned. Check out wikipedia for more info…

Written by Brad Wade

Brad Wade is a front-end web developer, Drupal specialist, and musician living in New York City.