Hm.. right, so the downside of this is that the MarkDown is now fully depending on Hugo to be rendered correctly, which quite limits how it can be read on GitHub, e.g. links in this block are no longer "valid" GFM, and no longer rendered as links;

Which is why I was considering if there's other ways to make it work (as I commented in #4238 (comment))

I'm not sure if that's possible though. I do recall we faced similar challenges long time ago when the original Docker documentation also used Hugo, and where we encountered some corner-cases (ISTR those were mostly related to _index.md files, which needed special handling that was missing in Hugo); a Docker maintainer at that time contributed some changes to Hugo to make that work (but I know some of that broke later, and was removed, so not sure what's still there);

• Githublink helper gohugoio/hugo#1398

Now, admitted, reading these docs (AND navigating them) on GitHub may be a "nice to have" if we consider the rendered docs to be the canonical place to read, but it is somewhat in line of expectation for these to be GitHub flavoured markdown; contributors and maintainers will be way more familiar with "regular" links, in addition to IDEs / editors that will assist (and validate) links with the assumption.

So if possible it would be great if that would work and if we could use regular / relative links to the .md files that work both in Hugo and in other settings.

(We should definitely consider having a link-checker in CI though, as these links currently being "silently" broken isn't great.)

@dvdksn @milosgajdos any thoughts?

Additional note- I'd suggested looking into https://gohugo.io/content-management/urls/#relative-urls as something of a flagrant hack to try and avoid the manual relpathing or ref tag usage. That won't fix the issue here, although you may want to consider it if you're doing something like shipping a copy of the docs with the distribution package.

I think we could add a render hook for links that ensures we can write links that are compatible with both Hugo and GitHub. Something like:

layouts/_default/_markup/render-link.html

{{- if (strings.HasPrefix .Destination "http") -}}
  <a href="{{ safe.URL .Destination }}" target="_blank">{{ safe.HTML .Text }}</a>
{{- else if (strings.HasSuffix .Destination ".md") -}}
  <a href="{{ ref .Page .Destination | safe.URL }}">{{ safe.HTML .Text }}</a>
{{- else -}}
  <a href="{{ safe.URL .Destination }}">{{ safe.HTML .Text }}</a>
{{- end -}}

My ideal solution would be:

• make sure GH links remain navigable using GH UI
• when deploying the links we should somehow "override" them during the build so they work in Hugo

Now, I'm not a hug expert unfortunately so I don't know how easy it'd be to do, but what @dvdksn describes in his last comment seeeems interesting?

Pushed an alternative solution in #4247