Hugo: Add markdown template hooks for links and images

[bep]

This is the number one pain point left vs rendering of content files, and I will do a fast implementation for this for Hugo 0.61.**

Common issues that are currently very hard/impossible to do:

• Adding attributes/classes to links, e.g. target=_blank on external links.
• Resolve links using .GetPage
• Resolve and resize images
• Collecting all images/links in a content file.
• ...

We may do improved (and faster) plugin interfaces for this (re. Starlight discussion in another thread), but what I suggest we do very short term is outlined in the below:

layouts
├── _markup
│   ├── render-link.html
│   └── render-image.html
└── index.html

• So render-link and render-image are predefined hook macros that will be responsible for producing the markup for links and img tags.
• They will receive a context with the current page, output format (which I will add to the page), and information about the link/image.
• The template lookup will follow the same rules as other templates vs. output format and language etc, templates in the project will override any in the theme(s), if no found we will use the default behaviour.

/cc @regisphilibert @onedrawingperday @kaushalmodi and gang.

** I know people are waiting "Pages for data", and it's in the pipeline. I have a branch where I'm working on it, so it's coming ... eventually.

[onedrawingperday]

Yes please. Pretty please with sugar on top!

This is a feature that I really-really want...

Having the ability to control markdown syntax images from the templates will make content editing in Hugo much more intuitive and portable.

Just closed #6505 in favor of this issue.

[HenrySkup]

Very great! Currently i'm doing this by pre-regexing .Content before markdownify ...

