Adding custom CSS in Sitecore can enhance the look and feel of your Sitecore site. As a content management system, Sitecore provides several ways to incorporate CSS styling. Here are some best practices for adding CSS in Sitecore:
Locate the Main CSS File
The first step is to locate the main CSS file that controls the styling of your Sitecore site. This is usually called default.css and located in the root folder of your Sitecore installation.
You can inspect the HTML source code of your Sitecore site pages to find where default.css is referenced. The path will be relative to the root.
For example, the CSS link tag may look like:
<link rel="stylesheet" href="/default.css">
This indicates default.css is in the root.
Alternatively, the configuration file Sitecore.config will contain a WebStylesheet setting that points to the CSS file:
<setting name="WebStylesheet" value="/default.css" />
Once you locate the file path, you can navigate to it using the Content Editor in Sitecore.
Edit Main CSS File
With the path to default.css, open it within the Sitecore Content Editor. You can now add any custom CSS styles here that will apply site-wide.
For example, to change all <h1> tags to be blue:
h1 { color: blue; }
The advantage of editing the main CSS file is that the changes apply globally. However, the downside is it affects all pages using this CSS, which can cause unintended styling issues.
Therefore, it's often better to add CSS overrides in page-specific CSS files.
Create Custom CSS Files
For targeted CSS tweaks, create custom CSS files and link them in specific Sitecore templates.
Here are the steps:
- Using the Content Editor, create a new CSS item in
/sitecore/media library/. For example,custom.css. - Add any CSS styles needed for that template in
custom.css. - In the template, create a
CSS filefield. Populate it with the path to your custom CSS file, like/sitecore/media/custom.css. - Insert the
CSS filefield in the template Standard Values, using a placeholder token. For example: <link rel="stylesheet" href="[% Custom CSS File %]" />- When this template is used for a page, it will include the custom CSS file with any overrides.
This approach allows you to have different CSS files for different templates or sections of your site.
Programmatically Add CSS
You can also programmatically add CSS files in Sitecore using C# code. This involves telling Sitecore to dynamically insert a <link> tag to the CSS file.
For example:
HtmlHead.Controls.Add( new LiteralControl( "<link rel='stylesheet' href='/sitecore/media/custom.css' />"));
This code can go in a pipeline processor, event handler, or anywhere that runs during the page lifecycle.
The benefit here is the CSS file inclusion is handled by code, so it can be conditional instead of global.
Use Scriban Templating
Another option is to add CSS classes and attributes using Scriban templates. Scriban is the templating language used by Sitecore SXA.
For example, to add a CSS class to a field:
{{ sc_field i_item 'Text' [['class', 'my-css-class']] }}
Scriban provides flexibility to add CSS styling directly in templates rather than static CSS files.
Best Practices
When adding custom CSS to Sitecore, keep these best practices in mind:
- Avoid modifying the core
default.cssfile directly. Use overrides instead. - Utilize specific CSS files for areas of the site that need styling tweaks.
- Add CSS files programmatically where possible for conditional loading.
- Use Scriban templating to apply styling rules at the template level.
- Test all CSS changes locally first before deploying to production.
- Document any custom CSS added in case another developer needs to maintain it.
With some planning, you can use Sitecore's built-in CSS support and extend it for any needed styling changes. The goal is to follow conventions that make it easy to manage CSS customizations over time.
Adding CSS appropriately will ensure your Sitecore site maintains a consistent look and feel across all templates and devices.
