Skip to main content

Getting started with Drupal 8 theming

Jan 15 '16

In this post, we're going to dig into the basics of Drupal 8's front-end theming to get a project up and running. Drupal 8 has altered the way we think about theming with Drupal in some considerable ways. This Drupal 8 theming guide should help you get started with a boilerplate theme that you can re-use for future projects.

Create your .info YAML file

Just like Drupal 7, Drupal 8 offers the ability to configure the theme from a .info file. The difference is that Drupal is now built on top of Symfony, a powerful open-source PHP framework built by SensioLabs that brings order to way Drupal developers build websites. As a consequence, Drupal now uses YAML, "a human friendly data serialization standard for all programming languages", to manage configuration. Your theme, image styles, display settings, etc. is now managed using YAML. Sounds intimidating, but YAML is super simple, easy to read, and easy to maintain.

In your theme folder, simply create a new file called Add the following:

name: My Theme 2015
type: theme
description: 'The brand new theme for our awesome project.'
core: 8.x
base theme: false
- mytheme2015/global-styling
  header: Header
  content: Content
  sidebar: Sidebar
  subcontent: Subcontent
  footer: Footer

In the file, I've declared some basic information that I think everyone can understand but I wanted to point out a few deal breakers.

Remove the use of a base theme
I've declared `base theme: false` to stop Drupal from using any core themes. Drupal will allow you to choose from any of the themes in core to build upon and uses Classy by default. By declaring that I don't want Drupal to use a base theme, I no longer have to do any of the usual Drupal resets (removing stylesheets or JS). I now have a clean slate to do work and impress grandma with my mad theming skills.

Create a different YAML file to manage libraries
This is a great feature because we can separate our styles (CSS and JS) into modular pieces. In the example provided, we've declared our global styles but we could continue making new YAML files for specific modules, pages, or features.

Here's what we've got for the MY_THEME.libraries.yml file:

  version: 1.x
      css/styles.css: {}
      css/print.css: { media: print }
    js/main-menu.js: { scope: footer }
  - core/drupal
  - core/jquery

I've declared the global-styling portion of the theme. It's important to keep in mind that YAML cares about indentation, so be sure to indent correctly. I've passed in a couple of options to the print.css and the main-menu.js declarations. The media option allows me to tell Drupal what kind of CSS file I'm adding. The scope parameter allows me to add render blocking JS after the content and CSS is loaded on the page.

Folder structure

In Drupal 7, we had to dive deep into the folders to add our custom theme. In Drupal 8, we have the luxury of using the `themes/custom folder` to add our new theme. Finally, something sensible and rational everyone can get behind. Here's the way we structured our new theme folder:

      - logo.svg
      - MY_THEME.libraries.yml
      - MY_THEME.theme

Now that we have our theme files, global styles, and folder in place, all we need to do is hit the switch.

$ drush config-set system.theme default MY_THEME

I hope this guide illuminates some of the basics to getting a theme started. It's not going to impress grandma, but now you can do work without the usual hassle of trying to "reset" Drupal.