Might be helpful to have some custom syntax interface? (so that we aren't limited to just ahref / img / or other pre-backed ones?)

[regisphilibert]

Very exciting indeed.

Would this be limited to the .Content renderer, or also applied when using the markdownify function?

[bep]

Would this be limited to the .Content renderer, or also applied when using the markdownify function?

I was thinking about .Content. For this to work with markdownify we need to add Page.Markdownify (which I guess is described in another issue) -- because we need a page context.

[regisphilibert]

This one https://github.com/gohugoio/hugo/issues/5976 and this one https://github.com/gohugoio/hugo/issues/6094 thought the latter won't be needed after once #5976 is implemented.

[bep]

because we need a page context.

I guess we strictly don't must have it, but it would be nice. We could and probably should make it optional, so you need to do

{{ with .Page }}
{{ else }}
{{ end }}

[regisphilibert]

I guess we strictly don't must have it, but it would be nice. We could and probably should make it optional, so you need to do

I agree.
This would not break too many people's code, as people would have to start using shortcode in markdownifyed string for this to break without a proper with clause.

[regisphilibert]

As for naming, I think we should stay away from HTML tags so 👍 for link.html but not for img.html. I'd suggest

├── _markup
│   ├── render-link.html
│   └── render-image.html
└── index.html

[bep]

link.html but not for img.html. I'd suggest

I agree with the link vs href, but render-image might be misleading ... But I guess it's fine.

[regisphilibert]

Also, the dir is being called markup, this could expand to rendering from something else than markdown?

[davidsneighbour]

I wonder if anywhere the - in render-image might bring issues and an underscore like render_image would fit more? But that's just because of my bad experiences in other templating systems where the - might be interpreted mathematically.

[regisphilibert]

I agree with the link vs href, but render-image might be misleading ... But I guess it's fine.

Ideally there is an agreed upon list somewhere of markdown "function/feature" names we could use when expanding this to more than images and links. But not sure where to look...

[sephore]

I can see this feature being used to generate a sitemap file with images...

[bep]

My first very rough implementation of this tells me that this is a great idea.

[bep]

While implementing the template lookup logic I have revised my directory structure. I think it would be really useful to respect type/section, and then I think it would make sense to have the templates logically grouped together by type/section (it's kind of a template tree single.html => render-link.html), so they can be edited together.

layouts
├── _default
│   ├── _markup
│   │   ├── render-image.html
│   │   ├── render-image.rss.xml
│   │   └── render-link.html
│   └── single.html
├── blog
│   └── _markup
│       └── render-image.html
└── index.html

We may add support for layout later, but I want to see how the above works first.

/cc @regisphilibert

[regisphilibert]

I agree 100%. Images and Links' markup should be customizable depending on sections.

[bep]

There is a relevant discussion over here: https://github.com/yuin/goldmark/issues/53#issuecomment-562481571

I have been thinking about this, and I still think my proposed (and implemented) solution for this is the pragmatic correct choice at the moment. We may improve.

[regisphilibert]

I'm having second thoughts about the UX side of this. Wouldn't it make more sense to align this new "API" with the Shortcode "API". A new directory underneath layouts to store those "renderer".

├── shortcodes
├── markup
     ├──    link.html
     └─── image.html
└── index.html

And have those template files use the same interface as shortcodes (.Get "alt, .Get "src") etc...

Yes they would not benefit from the "type" template lookup but neigher are shortcodes and people seem to accommodate. I for one just test the .Page.Type and build the corresponding output.

[bep]

I'm not sure about moving the markup. It gets ambiguous (for people having sections by that name) if we add one more folder to the top. And it's implemented ...

The .Get syntax you need to explain. Note that this is something very much different than shortcodes. The API is not something the user can control.

[bep]

I think I will hold off on the "type resolution" until we know how this works, but keep them below _default/_markup. They do relate to the content templates, and I would hate to add more top level folders (let's say that partials/shortcodes is something special).

[jakejarvis]

@bep this is awesome! Playing with it now and have a quick question though, not sure if this is a full bug/regression – if so I can repost. I have links where the inner text includes code styling (via markdown, single tildes) but .Text in render-link.html returns plaintext like so:

<a href="{{ .Destination | safeURL }}" target="_blank" rel="noopener">{{ .Text }}</a>

[`should be code`](https://gohugo.io)

...returns <a href....>should be code</a> instead of <a href....><code>should be code</code></a> as before.

Same with bold text ([**asdf**](#)) and other markdown styling. I've tried {{ .Text | markdownify }} as well with the same result. Am I missing something?

This is still a HUGE feature for me though, especially with images, so thanks!!! 👍

[bep]

@jakejarvis can you create a separate issue. This may be related to a similar issue we fixed in the ToC extension earlier.

[onedrawingperday]

@bep

I have already tested the new functionality and I also think that this is such an amazing update that will simplify my workflow a lot. Now every Markdown editor out there can be used as a CMS for Hugo, even on mobile.

Thank you so much! 🥇

[bep]

Yes, it's pretty great.

[inwardmovement]

Awesome!
Would it make sense to have a render-anchors.html to be able to customize anchors generated via .TableOfContents? > using anchorize.

This would allow to bypass Goldmark's stripping non Unicode characters from anchors (6616) without the need of an extension, but maybe an extension would make more sense I don't know (I guess an extension would indeed feel more "native" than a custom template).

[deanishe]

How is render-image.rss.xml supposed to work? It's name-checked, but not described in the docs.

I've created both render-image.html and render-image.rss.xml templates, but render-image.html is being used for RSS feed content, not render-image.rss.xml.

[ibnujakaria]

Hey I have problem with amp output format.

I have two files like this:

├── _markup
│   ├── render-image.html
│   └── render-image.amp.html
└── index.html

The one should be used is render-image.amp.html for amp pages but its never used.

[soneji]

Hi
Could somebody please explain how to use this feature. I am struggling trying to get images to load properly in both hugo and markdown

[bep]

Please use https://discourse.gohugo.io/ for questions/troubleshooting. Also see Hugo Documentation.

[deanishe]

Also see Hugo Documentation.

The documentation is inadequate.

[soneji]

Hey guys

I hope we can keep a positive attitude here :)

I think I managed to solve my problem by looking at this page here

If I create the file render-image.html like below, in the root of my hugo project

└── _default
    └── _markup
        └── render-image.html

The documentation says to put this in the file:

<p class="md__image">
  <img src="{{ .Destination | safeURL }}" alt="{{ .Text }}" {{ with .Title}} title="{{ . }}"{{ end }} />
</p>

I changed the line to:

<p class="md__image">
  <img src="../{{ .Destination | safeURL }}" alt="{{ .Text }}" {{ with .Title}} title="{{ . }}"{{ end }} />
</p>

and it let me put my images in content/posts/images.
I reference them in my markdown with images/image.jpg

[bep]

Please use https://discourse.gohugo.io/ for questions/troubleshooting. Also see Hugo Documentation.