Drupal 8 Theming: Basic guide to theme *.info.yml files

At Chapter Three, we’re quite versed with Drupal training. We have a long history of instructing the community on the various ways to use, theme and develop for Drupal. One of our more popular training courses has always been a head-to-toe walkthrough of Drupal 7 theming. Just before Drupal 8 was released, we created a new training series: “Drupal 8 Theming for Drupal 7 Themers”. This post is based on an exercise from that new training series.

The *.info.yml file

To create a new theme for Drupal 8, the only real requirement is to make sure you have implemented the .info.yml file (YaML, like Camel). Drupal 8 runs off of YaML files much the way that Drupal 7 ran off of .info files.

As long as you have your .info.yml file in place with a few keys in place, you have a theme (although if thats all you have in place, it's not going to be a pretty theme).

Create the theme folder and "YaML" file

1. Locate the /themes folder in your Drupal installation. In Drupal 8, Contrib and Custom modules and themes are saved at the root level in the /module and /themes folders.

2. Create a new folder in /themes or /themes/custom and call it acme

3. In that folder create a new file. It should be called acme.info.yml

4. Add the following lines to that file

   
   name: Acme
   description: My first Drupal 8 theme.
   type: theme
   base theme: classy
   core: 8.x
   version: VERSION
   
   regions:
       header: Header
       primary_menu: 'Primary menu'
       secondary_menu: 'Secondary menu'
       breadcrumb: Breadcrumb
       help: Help
       highlighted: Highlighted
       content: Content
       sidebar_first: 'Left sidebar'
       sidebar_second: 'Right Sidebar'
       footer: Footer
       page_top: 'Page top'
       page_bottom: 'Page Bottom'
   
   

Things we might find in a *.info.yml file

The following keys are items that we will often find in a *.info.yml file. Some are optional, some are required. These keys provide meta-data about your theme, and define some of the basic functionality.

1. name : The human readable name will appear on the Appearance page, where you can activate your theme. This is Required

2. description : The description is displayed on the Appearance page. This is Required

3. type : The type key indicates the type of extension, e.g. module, theme or profile. For themes this should always be set to "theme". This is Required

4. base theme : The theme can inherit the resources from another theme by defining it as a base theme. Not declaring this, will default to using "Stable" as the base theme.

5. core : The core key specifies the version of Drupal core that your theme is compatible with. This is Required

6. version : For modules hosted on drupal.org, the version number will be filled in by the packaging script. You should not specify it manually, but leave out the version line entirely.

7. regions : Regions are declared as children of the regions key. You are required to have a content region. The regions we just declared are also the default regions that are enabled by core if you do not declare any regions in your .info.yml file.

Other items

1. regions_hidden will allow you to remove regions that may be coming from a base theme, or remove any of the default regions from the output.

2. screenshot allows you to define a screenshot that is shown on the Appearance page. If you do not define this key then Drupal will look for a file named 'screenshot.png' or 'screenshot.svg' in the theme folder to display.

3. The libraries key can be used to add asset libraries to all pages where the theme is active.

   
   libraries:
       - THEMENAME/global-styling
       - THEMENAME/LIBRARY-NAME
   
   

   Theme libraries contain css and/or javascript. Theme libraries are declared in another type of YaML file (THEME.libraries.yml). We will go over libraries in later exercises.

4. The libraries-override and libraries-extend keys can be used to take control over the components of a library, remove individual items, remove the complete library, or add additional elements to a library.

5. The stylesheets-remove and stylesheets-override key are used to stop the addition of css components for core and contrib modules or to introduce new versions of those components to those libraries. Similar to libraries-override and libraries-extend but specific to stylesheets.

   
   stylesheets-remove:
     - core/assets/vendor/normalize-css/normalize.css
     - '@classy/css/components/tabs.css'
   
   

   The stylesheets-remove key removes a link to a stylesheet added by another theme or module. The full path to CSS file should be provided (instead of just the filename), to accommodate cases where more than one file with the same name exists. In cases where a Drupal core asset is being removed (for example, a CSS file in jQuery UI) the full file path is needed. In cases where the file is part of a library that belongs to a module or theme, a token can be used. Note that when using the token it needs to be quoted because @ is a reserved indicator in YAML.

6. ckeditor_stylesheets will allow you to have custom ckeditor styles attached to your theme

7. quickedit_stylesheets will allow you to have custom styles and javascript attached to the quickedit functionality

There you have it - you're now equipped with the basic knowledge needed to work with Drupal 8 theme Info files. This should open a lot of doors to custom themes, as well as manipulating existing themes!