Version-agnostic page/section references

support
1

We create a hyperlink to another page in the doc portal with a reference like this:
<a href=“{{< ref “v1-abcd-additional-options-in-cloud-accounts-screen#section-adjusting-the-cloud-account-scan-schedule” >}}”>Adjusting the cloud account scan schedule

The part “#section-adjusting-the-cloud-account-scan-schedule” is an optional section reference (anchor); it can be omitted.

Finally, there are on-page references to a different section on the same page that can omit the first part, like this:
see <a href=" {{< ref “#section-cloud-account-providers” >}}">Cloud account providers below

Here’s the problem. In a reference to another page, the doc version number must be included. It could be “v1-”, “v2-”, etc. This reduces document reusability.

Which Hugo code processes these references, and how can I change it to do the following:

  • If there’s no version reference included, then use the version of the current markdown page.
  • Otherwise, use the version reference that’s included.

Thanks!

2

i did not get the exact way how you organize your versions and templating…

but here’s the part on ref:

The ref and relref Shortcodes are described here Ref Shortcode

you may implement your own by overwriting the shortcode locally (also described there)

  • if your page for example has a frontmatter parameter version
    you could check if the argument to ref your version prefix and if not add that from frontmatter using the $.Page.Params.version inside the shortcode.
  • if it’s only in the filename
    you could get the logical path or slug using $.Page.Path or $.Page.Slug

hint:
your snippet looks like you are including links using HTML code in your markdown.
maybe switching to standard markdown links [TEXT](link) and a link-render-hook would be an option

3

I have not read you entire post, but

  1. If this is is Markdown, if would recommend creatint a link render hook
  2. If not, I would recommend creting a custom shortcode/partial

Whatever the case above, use site.GetPage and/or .Page.GetPage.

This way you can do (pseudo code)

{{ $path := .Get 0 }}
{{ $p := or (site.GetPage $path) (.Page.GetPage $path) }}
{{ if not $p }} 
  {{ if strings.HasPrefix $path "v1" }}
    // do something
   {{ end }}

{{ end }}

Note that the template code is just sketched out as an example, main point is that having one template like the above makes it easy to “look in different places” until you find the page.