Is there an example of how to use the new multidimensional content model?

[Travis_Beckham]

I maintain a few documentation sites and have to deal with multiple versions of docs, and was looking forward to the new multidimensional content model. I’ve read through the updated documentation on sites matrix and the new Rotate method, but I don’t quite understand how the content and templates should be set up. I probably have the wrong idea in my head on how this is suppose to work. Does anyone know if there’s a demo repo available that shows how to use versions, and demonstrates the power the new model provides?

[nekr0z]

I would also very much like to see an example demonstrating how to use sites.complements. The documentation says it can be used “to fill in the Swedish pages where pages for Norway are missing” or something of that sort, which is exactly what I’ve been doing for years now using all kinds of weird techniques. I would very much like to give the new approach a try, but I can’t wrap my head around it.

[bep]

I didn’t want to drag that feature unreleased into a new year, which is why I pushed the release right before Christmas. There’s a ton of integration tests, so I’m confident that it works, but you’re right, I don’t know about any great examples.

I will put on my TODO list to create a basic demo site that at least shows the versions and languages at play. @nekr0z you are right, this is is a head twister if you just look at the current documentation – but I think it gets much easier with some examples. Stay tuned.

[jmooring]

This needs some adjusting (consider it a work in progress), but it’s a starting point…

This is an example of the multidimensional content model introduced in Hugo v0.153.0. This framework enables content to be organized across multiple languages, roles, and versions simultaneously. For this specific example, we are focusing on the version dimension to demonstrate a software documentation site where pages are added, modified, or removed with each release.

v0.1.0

• Added /docs/functions/average
• Added /docs/functions/mean

v0.2.0

• Added /docs/functions/variance
• Modified /docs/functions/mean

v0.3.0

• Added /docs/functions/standard-deviation
• Modified /docs/functions/variance
• Removed /docs/functions/average

v0.4.0 (defaultContentVersion)

• Added /docs/functions/median

Expected result when viewing the v0.4.0 site:

• /docs/function/mean from v0.2.0
• /docs/functions/standard-deviation from v0.3.0
• /docs/functions/variance from v0.3.0
• /docs/functions/median from v0.4.0

Try it:

git clone --single-branch -b hugo-forum-topic-56516 https://github.com/jmooring/hugo-testing hugo-forum-topic-56516
cd hugo-forum-topic-56516
hugo server

Notes:

• Hugo does not create an alias in the root of the public directory that points to the defaultContentVersion. I need to figure out how to handle that. For now, visit http://localhost:1313/v0.4.0/.
• This doesn’t use module.mounts.sites.complements. I’m not sure how that should be configured for this example. Consequently, the desired inheritance isn’t working as desired.

[bep]

@jmooring

Hugo does not create an alias in the root of the public directory that points to the defaultContentVersion. I need to figure out how to handle that. For now, visit http://localhost:1313/v0.4.0/.

That’s a detail i missed in the original implementation, I will fix that reasonably fast:

Redirects should point to default {language,version,role}

As to “the desired inheritance isn’t working as desired”, let me know some more. I’m pretty sure it works on the technical level, but maybe it need to improved on the … practical level.

[nekr0z]

Wow, impressive, thank you!
(I’m even more confused about sites complements now, though ;).

[jmooring]

@nekr0z

Wow, impressive, thank you!

Well, it will be when the published site matches the “expected result” as documented in my initial post.

@bep

let me know some more

I’ve add an “expected result” list to my initial post. The actual result doesn’t match, so either my expectations are wrong or I’m doing it wrong… I suspect the latter because I don’t understand (and am not using) module.mounts.sites.complements. It would be helpful if you could look at site config.

[bep]

See Investigate the sites matrix file mount merge logic · Issue #14357 · gohugoio/hugo · GitHub

The file mount merge result looks fishy in your example, and I guess that is the main workflow for the “versions use case” (e.g. mount different GitHub branches). I’m a little surprised by this, though, but thanks testing this.

[bep]

@nekr0z

(I’m even more confused about sites complements now, though ;).

• sites.complements is probably not relevant for versions, possibly for some language use cases.

• conceptually it’s working the same as the lang.Merge func, but this is an auto merge into all. of Hugo’s page collections (e.g. site.RegularPags)

• The main use case I had in mind, though, was for membership sites using the role dimension. The member site would complement guest site with content, the guest site would list it with a title and summary (and a + sign or something to mark that it needs a membership), but it would link to e.g. /member/a-cool-article, which would trigger authentication/subscription*

• The authentication part would need to live outside of Hugo, but is much much simpler and cheaper than doing the entire thing on a server.

[nekr0z]

Perhaps, my mental model lacks some important elements. Take this sample repo: from what I read in documentation, as well as your explanations, I’d expect /public/de/posts/index.html in the rendered site to have links to two pages, one in English and one in German, based on what’s in /content/posts/_index.de.md, but that isn’t the case.

[bep]

@jmooring see this branch for a way to reconfigure your site to make it work, also with some links to some context: Rework the mounts · bep/hugo-testing@434a9dd · GitHub

[jmooring]

@bep

reconfigure your site to make it work

Well, that was easy. Thanks. With v0.154.4 this works as expected:

git clone --single-branch -b hugo-forum-topic-56516 https://github.com/jmooring/hugo-testing hugo-forum-topic-56516
cd hugo-forum-topic-56516
hugo server

[Travis_Beckham]

Thanks for the demo! This helped so much.

[jmooring]

Thanks. At some point I’ll add another content dimension (language) to this.

[chalin]

I finally got the OTel multilingual site with en fallback working with the sites.matrix . In case you’d like to see the config changes, here’s the PR:

• chore(hugo-config): refactor language mounts to use matrix sites config by chalin · Pull Request #9070 · open-telemetry/opentelemetry.io · GitHub

A note about the OTel.io site design: each non-en site is complete in itself. Locale users never have to leave their (locale) site. English pages have a banner atop that say something like “This page hasn’t been translated yet, want to help?” So I don’t use complements but rather map the en pages as backup locale pages. Hopefully this might be a useful example to some.

I do have some use cases for complements and version, which I’ll hopefully get to try soon. Thanks all!

p.s. The base config is in config/_default/hugo.yaml

[Tom_Durand]

I’ll wait until it’s been ironed out and most importantly the documentation fully fleshed out, because this is complex enough that just tinkering with the content tree won’t do it to intuitively grasp it. But as long as using plain ol’ language extensions still works and page sorting works, it doesn’t bother other users.