Hugo “link” helper methods

feature
1

There are a number of things being discussed in various bugs/pull requests about how to solve several problems, and I’d like to see what the preference for some of the options are. Basically, we have three problems:

  1. Cross-site document references. I can simulate this with my x shortcode, but it would be better if there were a helper mechanism. The x shortcode looks like {{% x ref="about" %}} and produces <a href="/about">About</a> if there is a page called about.md (or other template). I would rather be able to do [about me]({{ .RelRef "about" }}) or [about me]({{ .Ref "about" }}) and have it work with the content language I use rather than having to subvert it.

  2. In-document fragment references. This will be important because of the solution I’m going to propose for finally enabling automatically generating fragment references (e.g., #about-me) with Hugo and Markdown (using the blackfriday parser), because all heading IDs will be generated with the page unique ID appended (e.g., #about-me-0123456789abcdef0123). Rather than having to remember to write this as [heading](#heading-{{ .UniqueId }}), I would rather reuse something like .Ref or .RelRef (detect the use of a fragment and Do The Right Thing, such as [about me]({{ .RelRef 'about#current-job' }}) or [heading]({{ .RelRef '#heading' }})). Failing that, a .Fragment helper that does this would be useful. (I prefer the idea of having .RelRef and .Ref be smart enough to handle this, as it means that you can also do cross-document fragment references correctly.

  3. Asset references. This one is a bit harder, but it has to do with cache busting. This could be done with .Asset "path/to/file.css". This change would be a bit larger (as the copying of static assets would have to involve file renaming).

What do people think?

2 Likes
2

I think you’re Santa Claus, or something. :slight_smile: Let’s see if I can say something more than just +1 to everything.

1: that’s exactly what I was harping about elsewhere, and it’s awesome. :slight_smile: How would you work with the content language, that is, how would you make the parsers generate the right links?

Incidentally this approach would not help with my other goal of having inter-document links work on both GitHub and Hugo, but that’s probably an unattainable goal anyway, at least in any sort of robust way.

2: this is even better. :slight_smile: Being able to directly link to a section heading would be a great boon for documentation uses. I agree that having .Ref and .RelRef be smart about it would be better than a distinct .Fragment helper.

3: explicitly handling cache busting for assets would also be very good. Also yes, changing a version number of sorts in the filename or path would be more robust than just adding a query string.

Is it Christmas already?

3

+1 all over. :slight_smile:

4

This is an old thread. I think at least #1 and #2 are solved with cross-reference shortcodes. #3 is still an open issue.