Relative links in a site with many versions

I’m creating a documentation site with multiple versions. For each new version I copy the content of “latest” into a new versioned directory “x.y.z”.


On the first copy the links stopped working

[prerequisites]({{< ref "prerequisites" >}}) 

with an error

[en] REF_NOT_FOUND: Ref "prerequisites": "": page reference "/latest/foo/prerequisites" is ambiguous

I’ve tried ref and relref and the result is the same. What steps can I do the debug or work around this issue?

Well, you are copying identical slugs around and of course they are “ambiguous” because “link1” in latest is the same as “link1” in 1.0.0.

I think I would try to do the ref-links as “1.0.0/prerequisites” and symlinking “latest” somehow to the highest number of revisions.

You might want to have a look at how Bootstrap does their documentation. They use Hugo and they have a versioned documentation… so somehow they got it running :wink:

Thank you for the input. Using full path refs works but is hard to maintain.

{{< ref "/1.0.0/foo/bar/baz/prerequisites" >}}

Bootstrap as far as I can tell seem to release their sites separately.

I found no real good solution. Seems like I must build these as separate sites to make it work.

What could probably help you is if you replace the ref shortcode usage with a render hook. That way you can apply some logic to the lookup.

I will give that spin, thank you for the inspiration @bep

1 Like