hugo: Fix anchor links

[JorindeUsMedia]

• Add example of anchor link using ref to the example/ref page (this is not
  mandatory to use this way but it can be used like this)
• Add working example to Example - Text on how to use custom-id's.
• Fix smoothscroll of anchor links that start with the path of the current
  page (instead of starting with #)
• Change markdownify to $.Page.RenderString so anchor links get rendered
  correctly (recommended by hugo for more complicated markdown which uses the
  Page context such as anchor links, see highlighted block on https://gohugo.io/functions/transform/markdownify/)
  . Only tabs still uses markdownify because for some reason RenderString does
  not work here because it's a partial inside a shortcode.
• Change links in example/columns to '/' instead of a non-existing anchor link

To test:
Go to /examples and test if all the shortcodes are still working as expected.

Closes cue-lang/cue#2971

[netlify]

👷 Deploy request for cue pending review.

Visit the deploys page to approve it

Name	Link
🔨 Latest commit	d58c3aa

[jpluscplusm]

@JorindeUsMedia I don't think this PR leaves us in a state where either cue-lang/cue#2971 is fixed; or where we understand what we have to do to avoid it; and where we have on-page examples of things working "correctly" to review and cross-check in the future.

cue-lang/cue#2971 is solely concerned with links to fragments on the same page, when placed inside columns or info/warning/caution blocks. If this issue is demonstrating a workaround for that problem, please can we place some examples on page that show it being fixed (with the use of relref?).

If this issue isn't demonstrating that, then I'm not sure of its purpose, and I don't think it should close cue-lang/cue#2971.

[jpluscplusm]

If I'm interpretting this change correctly, please add a note that same-page links to a fragment "must" be invoked via ref/relref, if they're to work consistently.

[jpluscplusm]

This example renders oddly, negating the point that I think you're trying to make (that relref must be used, and not just bare fragments inside a Markdown link):

[JorindeUsMedia]

@jpluscplusm It seems Hugo adds the baseUrl in front of all links: also anchor links.
See https://discourse.gohugo.io/t/link-with-anchor-has-leading-slash/30391
They suggest to use relref instead. I did some more googling but could not find a solution for hugo/goldmark not adding the baseUrl to anchor links.

[JorindeUsMedia]

@jpluscplusm what do I need to do in order to get this pr closed? Mention that is must be used on the examples page?

[jpluscplusm]

@jpluscplusm what do I need to do in order to get this pr closed? Mention that is must be used on the examples page?

I think an explicit mention on the example page that linking to an anchor on the same page requires relref, with an example of it being used successfully inside the set of shortcodes that are mentioned in the linked issue: columns and info, at a minimum.

[JorindeUsMedia]

Hm it seems even with using ref instead of regular links there still seems to be an issue with Hugo (or Goldmark) adding the baseUrl in front of the anchor links when used inside of shortcodes.. I'll have to dive into the issue again.

[JorindeUsMedia]

I think I found it:

https://gohugo.io/functions/transform/markdownify/ >

Although the markdownify function honors Markdown render hooks when rendering Markdown to HTML, use the RenderString method instead of markdownify if a render hook accesses .Page context. See issue #9692 for details.

gohugoio/hugo#9692

I think we need to use

{{- $.Page.RenderString .Inner -}}
instead of

{{- .Inner | markdownify -}}

I will check in which components we use markdownify and change it. I will create a new pr for that

[jpluscplusm]

Hey @JorindeUsMedia - I've just hit this issue when trying to link to a same-page fragment from inside a caution block. Is there a workaround that works with the current site, other than hardcoding a link to the absolute path of the current page?

[JorindeUsMedia]

Hey @JorindeUsMedia - I've just hit this issue when trying to link to a same-page fragment from inside a caution block. Is there a workaround that works with the current site, other than hardcoding a link to the absolute path of the current page?

I've found a solution: see my last comment. I also implemented it but didn't have time to test it yet. I've just updated the pr

[jpluscplusm]

I can see changes to several different elements that we use throughout the site.

I'm just writing this as a marker that I've seen this PR, but need to find a bit of time to sit down and compare some before-and-after uses of the elements that have been updated :-)

[jpluscplusm]

I've started CI manually, here, as a change we made recently has made the Netlify preview bot unhappy. This is a just a temporary work around until we fix the bot.

[jpluscplusm]

Looks generally good - just a few questions/etc.

I'd like to grab a brief chat to understand the core of what's changing here, so that I can make sure we're marking up anchor links correctly.

[jpluscplusm]

Preview available at https://cl-1203530-2--cue-cls.netlify.app/.

@JorindeUsMedia I've resolved all the threads I feel able to - please could you resolve the rest, and then I'll know it's good for final review? Thank you!

[JorindeUsMedia]

@JorindeUsMedia I've resolved all the threads I feel able to - please could you resolve the rest, and then I'll know it's good for final review? Thank you!

All resolved :)

[jpluscplusm]

LGTM!

[jpluscplusm]

Imported as https://cuelang.org/cl/1203530.