Best Practices For Working With CSS in Kentico


This article describes best practices of how you can work with CSS in Kentico. It is divided into two sections. The first section describes a simple scenario, in which a front-end developer wants to write raw CSS without using any advanced tools such as CSS preprocessors or file. The second, more advanced scenario is intended for developers that make use of the more advanced tools and need the CSS files to be stored in filesystem so that they can apply their usual workflow when writing CSS in Kentico.

Basic scenario: Writing CSS using the Kentico “CSS Stylesheets” Application

Scenario description: Let’s say that the only thing you will need to style is a simple landing page. You don’t need any automation tools, you just need to be up and running very quickly. All you need to do is to follow these two steps (I also encourage you to read the info boxes below the steps, as there might be useful hints for you as well):

  1. Navigate to the CSS Stylesheets application and create new stylesheet, with display name set to "[YourSite] - Styles", where [YourSite] is your site’s code name.
  2. Then, include the stylesheet in your page. There are multiple ways, but this is what we recommend: go to the Sites application, click the pen button next to your site to edit your site, and then select the previously created stylesheet in the "Site CSS Stylesheet" dropdown on the General tab.

Info: In this scenario, we recommend using the CSS Stylesheets application as the only place to store your CSS code. There are also other places where you can put your CSS code, like web parts and other page components. We highly discourage doing that, as you won’t have a centralized control over your CSS code. Instead, it will be spread throughout the whole UI.

Info: If you want to have multiple CSS files per one site, you can include one into another. This way, you will have one Main CSS file. The file will only include other files. Use the {% CSS["Navigation"] %} macro inside your CSS file to include stylesheet called "Navigation" into that file. Note that after each change in the child CSS files you need to resave the main CSS file.

Advanced scenario: Using automation tools to write your CSS code

Scenario description: In this scenario, we assume that you need some more advanced tools for creating your CSS code like CSS preprocessors, code hinting, bundling, etc. We call that automation and you will need to store your CSS files in the filesystem in this case.

Info: This article does not describe what you need to do in order to use CSS preprocessors or code hinting. It assumes that you already know that and you just need to use these tools together with your Kentico instance.

You won't be using the CSS Stylesheets application. All of your CSS files will be stored on the filesystem and you will just need to include the resulting CSS file in your site’s Master page. You will need to complete the following steps:
Note: It is important to strictly follow the naming conventions in step 1 to make sure that your stylesheet files work with Kentico’s import/export functionality.

  1. In your Kentico project, there is a folder named after your site’s code name (If the folder is not there, create it. Just make sure that the folder’s name exactly matches your site’s code name). This is where you need to store your CSS files. Just create a subfolder called Stylesheets, for example, and you are ready to store your CSS code inside that folder.
  2. Then, simply use your front-end, start up your node console, set it up for bundling your LESS or SASS files, use your favorite code editor and you are good to go!
  3. The last step is to include your resulting bundle file in your Kentico Site. Let’s say your Site’s CodeName is “YourSite” and your bundle CSS file is called “Styles.css”. Go to the Page application, select the Master page tab and include this code snippet '<link href="~/CMSPages/GetResource.ashx?stylesheetfile=/{% CurrentSiteName %}/Stylesheets/Styles.css" type="text/css" rel="stylesheet" />' to the head section, as in the following image:

Note: Please note that the approach described in the advanced scenario, besides its main advantage (using your own code editor and front-end workflow), does not currently work with Kentico staging and web farms functionality.

Note: You can also notice that the file is linked using ‘GetResource.ashx’ handler. The reasons are that you can then leverage on Kentico’s minification, server caching, resolving of relative URLs, etc.

And that’s all. Please leave any feedback or questions in the comments below.

Share this article on   LinkedIn Google+

Ondrej Vasil

I'm a Technical Leader of the Web Development team in Kentico Software. I'm going to write articles connected with a real life development using Kentico.


kentico_ondrejv commented on

Hi Dmitriy,

I think that the only way to prevent content editors doing mess around a site is to prevent them to add inline code. No offence, just saying. Well, we were in similar situation when starting to redesign our web site - we wanted our content editors to have free hands as much as possible but after several discussions about their front-end skills and responsibilities we ended up that their job is content and ours is websites' look and feel. We have unified our typography rules and content outline for newly designed responsive pages which provided a great playground for them.

I see that it is not exactly as you described as we don't have each page with its unique design, but I wanted to point out the idea about the roles :-) If you would like to go beyond, I would recommend using a style guide with defined classes which would content editors enter (or maybe develop custom widgets in order to be able to insert whole content blocks and allow them adjusting via widget properties).

Hope it makes sense

Ondrej Vasil

Dmitriy commented on

Hi! Thanks for the article. It's in way useful, but in another way I would like to know more in terms of using CSS for content managers. For example we have a rather big site with loads of custom content and content managers heavily use inline CSS snippets (which I heavily discourage). Their main reason is that it is quicker than going over to CSS stylesheets app and using the method described in this aricle and, another thing is that this specific CSS code is used only on this specific page. I would like to centralize CSS storing , but the fact that we customize many single pages for specific goals makes me think it is impossible. Maybe you can prove I'm wrong? And thank you for your work in making things easier for devs with your helpful articles!

kentico_ondrejv commented on

Hi Rashed,

There are used relative URLs in both scenarios therefore the link should reflect your protocol. What is the exact way you are loading your CSS?

Best regards
Ondrej Vasil

Rashed commented on

When using SSL this approach gives a warning that some content requested from insecure source (from http instead of https)