Why does Drupal (8) not discover my custom taxonomy term template? Following the instructions on how to create a custom template for taxonomy terms I managed to add a template suggestion for a particular view mode of the taxonomy term entity by using hook_theme_suggestions_HOOK_alter:

function linkup_theme_suggestions_taxonomy_term_alter(&amp;$suggestions, $vars, $hook) {
  if($vars['elements']['#view_mode'] == 'teaser') {
    $suggestions[] = 'taxonomy-term--teaser';
  }
}


(linkup is the name of my custom theme)

This seems to work as I can see the template suggestions when I print the twig debug information:

&lt;!-- THEME DEBUG --&gt;
&lt;!-- THEME HOOK: 'taxonomy_term' --&gt;
&lt;!-- FILE NAME SUGGESTIONS:
   * taxonomy-term--teaser.html.twig
   * taxonomy-term--15.html.twig
   * taxonomy-term--group.html.twig
   x taxonomy-term.html.twig
--&gt;
&lt;!-- BEGIN OUTPUT from 'core/themes/stable/templates/content/taxonomy-term.html.twig' --&gt;


But for some reason Drupal does not pick up the template which is located in themes/linkup/templates/taxonomy-term--teaser.html.twig

I think the naming is correct (unlike Drupal 7 in 8 you dont need to fiddle with underscores to match dashes in file names)

If I add a template called taxonomy-term.html.twig to the theme then that is discovered.

Am I missing some of Drupal 8's logic to discover the custom template?
You need to use underscores in your suggestion (but continue to use dashes in your template file name):

/**
 * Implements hook_theme_suggestions_HOOK_alter() for taxonomies.
 *
 * {@inheritdoc}
 */
function HOOK_theme_suggestions_taxonomy_term_alter(&amp;$suggestions, $vars, $hook) {
  if($vars['elements']['#view_mode'] == 'teaser') {
    $suggestions[] = 'taxonomy_term__teaser'; // note underscores
  }
}


you could also leave out your condition and do:

/**
 * Implements hook_theme_suggestions_HOOK_alter() for taxonomies.
 *
 * {@inheritdoc}
 */
function HOOK_theme_suggestions_taxonomy_term_alter(&amp;$suggestions, $vars, $hook) {      
  $suggestions[] = 'taxonomy_term__' . $vars['elements']['#view_mode'];
}