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.

If you liked this, you'll love my book, Conquer Drupal 8 Module Development.