Multi-product versioning

support
1

Currently running into issues of the native versioning supports one product. While this works well, in the case a single hugo site has multiple products with each having their own versions, it doesn’t seem to be supported without some post-build scripting to manipulate the output folder.

Looking deeper here - hugo/hugolib/site.go at master · gohugoio/hugo · GitHub - it looks like Hugo creates a full Cartesian product: every language × every version × every role. Instead, possibly it would be better to do a sparse matrix.

But core code aside, are there any tips to get around without having to change the core Hugo code?

2

Have you looked into taxonomies as a possible alternative to what you want to create? The language, version, role will create nnn sites, which is the nature of those domains. A “product” does not match into that setup.

3

Taxonomies aren’t a terrible idea, but they have a couple of shortcomings that make them fiddly for this use case.

You’d have to namespace the tag names like product-a/v2.0.0, to avoid semver collisions across product lines.

The URL shape would end up being something like

/version/product-a/v1.0.0/
/version/product-a/v2.0.0/
/version/product-b/v1.0.0/
/version/product-b/v1.1.0/

With the gotcha of unscoped versions, e.g. v1.0.0 in frontmatter generating pages like:

/version/v1.0.0     <--- orphaned

The real wrinkle with using taxonomies is that it does not have any structural binding to the actual content hierarchy. How do you build something like a version selector with this system? You might end up with adhoc directories like content/product/v1.0.0 that hold version-specific content. If you’re doing that, a series of mounts that shadow and override each other probably works better—if you’re willing to take on the config overhead as you add new content.

Maybe mounts?

This is what a mount-based config might like. The mount order is critical to get the desired shadowing behaviour:

[module]

# --- Product 17.1.0 → /product/17.1.0/docs/ ---
[[module.mounts]]
source = "versions/product/17/1/0/docs"
target = "content/product/17.1.0/docs"
[[module.mounts]]
source = "versions/product/17/1/_shared/docs"
target = "content/product/17.1.0/docs"
[[module.mounts]]
source = "versions/product/17/_shared/docs"
target = "content/product/17.1.0/docs"
[[module.mounts]]
source = "versions/product/_shared/docs"
target = "content/product/17.1.0/docs"

# --- Product 17.1.1 → /product/17.1.1/docs/ ---
[[module.mounts]]
source = "versions/product/17/1/1/docs"
target = "content/product/17.1.1/docs"
[[module.mounts]]
source = "versions/product/17/1/_shared/docs"
target = "content/product/17.1.1/docs"
[[module.mounts]]
source = "versions/product/17/_shared/docs"
target = "content/product/17.1.1/docs"
[[module.mounts]]
source = "versions/product/_shared/docs"
target = "content/product/17.1.1/docs"

# ... ad nauseum for every single product x semver documented

For this, you’d pretty much need to have an external validator to maintain coherence, but the resulting built URL structure is very clean.

Conclusion

Using taxonomies or mounts are both quite clever as solutions, but they’re both fragile because of all the scaffolding they need.

Ideally this product x version use case would be covered by the built-in versioning system. Another alternative is multiple site builds per product, which has its own nightmarish suite of compromises and complexities.