Render Markdown in figure (shortcode) captions

[kaushalmodi]

Hello,

It is often a necessity to allow emphasis in figure captions, especially for technical blogs, where you would use `code` markup for referring to file names, commands, etc.

Here is a test Markdown content file where I have such caption: image-captions-with-markdown.md.

{{< figure src="/images/magit-log-buffer-file.png" caption="Log buffer for `gohugoio/hugo/tpl/tplimpl/template_embedded.go` created by **Magit** on doing `M-x magit-log-buffer-file`" >}}

But Hugo does not render the Markdown in captions, and so they show up like this:

Hugo generated page

I get the exact same behavior whether I use {{< figure .. >}} or {{% figure .. %}}.

Proposal 1

Here was my Proposal 1.

Note that that change did not fail any existing test.

Proposal 2

• Within a shortcode, is there a boolean function that can tell if {{< .. >}} or {{% .. %}} was used? If so, we can do what I did in Proposal 1, but only if {{% figure .. %}} style shortcode is used.

[bep]

This is a breaking change on a couple of levels (statistically speaking). I don't mind breaking stuff if it is really important. This isn't, and there is also a workaround (create a local version of the shortcode).

We have to revisit this in the future (add image Resouce support etc.), but before breaking stuff, I think we have to figure out a better design for those internal shortcodes (pull them out into some external bundle, versioning etc.)

[kaushalmodi]

This is a breaking change on a couple of levels (statistically speaking).

What kind of breakage do you expect?

Using the customized figure shortcode I proposed, and the caption as:

{{< figure src="/images/magit-log-buffer-file.png" caption="this asterisk * shows up fine _ this underscore too, but **bold** and _italics_ still work fine" >}}

I get:

I have the whole caption in italics, so the italicized part doesn't stand out.

There will still be subtle breakages if people have the stray ` character mixed with something like `code` in the caption for some reason (when Markdown parsing is not even expected right now!).

But I don't see this as a widely breaking change.

---

think we have to figure out a better design for those internal shortcodes (pull them out into some external bundle, versioning etc.)

I agree.

[kaushalmodi]

Another case where this proposal will be useful: https://discourse.gohugo.io/t/html-in-shortcode-attribute-breaks-shortcode/11027

[stale]

This issue has been automatically marked as stale because it has not had recent activity. The resources of the Hugo team are limited, and so we are asking for your help.
If this is a bug and you can still reproduce this error on the master branch, please reply with all of the information you have about it in order to keep the issue open.
If this is a feature request, and you feel that it is still relevant and valuable, please tell us why.
This issue will automatically be closed in the near future if no further activity occurs. Thank you for all your contributions.

[kaushalmodi]

@bep Can you please give another thought to this? Is this really that of a breaking change?

Most people don't care of using Markdown in captions. So this change won't affect them in any way. On the other hand, this change will be a welcome change for folks wanting to use markup in captions.. and HTML allows <b>, <i>, etc tags inside figure captions.

[kaushalmodi]

@bep Thanks for re-opening this. Should I start working on a PR for the figure shortcode that basically runs markdownify over the caption and attr parameters?

(Basically same as the older PR https://github.com/gohugoio/hugo/pull/4405/files#diff-33eb7415b0f69c81e6da0d26eadeea41, but re-done in the new shortcode file location.)

[kaushalmodi]

@bep Would you accept the PR for this.. awaiting your reply to the previous question. (This PR will enable Org mode/ox-hugo users have the figure captions rendered the right way, and I have heard of this request quite a few times.).

While a custom figure shortcode can fix this, it would be nice to have Hugo do the right thing so that I don't have to ask everyone to use my custom shortcode just for this. HTML allows tags in captions, so Hugo should insert style tags corresponding to Markdown format too. I don't see this much of a breaking change.

[bep]

@bep Would you accept the PR for this..

Yes.

[kaushalmodi]

@bep

I am trying to test the change locally.. after go1.11, the old go test -v ./... does not work any more. I get:

resource/resource_cache.go:27:2: cannot find package "github.com/BurntSushi/locker" in any of:
        /home/kmodi/go/src/github.com/BurntSushi/locker (from $GOROOT)
        /home/kmodi/go.apps/src/github.com/BurntSushi/locker (from $GOPATH)
commands/commandeer.go:32:2: cannot find package "github.com/bep/debounce" in any of:
        /home/kmodi/go/src/github.com/bep/debounce (from $GOROOT)
        /home/kmodi/go.apps/src/github.com/bep/debounce (from $GOPATH)
resource/tocss/scss/client.go:17:2: cannot find package "github.com/bep/go-tocss/scss" in any of:
        /home/kmodi/go/src/github.com/bep/go-tocss/scss (from $GOROOT)
        /home/kmodi/go.apps/src/github.com/bep/go-tocss/scss (from $GOPATH)
resource/image.go:29:2: cannot find package "github.com/disintegration/imaging" in any of:
        /home/kmodi/go/src/github.com/disintegration/imaging (from $GOROOT)
        /home/kmodi/go.apps/src/github.com/disintegration/imaging (from $GOPATH)
resource/resource.go:39:2: cannot find package "github.com/gobwas/glob" in any of:
        /home/kmodi/go/src/github.com/gobwas/glob (from $GOROOT)
        /home/kmodi/go.apps/src/github.com/gobwas/glob (from $GOPATH)
helpers/general.go:34:2: cannot find package "github.com/jdkato/prose/transform" in any of:
        /home/kmodi/go/src/github.com/jdkato/prose/transform (from $GOROOT)
        /home/kmodi/go.apps/src/github.com/jdkato/prose/transform (from $GOPATH)
tpl/inflect/inflect.go:19:2: cannot find package "github.com/markbates/inflect" in any of:
        /home/kmodi/go/src/github.com/markbates/inflect (from $GOROOT)
        /home/kmodi/go.apps/src/github.com/markbates/inflect (from $GOPATH)
resource/transform.go:26:2: cannot find package "github.com/mitchellh/hashstructure" in any of:
        /home/kmodi/go/src/github.com/mitchellh/hashstructure (from $GOROOT)
        /home/kmodi/go.apps/src/github.com/mitchellh/hashstructure (from $GOPATH)

mage check fails too:

go: downloading github.com/alecthomas/repr v0.0.0-20180818092828-117648cd9897
go: downloading github.com/davecgh/go-spew v1.1.1
Error: running "go test ./..." failed with exit code 1

Can you please help me with this? How do you run tests locally?

[kaushalmodi]

ah.. commented that too soon.. need to set GO111MODULE to on first. Then go test -v ./... works.

[kaushalmodi]

@bep PR submitted and it passes all the tests. Please review. Thanks!

[github-actions]

This issue has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs.