How do you create a node template for a content type in Drupal 8?

People often ask this question. Creating a template for a specific content type gives you a lot more control over the output for that content type than just using the standard node template. You can add specific markup, re-arrange the fields and other good things.

If you have ever done Drupal 7 theming (if not, don’t worry, read on anyway), creating a specific node template isn’t all that different in Drupal 8. You use the same naming pattern. But now we have Twig and this is a good opportunity to dig into what Twig is all about.

How do you create a template?

To create a new node template, copy the existing node.html.twig file in your theme and rename it. If your theme does not have a node.html.twig, you can copy the base template from core/modules/node/templates/node.html.twig.

Step by step

  • Go to your theme
  • Duplicate node.html.twig
  • Rename the duplicate node
    • Use the following naming convention: node--TYPE.html.twig. Change TYPE to the machine name of your content type. For example, if you have a content type called article, the twig template will be: node--article.html.twig
  • Rebuild the cache

This will allow Drupal to discover the new template.

Test it works

To test that it works, you can add a new piece of markup, such as: <p>It works!</p>. Just don’t forget to remove it after you have tested it!

What if a content type is made up of more than one word?

If you have a content type with more than one word, the words will be separated with an underscore in the content type’s machine name. For example, a content type called “Landing Page” will normally have a machine name of “landing_page” (unless you change it).

When you create a Twig template for multiple word content types, use a hyphen instead of a underscore in the template name. So the “landing_page” Twig template will be:

node--landing-page.html.twig

Note that technically the underscore should still work, but replacing with a hyphen is recommended in the official Drupal.org documentation.

What is with the double hyphen between node and article?

The double hyphen (--) is a delimiter. It separates the type of temple (node in this case) with the content type. You’ll see this in a lot of template. For example, a page template for the front page will be called page--front.html.twig.

Wrapping up

There are a lot of changes in Drupal 8, including in the theme layer. A good place to start is with creating creating node template. In this tutorial, you learnt how to create a template for a specific content type.

If you’d like to continue to learn Drupal 8 theming (or module development), jump on my newsletter as I’ll be sharing and building on this over the coming weeks and months.