Configure HTML caching

Current version: 8.2

The HTML cache is an output cache that caches renderings, not whole pages. You use the HTML cache to improve the performance of websites.

To enable the HTML output cache:

  1. Patch the site specification of predefined sites in the sites node of the \App_Config\Sitecore.config\App_Config\Sitecore\CMS.Core\Sitecore.Sites.config file and set the cacheHtml property of sites to true to enable the HTML output cache for that site.


    The website default site set up during installation is already there. You must specify this setting for any site you create yourself and that you want HTML caching for.


    You can specify the size of each cache in the htmlCacheSize property of a site node.

  2. Add caching options to the renderings Sitecore caches output for. You can do this in two ways:

    • Locally by specifying the options every time you use a rendering. To do this, open the item in the Content Editor, and on the Presentation tab, click Details, and then click the rendering you want to set options for.

    • Globally by specifying the options in the definition item of the rendering. This is then the default setting for all uses of this rendering. To do this, open the rendering definition item in the sitecore/Layout/Renderings part of the content tree, and navigate to the options in the Caching section.

    The options are:

    • Cacheable

      Specifies if Sitecore caches the rendering or not.

    • Clear on Index Update

      Sitecore clears the cache when it updates the content search index.

      This is important if your Sitecore instance uses HTML caching for renderings, controls, or sublayouts that contain code, and this code depends on an index. For more information, see Index-dependent HTML caching.

    • Vary by Data

      Sitecore caches output based on the item accessed. This is useful when content is highly consistent, for example: headers and footers.

    • Vary by Device

      Sitecore caches output for each device separately.

    • Vary by Login

      Sitecore caches two copies of the output: one for authenticated users, and one for unauthenticated users.

    • Vary by Parameters

      Sitecore caches output for each parameter the rendering accepts.

    • Vary by Query String

      Sitecore caches output for each unique combination of query string parameters.

    • Vary by User

      Sitecore caches output for each authenticated user.

  3. In a standard Sitecore installation, Sitecore clears the cache on each publish. This is specified for the default website. If you add websites, you must patch the Sitecore.config setting like this:

    • Add the website to the publish:end event handler:

          <event name="publish:end">
            <handler type="Sitecore.Publishing.HtmlCacheClearer, Sitecore.Kernel" method="ClearCache">
              <sites hint="list">
                <site>website</site> <!-- the default site -->
                <site>yoursite</site> <!-- your site(s) -->
            <handler type="Sitecore.Publishing.RenderingParametersCacheClearer, Sitecore.Kernel" method="ClearCache" />
  4. Sitecore clears caches for all sites you configure with the value of the cacheHtml property as true. The publish:end event handler is configured like this in a standard installation:

       <event name="publish:end">
          <handler type="Sitecore.Publishing.SmartHtmlCacheClearer, Sitecore.Kernel" method="ClearCache" resolve="true" />

    If you do not want the cache for a site to be cleared when you publish you can add the preventHtmlCacheClear attribute to the site definition like this:

    <site name="custom_website" cacheHtml="true" preventHtmlCacheClear="true" … />

Do you have some feedback for us?

If you have suggestions for improving this article,