Skip to main content

Best Practice: Custom CSS Overrides to Enhance Performance (MT4)

This page applies to:MindTouch 4

This article explains how to avoid having site visitors experience performance issues with your Custom CSS Overrides.



Custom CSS Overrides provide site owners with an easy way to style article content and site branding for all site visitors, or users who fit a specific user role. As CSS is an web asset that must be downloaded by a site visitor's web browser, it is ideal to make this download as fast as possible. Slow CSS downloads block the loading of the page, which can be noticeable or frustrating. 

Optimize for Minification

MindTouch will automatically minify and compress your Custom CSS Overrides, stripping out comments and all redundant spaces. The resulting CSS is much smaller and thus quicker for site visitors to download.

The Minification system assumes your Custom CSS Overrides contains only valid CSS. Including HTML markup or JavaScript may negatively affect the Minification process and result in broken styling on your site.

Avoid @import

It is highly recommended that you avoid placing @import statements in Custom CSS Overrides, such as

@import url('');

Custom CSS Overrides, after minification, are downloaded by site visitors from the Content Delivery Network (CDN). The presence of an @import statement pauses the downloading of an CSS file in order to download the imported CSS file. This causes the web page to stop loading until this operation completes. The majority of @import statements placed in Custom CSS Overrides are references to Google Fonts API. To this end, we've provided a JavaScript API to download web fonts from Google, as well as other web font providers.

Including @import in your Custom CSS Overrides disqualifies it from delivery via the Content Delivery Network. Your custom styles will instead be placed inside the web page HTML, increasing the size of the page, and missing out on the benefits of caching.

Check URLs

MindTouch tracks all web requests made to our infrastructure and the Content Delivery Network. Custom CSS Overrides with broken or unresolvable URL's can be a drain on performance for your site visitors.

.link a { background: url('12345.png'); }

This example demonstrates an image that will likely return a HTTP 404 (Not Found) response. This statement assumes that 12345.png is available at the root location of a MindTouch site or the Content Delivery Network, which it is not. This means that every time a  web page is loaded on the site, a request to a missing image is made, increasing overhead for the web page load. Often CSS is provided by a web designer and copied and pasted directly into a site's Custom CSS Overrides. The URL's in the web designer's development environment may not resolve correctly in a MindTouch staging or production site without some cleanup.

For advanced site owners, if you are using Google Chrome, Mozilla Firefox, Apple Safari or are familiar with Fiddler, you can inspect the network traffic between your browser and the Content Delivery Network to identify web assets referenced in CSS that are not resolving correctly. For the fore mentioned browsers, consult your browser's documentation regarding developer tools.

  • Was this article helpful?