Making a custom theme from scratch in Drupal 8: Part 1 - Settings and Services

Submitted by Craig Clark on Sun, 04/16/2017 - 08:48
Blank Canvas

These are my notes on making a custom theme in Drupal 8. If this can help anybody else, great!

It's really worth the time to read the Drupal 8 theming documentation and the Drupal 8 Theming guide.

Before starting, there are some useful things to do in our settings files.

Settings changes that help with theming

  1. in settings.php, enable a local settings file. This will look after turning off caching.  You enable it by un-commenting this line:
    if (file_exists($app_root . '/' . $site_path . '/settings.local.php')) {
    include $app_root . '/' . $site_path . '/settings.local.php';
    }
  2. in /sites look for example.settings.local.php
  3. copy it to /sites/default
  4. rename it to settings.local.php
    I don't keep a copy of settings.local.php on the production server. It prevents caching. That is good for development, bad for people trying to use your website.
  5. open /sites/default/services.yml
  6. enable twig debugging by switching debug to "true"
        debug: true

What has happened here is that settings.php has been told to look for a settings.local.php file and use it if present. This file can be customised as you see fit. By default, it's disabling caching.  I find this easier than remembering to turn caching or CSS and JavaScript off in the admin pages. Then by turning on the debugger in services.yml we are able to see templating information in  developer tools. For example:

<!-- THEME DEBUG -->
<!-- THEME HOOK: 'menu__main' -->
<!-- FILE NAME SUGGESTIONS:
   * menu--main.html.twig
   x menu.html.twig
-->
<!-- BEGIN OUTPUT from 'core/themes/stable/templates/navigation/menu.html.twig' -->

         <ul>
                  <li><a href="/" data-drupal-link-system-path="&lt;front&gt;">Home</a></li>

                  <li><a href="/about" data-drupal-link-system-path="node/22">About</a></li>

                  <li><a href="/portfolio" data-drupal-link-system-path="portfolio">Portfolio</a></li>

                  <li><a href="/blog" title="Blog" data-drupal-link-system-path="blog">Blog</a></li>

                  <li><a href="/contact" data-drupal-link-system-path="contact">Contact</a></li>
        </ul>
  


<!-- END OUTPUT from 'core/themes/stable/templates/navigation/menu.html.twig' -->

The 'x' indicates the template file the that is being used. The files marked with an '*' don't exist, but you could use a template file with that name to override the one being used. More on that in part 2.