In addition to looking for a template namednode.html.twig, Drupal will also attempt to locate variations of the file based on context, and use those variations if they exist. This allows for fine-grained control over which template file is used in any given context.

Sometimes you might want to get more specific and change the markup of an element only in specific cases. A common example would be providing different markup for nodes of a specific type, like blog posts. In addition to looking through the theme's chain of inheritance for a template file, Drupal will also look for templates that match a predefined naming convention for a best-fit match. These potential alternate names are referred to as theme hook suggestions.

1. node--{NODE.NID}.html.twig -- node-123.html.twig
2. node--{NODE.TYPE}.html.twig -- node--blog_post.html.twig
3. node.html.twig

Example 1: Displayingnode/123, node type: "blog_post".

1. [] themes/icecream/templates/node--42.html.twig (Not a match; wrong node ID)
2. [x] themes/icecream/templates/node--blog_post.html.twig (Match: node type; template used)
3. [ ] themes/icecream/templates/node.html.twig

Example 2: Displayingnode/21, node type: "page".

1. [ ] themes/icecream/templates/node--42.html.twig (Not a match; wrong node ID)
2. [ ] themes/icecream/templates/node--blog_post.html.twig (Not a match: wrong node type)
3. [x] themes/icecream/templates/node.html.twig (Match: all nodes; template used)

Example Twig debug output:

Suggestions added by hooks

Theme hook suggestions are provided by one of three hooks. Both modules and themes can add or remove suggestions from the list.

• hook_theme_suggestions_HOOK(array $variables)
• hook_theme_suggestions_alter(array &$suggestions, array $variables, $hook)
• hook_theme_suggestions_HOOK_alter(array &$suggestions, array $variables)