Hugo: partialCached or not?

The name is pretty self-explanatory. It caches the render of a given partial.

While it can optimize the build, especially when you have to deal with heavy templates and complex calculations, partial and partialCached keywords are not interchangeable.

Basic usage

The most common implementation would be similar to the following:

{{ partialCached "footer.html" . }}

It assumes the partial generates the same code every time.

More advanced usage

The documentation you can pass additional arguments:

{{ partialCached "footer.html" . .Section }}

Although, you might miss the point if you don’t read the documentation carefully:

The variant arguments are not available to the underlying partial template; they are only used to create unique cache keys

Those arguments are only used to create unique cache keys.

Everything wrong with cached partials

• ❌ don’t use partialCached if there are too much variants (e.g., one per page)
• ❌ don’t forget the context (2nd argument)
• ❌ don’t try to use the arguments within the partial itself
• ❌ don’t use partialCached for very small websites (e.g., one-page, portfolio)

Better practices

• ✅ remember Hugo executes the partial only once per key
• ✅ use partialCached when the content is the same on all pages or, at least, several pages (e.g., sections, footer)
• ✅ replace partialCached with partial if you encounter some performance issues or display errors

Useful links

• Hugo – documentation – partialCached
• Hugo – documentation – variable scoping