Relative links in a site with many versions

support
1

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”.

content/latest
content/1.0.0

On the first copy the links stopped working

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

with an error

[en] REF_NOT_FOUND: Ref "prerequisites": "page.md": 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?

2

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:

3

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.

4

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

5

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.

6

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

1 Like