Skip to content

Cache static sidebar tree with partialCached to speed up large-site builds #942

@kaixinol

Description

@kaixinol

Feature Description

Add partialCached for the static portion of the sidebar tree to reduce repeated sidebar computation on large docs sites, while keeping per-page sidebar state dynamic.

Problem/Solution

On large sites, sidebar rendering is repeatedly computed across many pages even when the tree is mostly identical.

Here are the metrics from hugo --templateMetrics for my custom theme:

  • _partials/sidebar.html: high cumulative template cost across many invocations (e.g. 43.6s cumulative, 454 calls)
  • Build wall-clock time is still ~4.2s (Total in 4175 ms), because Hugo renders in parallel

So this is not a contradiction:

  • Total = real elapsed build time
  • cumulative = summed template execution time across calls

Proposed solution:

  1. Split sidebar rendering:
  • Cached static tree (section/page hierarchy, sidebar menu structure)
  • Uncached page-specific state (active/open, page TOC, .Store.Set effects)
  1. Cache only static tree using partialCached with shared keys (not per-page URL), e.g.:
  • language
  • nav root / section
  • relevant sidebar config flags

Expected result:

  • Reduced repeated sidebar work
  • Non-zero cache hits on sidebar static partial
  • No behavior regressions

Alternatives Considered

  1. Cache the entire sidebar partial
    Not ideal, because it includes per-page state (.RelPermalink, .IsAncestor, .Fragments.Headings) and side effects.

  2. Keep current implementation
    Functionally correct, but does repeated tree traversal at scale.

  3. External pre-generated nav data
    Possible but adds complexity and maintenance overhead.

Additional Context

  • This request targets Hugo build-time optimization, not frontend runtime speed.
  • The sidebar is a strong repeated hotspot in template metrics for large docs structures.
  • Since Hugo renders concurrently, cumulative template time should be interpreted as hotspot evidence, not wall-clock build time.

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions