Rendered-HTML Caching

Boost site speed even further.

As of v1.7.8, Statamic now includes an html_caching bundle. When turned on, Statamic will cache the rendered HTML for each of your pages and will serve that up instead of rendering the pages on the fly every time.

Turning on HTML Caching

To turn on HTML caching:

1. Open _config/bundles/html_caching/html_caching.yaml
2. Set enable to true

Done. If you’d like, you can set the other three features:

• cache_length lets you determine how long a cached rendered page should be served for before being re-rendered; you can set this to either a time value (like “12 hours” or “10 minutes”), or “on last modified” which will keep rendered pages around until the URL’s content file is touched on the server
• exclude is an optional pipe-separated list of URLs to not use HTML caching for
• ignore_query_strings (added in [v1.7.9]) when true will ignore query strings appended to a URL, so that all base URLs always use the same cache — for example, when false, /about and /about?foo=bar are seen as two different pages, when true, they’re the same

note The on cache update option for cache_length has been deprecated and will function like on last modified. This is due to a couple of flaws that it had that could not be resolved due to the way Statamic works internally.

To better understand how exclude works with wildcarding, let’s use the default Statamic sample content as an example.

• survival-guide will only match the URL /survival-guide and none of its sub-pages
• survival-guide* will match the URL /survival-guide and all of its sub-pages
• survival-guide/* will not match /survival-guide but will match all of its sub-pages

How it Works

Each time a URL is requested, the html_caching bundle will check to see if it’s enabled. If it’s on and there is a valid version of the rendered HTML saved for this page it will display that one to the user.

If html_caching is not on, or it’s on but the current URL is being excluded, or if the current URL isn’t being excluded by there isn’t a valid version of the rendered HTML saved for this page, Statamic will render the page as it normally would. If html_caching is enabled, the rendered page will be saved for later use.

Things to Note

HTML caching stores the entire rendered HTML page. It doesn’t take into account things like entries falling into (or out of) the live window of an {{ entries:listing }} tag, or places where you do sort_by="random". We added the exclude option so that you weren’t forced to use this feature wholesale, but on a page-by-page basis is the smallest level of detail this will work with.

With ignore_query_strings, if you have it on and (from the example above) /about and /about?foo=bar will render two different pages, the one that gets cached for /about is whichever one is visited first when the cache for /about is invalid. The number one question people will ask is “what about pagination?” Setting this option to true will break pagination, and thus, should only be used sparingly.

Results

Our testing found that enabling HTML-caching can cut page-display times by up to 90%, and about 85% on average.