Theme: Improve build performance

[marcuspollio]

While the current theme code is fairly decent (about 1ms per page on 5K pages and almost 1K processed images, about 5s in total on old laptop CPU), there are many improvements and optimizations possible:

Template:

• Better cache: see Hugo docs for hugo build --templateMetrics --templateMetricsHints for templates with many calls
• Reduce nested loops in templates: avoid O(n²) complexity
• Reduce expensive calls: site pages or collections traversals, filtering and sorting
• Reduce image and assets pipelines to strictly needed, caching artifacts if reusable between cover, cards, render-hooks

Config:

• Optimize settings and config
• Make better use of segments

[marcuspollio]

The latest refactors (e.g. e14f593, c4c9030) and other changes already improved the build performance.

On my old quad-core laptop CPU (i7-7700HQ) and Ubuntu 22.04 LTS, building the production site (currently 7 languages) for a total of 5300 pages, 530 non-page and static files, and process 1010 images, takes now 3500-4000 ms, so 0.65-0.75 ms per page.
The same for the build step on the Hugo main GitHub CI action workflow takes 7000-8000ms (118MB artifact size).

So pretty good. But we can probably do even better 😁

[marcuspollio]

FYI @chennes @Reqrefusion @kkremitzki regarding deployment times with new metrics.

For the exact same commit (316f9c4), Hugo version (0.160.0) and platform (linux/amd64)

The GitHub CI runner takes about 10 seconds for the full production site (including remote assets).

CI runner stats

hugo v0.160.0-652fc5acddf94e0501f778e196a8b630566b39ad linux/amd64 BuildDate=2026-04-04T13:32:34Z VendorInfo=gohugoio

WARN  Fetching remote resource: "https://unpkg.com/@sveltia/cms/dist/sveltia-cms.js"
WARN  Serving cached resource: "/Website/sveltia-cms_1757442759729611819.js"
WARN  "video" shortcode: video resource "video.mp4" not found on "/home/runner/work/Website/Website/content/en/dev/web/shortcodes/index.md:425:1"

           │  EN  │ ZH  │ ES  │ FR  │ PT  │ DE  │ JA  
───────────┼──────┼─────┼─────┼─────┼─────┼─────┼─────
 Pages     │  540 │ 538 │ 538 │ 538 │ 538 │ 538 │ 538 
 Paginator │  102 │ 102 │ 102 │ 102 │ 102 │ 102 │ 102 
 pages     │      │     │     │     │     │     │     
 Non-page  │  527 │   0 │   0 │   0 │   0 │   0 │   0 
 files     │      │     │     │     │     │     │     
 Static    │   14 │  14 │  14 │  14 │  14 │  14 │  14 
 files     │      │     │     │     │     │     │     
 Processed │ 1041 │   0 │   0 │   0 │   0 │   0 │   0 
 images    │      │     │     │     │     │     │     
 Aliases   │  122 │ 121 │ 121 │ 121 │ 121 │ 121 │ 121 
 Cleaned   │    0 │   0 │   0 │   0 │   0 │   0 │   0 

Total in 9539 ms

The FreeCAD server (container) takes about 40 seconds. I don't know their specs.

FreeCAD server stats

hugo v0.160.0-652fc5acddf94e0501f778e196a8b630566b39ad linux/amd64 BuildDate=2026-04-04T13:32:34Z VendorInfo=gohugoio

WARN  Fetching remote resource: "https://unpkg.com/@sveltia/cms/dist/sveltia-cms.js"
WARN  Serving cached resource: "/sveltia-cms_1757442759729611819.js"
WARN  "video" shortcode: video resource "video.mp4" not found on "/var/www/Website/content/en/dev/web/shortcodes/index.md:425:1"

           │  EN  │ ZH  │ ES  │ FR  │ PT  │ DE  │ JA  
───────────┼──────┼─────┼─────┼─────┼─────┼─────┼─────
 Pages     │  540 │ 538 │ 538 │ 538 │ 538 │ 538 │ 538 
 Paginator │  102 │ 102 │ 102 │ 102 │ 102 │ 102 │ 102 
 pages     │      │     │     │     │     │     │     
 Non-page  │  527 │   0 │   0 │   0 │   0 │   0 │   0 
 files     │      │     │     │     │     │     │     
 Static    │   14 │  14 │  14 │  14 │  14 │  14 │  14 
 files     │      │     │     │     │     │     │     
 Processed │ 1041 │   0 │   0 │   0 │   0 │   0 │   0 
 images    │      │     │     │     │     │     │     
 Aliases   │  122 │ 121 │ 121 │ 121 │ 121 │ 121 │ 121 
 Cleaned   │    0 │   0 │   0 │   0 │   0 │   0 │   0 

Total in 40634 ms

On my almost-potato laptop from 2017 with also linux/amd64, it takes about 7 seconds.

---

1. Is the time needed on the FreeCAD servers (i.e. about 40s) OK? I suspect there will be only a few staging and production deployments per day, so that should not be a major problem for now.

2. The build time may be multiplied in the future:

• Translations: currently 7 locales are enabled for the new website in the production environment. The current "homepage" website has 32 more-or-less translated locales, the wiki has 15 locales. So roughly 20-30 locales in the medium-term sounds plausible. With the current setup, all enabled languages have all the pages (with non-translated pages using the English content as fallback with a notice banner). We can change that to redirects if preferred, but this makes crossing sites locales, which is not the best UX.
• Content pages: currently the new website has ~500 pages per language. In a possible not-so-distant future, the wiki may be migrated to the same base (i.e. static site generator). The current wiki has about 2100 useful English pages. Maybe that can be lowered a bit with some cleanup, but that may be offset by documenting new stuff.
• Versioning: if and when the wiki is migrated, we will probably add support for documentation by release version (e.g. docs content for 1.1 is not the same as for 26.3). Luckily this is supported out-of-the-box by Hugo since a few versions (see dimension), but that also multiplies the number of pages for the largest section.
• Additional features like search index generation. Search is not implemented yet, but will be needed once the full documentation is on it. This step probably only takes a few seconds (i.e. to generate the JSON index), but that adds up as well.
• Note that the time needed to process resources (e.g. images) that are the same across dimensions (i.e. not localized nor versioned) is not multiplied linearly, as such resources are shared across site dimensions. This strategy also preventa the total filesize to grow linearly with additional dimensions (i.e. only additional HTML files are added, as resources are not duplicated).

3. Possible mitigations to growing build time (from my preferred to avoidable if possible):

• Optimize the theme and setup (see OP)
• Reduce or remove some compute-intensive features
• Provide redirects to missing content (e.g. language and version dimensions), instead of complete fallbacks
• Add some clever tricks to speed up things, at the expense of maintainability and flexibility

4. Filesize and Hugo performance are separate issues. For the latter, even more performance improvement seem to be planned from the Hugo team that may help with large sites. Also, there are way bigger sites (>10K pages per locale) out there with this same stack and open repos (e.g. Kubernetes, Bootstrap, etc), so we may benefit from their experience.

What do you think?
TIA

[chennes]

Obviously any improvement would be nice, but it is t like the site is actually offline for those 40 seconds, so as long as the server is still reasonably responsive it probably doesn't matter that much.

[marcuspollio]

Yeah, I do agree, this is not a big priority.
The reason for my previous message is to keep track of this aspect, as we now have new metrics for the staging environment. And also to keep that in mind as the website evolves.