Where should an aspiring web developer who wants to try out Drupal 8 begin? In a series of posts I’ll walk you through a few basic exercises to help you get acquainted with Drupal 8.

If you’re already a real pro scooting around D8 in your coding skills equivalent of a jetski – this content is clearly not for you. But if you feel a bit lost where to start and want to try out some basic Drupal development you’re welcome to read along.

This first post will simply show you how create a child theme. Having a custom child theme will allow you to have a set of ”your own files” where you can start coding without hacking core.

I guess it may seem self evident to most people, but it’s still worth mentioning, that you never, under any circumstances, want to hack core. Why? Because doing so will make you ”enter a world of pain, Smokey” (ten points to whoever pins that quote). Here are three reasons why:

  1. Hacking core means that you will not be able to safely update Drupal Core or contrib modules further down the line. Drupal provides plenty of hooks and opportunities for you to alter and add things without touching the code in core or in contributed modules and themes.
  2. Hacking core exposes you as someone who doesn’t know Drupal and is too lazy and arrogant to do basic research and read the API on drupal.org
  3. A kitten dies every time you hack core (https://drupal.stackexchange.com/questions/59054/why-dont-we-hack-core)

Creating a child theme to Bartik

Install Drupal 8 by your preferred method. As of lately I recommend using Acquia Dev Desktop for learning and testing purposes – read about that in my previous blog post here (http://leanderlindahl.se/article/acquia-dev-desktop-fastlane-drupal-8-development).

Find your document root and open it in an editor such as PHPStorm or Sublime.

Find your local site root in Acquia Dev Desktop.

The "vanilla" file tree of your site root in PHPStorm

For the purpose of this tutorial we’re going to create a custom child theme named Katniss in the themes-folder. The theme will be based on the Bartik that is the default theme in Drupal 8.

Open the themes folder in your site root (e.g ~/username/Sites/devdesktop/drupal-8.3.2/themes). This is the location where you store themes – both downloaded contributed themes from drupal.org and custom themes that you create yourself. (In Drupal 7 this used to be sites/all/themes.) To keep everything orderly and pretty we are going to create a folder inside themes named “custom”. If you download contributed themes from drupal.org or elsewhere, you should place them in a folder named “contrib". This subfolder structure (themes/custom and themes/contib) is a convention and not a technical requirement. But if you are going to become a honourable Drupal citizen you should go for the “orderly and pretty” option and follow this Drupal convention.

Now in the themes/custom folder you create the actual folder containing your theme. In this example where we’re creating a theme named “Katniss” the folder should be named “katniss” (lowercase is the convention of all folder and file names).

Inside “katniss” create a new file named katniss.info.yml. And insert the following code (this is what actually creates the theme in the eyes of Drupal):

name: Katniss
type: theme
description: Custom theme for District 12
core: 8.x
base theme: bartik
  - katniss/global-styling

The name value is the "human readable" name of your theme. This could be something other than the machine name "katniss", such as "Everdeen" or "My super AweSome fancy Theme". But it's usually a good idea to keep this name more or less the same as the machine name to avoid confusion, in this case we're going with "Katniss".

The type value declares to Drupal that this is a theme.

The description value allows you to specify a description for your theme.

The base theme value is used if you want your theme to be based on another theme. Basing your theme on another means that your theme will inherit all the settings and templates from another theme unless you actively override those settings and templates with your own settings and templates.

The core value declares with what version of Drupal your theme is compatible. In our case this is Drupal 8.x, which means all versions of Drupal 8.

Now libraries is slightly more tricky. This declaration allows you to attach CSS and JavaScript files to your theme. In this case we're declaring "katniss/global-styling". This means that Drupal will look in "katniss" for a file named "katniss.libraries.yml". In this file it will look up the declaration of "global-styling". We could have named this anything. But we didn't. So let's create "katniss.libraries.yml" and declare "global-styling".

  version: 1.0
      css/style.css: {}

To keep this exercise simple we'll only add a style.css file where we can add css to our theme. You could also add javascript and other resources, such as font-awesome in the libraries declaration.

So now we've added a stylesheet to our theme and it will live in the theme's folder (katniss) in a subfolder named css. The file itself will be name "style.css". This is what the source file tree should look like now:

Katniss Theme – katniss.libraries.yml

There's actually one more thing we have do to to avoid having errors thrown. If we're using Bartik as base theme the template files we're inheriting are expecting the same regions as in Bartik to be available. Thus we need to copy the regions declaration from core/themes/bartik/bartik.info.yml into our own katniss.info.yml:

name: Katniss
type: theme
description: Custom theme for District 12
core: 8.x
base theme: bartik
  - katniss/global-styling
  header: Header
  primary_menu: 'Primary menu'
  secondary_menu: 'Secondary menu'
  page_top: 'Page top'
  page_bottom: 'Page bottom'
  highlighted: Highlighted
  featured_top: 'Featured top'
  breadcrumb: Breadcrumb
  content: Content
  sidebar_first: 'Sidebar first'
  sidebar_second: 'Sidebar second'
  featured_bottom_first: 'Featured bottom first'
  featured_bottom_second: 'Featured bottom second'
  featured_bottom_third: 'Featured bottom third'
  footer_first: 'Footer first'
  footer_second: 'Footer second'
  footer_third: 'Footer third'
  footer_fourth: 'Footer fourth'
  footer_fifth: 'Footer fifth'

Now your theme should be available in the "Appearance menu" of your Drupal Site and you should be able to install it and set it as default:

Choosing a theme in Drupal 8.

As the crowning of your work, and to verify that your theme is now the "boss" of your Drupal site's appearance create the file themes/custom/katniss/css/style.css and enter the following:

* {
	color: red !important;

Empty the cache with admin/config/development/performance in a different browser tab and view the result. It should look something like this:

Impact of style.css for the Katniss Drupal 8 child theme

This CSS is kind of awkward and is only meant as a test for you to establish that your actual CSS impacts the site.

So now you have a child theme for Drupal 8, where you can start coding to your hearts content. In the next article of this series we'll have a look at setting up your development environment without the very strict and "heavy" default caching that Drupal 8 has "out of the box".

Happy coding!