I know I could use something like hook_theme_suggestions_HOOK_alter() to add a suggestion, which would allow me to get a template rendered, but I wish someone would explain where the original ones come from in the first place.

For example, in the Twig debugging html, I'm seeing this:

<!-- THEME HOOK: 'page' -->

...but I don't know where that 'page' hook came from. I can't exactly grep for 'page' in core. Could anyone give me an explanation the order in which these things happen, and how they're connected:

  • Something creates a list of possible templates to use (How?)
  • Drupal grabs/renders the files specified from this list, from the theme or parent theme
  • Something adds new suggestions to existing template names, allowing for specificity
  • You can add your own template names to elements, which causes it to look for those files

Even a good direction to look in core would be appreciated.

1 Answer 1


The hook page comes from a hook_theme implementation in system.module:

 * Implements hook_theme().
function system_theme() {
  return array_merge(drupal_common_theme(), [

which calls the function drupal_common_theme() in theme.inc:

function drupal_common_theme() {
  return [
    // From theme.inc.
    'html' => [
      'render element' => 'html',
    'page' => [
      'render element' => 'page',

The hook name is the top key of the array in hook_theme. See the documentation in D8 Theme API. The theme suggestions are built in core the same way as in custom code.

  • Thank you so much for that, it feels relieving to know where things come from. May 10, 2017 at 20:46

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.