In this chapter, let us study about Theme Customization. There are several ways to customize your theme. Grav provides many features and a few functionalities to easily customize your theme.

Custom CSS

You can provide your own custom.css file to customize your theme. The Antimatter theme refers the css/custom.css file through the use of Asset Manager. If no reference to the CSS file is found, then the Asset Manager will not add the reference to HTML. Creating the CSS file in Antimatter”s css/ folder will override the default CSS. For example −

custom.css

body a {
   color: #FFFF00;
}

The default link color is overriden and set to yellow.

Custom SCSS/LESS

Another way to provide custom CSS file is by using the custom.scss file. The SCSS( Syntactically Awesome Style Sheets ) is a CSS preprocessor which allows you to build CSS efficiently through the use of operators, variables, nested structures, imports, partials and mix-ins. The Antimatter is written using SCSS.

In order to use SCSS, you need the SCSS compiler. You can use the command-line tools and the GUI applications to install SCSS compilers on any platform. Antimatter uses the scss/ folder to place all your .scss files. The compiled files are stored in css-compiled/ folder.

The SCSS files should be watched for any updates which can be done by using the following command −

scss --watch scss:css-compiled

The above command tells the SCSS compiler to watch the directory called scss and whenever the css-compiled folder is updated the SCSS compiler should compile it.

You can keep your custom SCSS code in scss/template/_custom.scss file. There are many advantages of keeping your code in this file.

• Any update from the SCSS files and other CSS files are compiled into css-compiled/template.css file

• You can access any of the SCSS that are used in your theme and make use of all variables and mix-ins available to it.

• For easier development, you are provided with access to all the features and functionalities of standard SCSS.

An example of _custom.scss file is shown below −

body {
   a {
      color: darken($core-accent, 20%);
   }
}

When you upgrade your theme, all the custom css will be overridden. This is the major drawback of choosing this way to customize a theme. This can be solved by using the theme inheritance.

Theme Inheritance

Theme Inheritance is the best way of modifying or customizing a theme and can be accomplished with a few setups. The basic idea is that a theme is defined as the base-theme that you are inheriting from, and only some bits can be modified and the rest of the things is handled by the base theme. The advantage of using theme inheritance is that the customized inherited theme will not be directly impacted whenever the base theme is updated. To accomplish this, you need to follow these steps.

• To store your new theme, create new folder called mytheme/ inside /user/themes/ folder.

• Next you need to create a new theme YAML file called mytheme.yaml under the newly created /user/themes/mytheme/ folder with the following content.

streams:
   schemes:
      theme:
         type: ReadOnlyStream
         prefixes:
            '''':
               - user/themes/mytheme
               - user/themes/antimatter

• Create a YAML file called blueprints.yaml under the /user/themes/mytheme/ folder with the following content.

name: MyTheme
version: 1.0.0
description: "Extending Antimatter"
icon: crosshairs
author:
   name: Team Grav
   email: [email protected]
   url: http://getgrav.org

We will now understand how to define a theme blueprints.yaml that consists of basic elements. More details can be provided for form definitions to control your form functionalities. The blueprints.yaml file can be examined for more details on this.

• In your user/config/system.yaml file edit pages: theme: option to change your default theme to new theme as shown below.

pages:
   theme: mytheme

Now new theme is created and Antimatter will be the base theme for this new mytheme theme. If you want to modify specific SCSS we need to configure SCSS compiler so that it looks your mytheme theme first and secondly the Antimatter theme.

It uses the following settings −

• First copy the template.scss file which is placed in the antimatter/scss/ folder and paste it in the mytheme/scss/ folder. This file will contain all the @import calls for various files like template/_custom.scss and sub files.

• The load-path points to antimatter/scss/ folder which contains large number of SCSS files. To run the SCSS compiler, you need to provide load-path to it as shown below.

scss --load-path ../antimatter/scss --watch scss:css-compiled

• Now, create a file called _custom.scss under mytheme/scss/template/. This file will contain all your modifications.

When the custom SCSS file is changed, automatically all the SCSS files will be compiled again into template.css which is located under the mytheme/css-compiled/ folder and then the Grav references this accurately.