Week 2: Create a New Theme

This is Week 2 of the 7-week course Hands-On: Theming. Get started with Drupal theming in 1 hour a week for 7 weeks. Based on our popular Drupal Theming Workshop featured at DrupalCon.

Time to complete: About 1 hour

This week you will learn how to create an info file using YAML to give Drupal information about your theme including an initial set of regions. Go through each tutorial and then apply what you've learned in the final hands-on exercise. Be sure to complete the last tutorial listed (Exercise: Create a New Theme) before you move on to Week 3: Add an Asset Library.


  1. Understand what YAML is and its basic syntax rules.
  2. Understand the concept of an "info" file in a theme.
  3. Understand the concept of regions in a theme.
  4. Complete Exercise: Create a New Theme:
  • Create an info file that describes a new custom theme to Drupal
  • Define regions for that custom theme
  • Enable and view your new custom theme

Sign-up for weekly email reminders

Sign-up for the Hands-On Theming email list and get reminders and tips about each week's exercises!


Own this course

You can also purchase the Practical Drupal Theming course on Thinkific. The course material is the same, but you can access the content without a Drupalize.Me membership and you will own the course forever.

Tutorials in this course
Drupal 8, 9, and 10
More information

Info files, aka THEMENAME.info.yml files, provide Drupal with metadata about your theme, the features it supports, and the regions that it defines. All themes are required to have a THEMENAME.info.yml file, and creating one is generally the first step you'll take when creating a new theme.

In this tutorial we'll:

  • Create a new .info.yml file and define a new theme
  • Review the required key/value pairs of an .info.yml file
  • Enable our new theme in the Drupal UI

By the end of this tutorial you'll be able start a new theme by creating the required *.info.yml file and better understand its contents.

Drupal 8, 9, and 10
More information

Before visitors to your site will see the pages displayed using a theme the theme needs to be installed and set as the default. This is true whether it's a custom theme you wrote yourself, or a contributed theme you downloaded from Drupal.org. Installing themes can be done either via the user interface, or using Drush. Once a theme is installed, users of your site will see all public facing page rendered using that theme. Themes that are no longer being used can safely be uninstalled.

In this tutorial we'll:

  • Demonstrate how to install a theme and make it the default using both the UI and Drush.
  • Learn to differentiate between installed themes, default themes, and uninstalled themes.
  • Configure our site to use an administration theme for the administrative pages.

By the end of this tutorial you should be able to install a theme and make it the one visitors to your site see by default.

Drupal 8, 9, and 10
More information

Themes define the regions that are available for site administrators to place blocks in, creating a layout framework within which the components that compose a page can be placed. As a theme developer you'll need to determine what regions are necessary to accommodate your design's layout, while also ensuring it'll work with the way Drupal uses blocks to place content onto the page. Deciding what regions to create requires knowledge of how Drupal works and a clear vision of the design you're trying to achieve.

In this tutorial we'll:

  • Explain what regions are and how they relate to themes
  • Describe how regions are handled internally within Drupal
  • Demonstrate things to keep in mind when planning the regions for your custom theme

By the end of this tutorial you should be able to describe what a region is, explain how Drupal themes use regions to place content, and get started dissecting your own designs into regions.

Drupal 8, 9, and 10
More information

Customizing the available regions in your theme is one of the first things you'll do when creating your own themes. Doing so gives you complete control over where content is displayed on the page, and the markup involved. Adding regions to a theme is a two-step process that involves editing your theme's THEMENAME.info.yml file and updating your page.html.twig file.

In this tutorial we'll:

  • Declare one or more new regions in our themes THEMENAME.info.yml file.
  • Output the content of those regions in our theme via the page.html.twig file.

By the end of this tutorial you should be able to add or edit the regions a theme provides. Also, you'll ensure that blocks placed into regions are displayed by outputting the regions in the page template.

Drupal 8, 9, and 10
More information

It's time to create the bare-bones structure for a new theme on your site. You should try to complete this exercise based on the information you've learned in this chapter. The video included will walk you through the implementation of this exercise if you need some help. In this exercise you will need to:

  • Create an info file that describes a custom theme to Drupal with the regions listed below (we're going to name ours "reboot").
  • Enable, and view, a bare-bones custom theme.


'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)
'Footer first' (footer_first)
'Footer second' (footer_second)

Note: At the end of this exercise, you'll find a video walk-through of the solution.

This course appears in the following guides:
Site Building, Theming, Module Development
Drupal 9, 10
Site Building, Theming, Site Administration
Drupal 9
Drupal 8, 9, and 10