Server Side Compiling of Sass & Less Files - Documentation topics on: compiling,css,less,sass,server side,.

Server Side Compiling of Sass & Less Files

Dotcms is one of the first content management systems to offer server side editing/compiling of Sass and Less files "on the fly."  Modern front end development is best authored in a CSS pre-processor such as Sass or Less.  CSS pre-processors extend the CSS language, allowing for additional features, variables, mixins and functions, and allows CSS to be more maintainable, themable and extendible.

Why Sass and Less?

Both Sass and Less CSS pre-processors have great documentation, well founded communities, and are essential to any modern front-end workflow

Advantages of uploading Sass and Less files to dotCMS

  • Server side editing and instant compiling of Sass/Less files
  • Files are minified on compile
  • Revertable change/user history kept on every Sass/Less file
  • Cache rebuilds each time files are edited

How to Reference Sass and Less files in a dotCMS Template

When properly referenced in the template code, the Sass/Less files compiles server side "on the fly" and are cached.  Sass/Less files can be uploaded/edited via webdav or from the dotCMS backend. Each save to the file is stored in the files change history and triggers an update of the cache.

Sass files: After creating the appropriate Sass files to control template styling, such as in the example below:


Then the appropriate reference to the css would be:


Less files: When using Less files to control template styling:


Then the appropriate reference to the css would be:


How to Reference Sass and Less files in dotCMS Themes

Sass and Less files can be uploaded directly to a dotCMS Theme. The $dotTheme.path variable should be used in the pathing references to the file. Below are some recommended pathing examples when calling Sass/Less files from one of the them vtl files.

Proper Pathing of Sass and Less Files in Themes

The proper way to reference the CSS files that are created by these sass files is by using this simple pathing scheme which will compile and cache the css files from the sass files as they are called and automatically update the cache:


Given the examples above, the proper pathing to the auto-generated CSS files would be:


Proper Pathing of Less Files in Themes

For example, our Muted Blue theme on the website downloads with the following files:


Since the Muted Blue theme downloads with Less files instead of the Sass files, then the pathing to the auto-generated CSS files would be:


Example Themes with Pre-built Sass/Less Files

Download sample themes using various frameworks on the website.  Each downloadable theme includes pre-built Sass and Less files:

Caching of Sass and Less files

Sass/Less files have their own cache that can be manually flushed from the System → Maintenance portlet under the cache tab.

Each change to a Sass/Less file reloads the cache so that the cache stays in synch with file updates whether they are made through editing the file directly in dotCMS or thru a Webdav connection.

Importing other Files into Sass/Less Files

The "@import" command allows other files to be called into a Sass/Less file. If the file being imported resides on the same host as the file making the import call, then a relative path can be used:

@import "/path_to_file/file_name.less";

If the file being imported resides on another host on the same dotCMS instance, then the import path must begin with "//" so that the other host can be referenced in the pathing:/p>

@import "//host_name/path_to_file/file_name.less";

Caution: Sass/Less files residing on other servers, outside the existing instance, may NOT be imported via http call.

Debugging (Available when logged in to the dotCMS backend only)

To debug issues with the Sass/Less compiler, the un-minified version of the CSS can be examined by setting the following debug parameters to true in the pathing





Using this debug option, webmasters can verify that the non-minified css output matches the expected result.

Forcing the Recompile of the Sass/Less File (Available when logged in to the dotCMS backend only)

To force the re-compile of the Sass/Less file, add the recompile=true parameter to the end of the path to the file:





The recompile option allows webmasters to force a recompile of the Sass/Less file to CSS, verify the recompile in the dotcms.log, and check that code matches expected result.