I have a site with about 1k pages on it that has been using ref/relref shortcodes for links. I am investigating moving to the link render hook, which wasn’t around when I first started the site.
I rely on broken link detection for Markdown links using ref, so that [click here!]({{< ref "nonexistent-page" >}}) shows an error when trying to build the site. I see that the link render hook can emit errors too, which is nice. I’m starting with this page as recommended elsewhere on these forums.
However, sometimes I want to link to generated pages, including intentional links to
a page alias, e.g. for a shortened URL
the 404 page
the RSS feed
etc
These pages are not known to Hugo at build time, so they show errors when broken link detection is enabled.
Under my current system, where I use ref for regular pages almost all the time, I benefit from broken link detection during builds, and in the rare circumstance where I want to link to one of these generated pages, I use a regular Markdown link and have to remember to check it for brokenness myself. If I were to move to the link render hook instead, all my Markdown links emit an error if they are not real Hugo pages or assets.
I suppose I can convert the Markdown link to HTML links (<a href="/sitemap.xml">Sitemap</a>). This would work for me, although it does require setting markup.goldmark.renderer.unsafe to true. Is there a better way?
I had to deal with this issue a while back and we gave up, because GoHugo does a “too good" job knowing, that the page does not exist. But the way you could start your deep dive into this is GetPage, which returns either a page or an error:
{{ $p := page.GetPage $pathToCompareAgainst }}
{{ if $p }}
{{ printf "%s%s" $p.Permalink $hash }}
{{ else }}
{{ errorf "Page not found for ref: %s" $path }}
{{ end }}
$pathToCompareAgainst is the path to the content file that you had in your ref shortcode. The problem we were running into was, that this worked on a very old Hugo system (pre v0.80) and the refs were were forgiving, so after switching we encountered lots of issues with broken paths.
GetPage does not search for the page, just retrieves the page existing at the given path.
If you give up follow these steps:
replace all ref-shortcodes with markdown links (absolute links).
let a tool like Lychee run over the site to find all broken links.
you could always replace those now working links back to a shortcode with the now fixed content paths.
In the long term having all links in Markdown is much more portable, should you decide on a different site generator.
I am not sure if that is any useful for your case. Keep this post updated where you end up.