Grav - Theme Customization

In this chapter lets study about Theme Customization. There are several ways to customize your theme. Grav provides many features and few functionality 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 Asset Manager will not add the reference to HTML. Creating 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 override and set to yellow.

Custom SCSS/LESS

Another way to provide custom CSS file is by using 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 SCSS compiler. You can use command-line tools and GUI applications to install SCSS compilers on any platform. Antimatter uses 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 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 overriden. This is the major drawback of choosing this way to customize a theme. This can be solved by using theme inheritance.

Theme Inheritance

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

• To store your new theme create new folder called mytheme/ inside /user/themes/ folder.
• Next you need to create new theme YAML file called mytheme.yaml under newly created /user/themes/mytheme/ folder with below content.
  

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

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

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

  To define a theme blueprints.yaml 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 below settings:

• First copy the template.scss file which is placed in antimatter/scss/ folder and paste it in 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

• Next 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 mytheme/css-compiled/ folder and then the Grav references this accurately.