Docs (Public)

Unibit supports SCSS and automatically compiles SCSS when running unibit build or unibit develop.

Sass Folder Structure

Create a folder called sass and create a new file called main.scss.njk - a typical folder structure for your SCSS filess looks like this:

├── sass
|   ├── main.scss.njk   [the main scss file, @import other scss files from here]
│   ├── imports
│   │   ├── _reset.scss
│   │   ├── _header.scss
│   │   └── _main.scss

Configure Sass

You need to define the sass configuration in the config.yml

# config.yml

sass:
  input_file: sass/main.scss.njk
  output_file: assets/css/main.css
  indentWidth: 4
  outputStyle: nested
  precision: 10

Note the main.scss.njk has the .njk extension. This allows the file to be read using Nunjucks templating. Only the main entry scss file where @imports are declared needs to have the .njk extension.

input_file - the location of the main scss file which @imports other scss files.

output_file - the location of the compiled css file. This is placed inside the the output directory. By default when running unibit build this would be /public/assets/css/main.css

Using Parameters in Sass

It is possible to use paramters from the config.yml in your main scss file. A common use case would be to set a primary_color paramter in the config and pass that as a SCSS variable such as $primary - Remember that parameters set in config.yml can be editing by a CMS so this approach is a great way to offer customisization of your themes CSS from within a CMS.

Because both Hugo and Jekyll allow templatizing only the source SCSS file, rather than any imported SCSS file. Any parameters external to SCSS must be set inside the main entry SCSS file. To specify the main entry SASS file, use sass property inside config.yml file.

For example, if the main SCSS file is main.scss, and it has external parameters, it should be postfixes with .njk, that is main.scss.njk.

main.scss.njk:

{% set colors = site.params.sass.colors %}
$colors: (
    primary: {{ colors.primary }},
    secondary: {{ colors.secondary }}
)

config.yml:

params:
  sass:
    colors:
      primary: "#ff0000"
      secondary: "#0000ff"

config.yml:

sass:
  input_file: sass/main.scss.njk
  output_file: assets/css/main.css # copies the .css file to the /static folder
  indentWidth: 4       # see node-sass for more info
  outputStyle: nested  # see node-sass for more info
  precision: 10        # see node-sass for more info

Including the main stylesheet in your theme

The best place to include the main stylesheet is in components/html_head.html. This will insert the stylesheet inside the <head> and </head> tags. Note you must reference the compiled css file not the main scss file. 

...
<link rel="stylesheet" href="{{ 'assets/css/main.css' | relative_url }}">