Week 5: Override the Main Page Template

This is Week 5 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 about the concept of template files and override the main page template. 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: Override the Main Page Template) before you move on to Week 6: Set Variables, Use Filters, and Add Classes in Templates.


  1. Understand the concept of template files in Drupal
  2. Complete Exercise: Override the Main Page Template:
  • Override the default page template file in order to change structural markup for your theme
  • Add new markup and CSS classes to Drupal's default markup

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

Template files are responsible for the HTML markup of every page generated by Drupal. Any file ending with the .html.twig extension is a template file. These files are composed of standard HTML markup as well as tokens used by the Twig template engine to represent dynamic content that will be substituted into the HTML markup when the template is used. As a theme developer, you'll work with this a lot.

In this tutorial we’re going to learn about:

  • What template files are, and how they fit into the big picture of creating a theme
  • How template files are used in order to allow theme developers to modify the HTML markup output by Drupal
  • Naming conventions for, and specificity of, template files
Drupal 8, 9, and 10
More information

This tutorial demonstrates how to locate the template file that is currently being used to render an element and override it in your own theme. This is an important skill for anyone who wants to make changes to Drupal's default HTML markup.

In this tutorial we'll:

  • Override the node.html.twig template in our theme
  • Make changes to the markup
  • Create a content-type-specific template override like node--CONTENT_TYPE.html.twig

By the end of this tutorial you should be able to modify the HTML markup used to display a node, or any other element of the page generated using a template file.

Drupal 8, 9, and 10
More information

If you want to make changes to the HTML markup of any element on the page you need to first figure out the theme hook or base name of the template file used to generate it. This information is required to override the template in your custom theme.

There are other situations in which knowing the theme hook name of a template file is useful. Including determining which preprocess function affects a template, and which template theme hook suggestions can be used.

In this tutorial we'll learn:

  • How to figure out the theme hook name for any template

By the end of this tutorial you should be able to use the output from Twig's debugging mode to determine the theme hook name of any template file.

Drupal 8, 9, and 10
More information

In order to change Drupal's default markup you need to override template files. The page template controls the overall layout of your theme, including the placement of regions. You should complete the exercise just following the written instructions and you can use the video to help if you get stuck.

If you want to try and do this on your own first you'll need to:

  • Override the currently used page.html.twig template file.
  • Modify the content of the file to include the regions defined in the theme's .info.yml file.
  • Wrap the regions in the page template file with HTML markup using CSS classes from Bootstrap to achieve the example layout below.

Illustration of layout with header, menu, breadcrumb, and higlighted regions all full width, content and both sidebars as 3 columns, and one column for each of the two footer regions.

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

This course appears in the following guides:
New to Drupal theming? This hands-on guide is for you.

Hands-On Theming