Allow markdown inside of figcaptions

[LunkRat]

Great plugin! I notice that markdown is not processed inside of the figure caption.

Example:

![**Figure 1** Markdown here is not processed by the plugin.](/images/figure1.jpg)

Produces the output:

<figure class="figure-image">
<img src="/images/figure1.jpg" alt="**Figure 1** Markdown here is not processed by the plugin."
<figcaption>**Figure 1** Markdown here is not processed by the plugin.</figcaption>
</figure>

Would be great to be able to format the text inside of the caption.

[fstueber]

That's not so easy to implement since you must distinguish between Alt-Tag (plain text) and figcaption (html text).

[timvink]

Actually it might not be that hard, if you first save both capture groups 1 and 2 as variables.

https://github.com/stuebersystems/mkdocs-img2fig-plugin/blob/c618bce2dfed9a0e279dfdd5ad6930723e3fb157/src/plugin.py#L14-L16

From capture group 1 you can create a third version where you generate the html using markdown:

import markdown
md = markdown.Markdown()
md.convert("**yes**").replace("<p>","").replace("</p>","")
# <strong>yes</strong>

Happy to provide a MR if want me to implement it

[fstueber]

Thanks, I am always open for a push request :-)

[timvink]

I started on this, but there are some tricky edge cases, like users adding links within the caption text. Here are some examples where you can when current regex works and when it doesn't:

https://regex101.com/r/lmlVsJ/1/

@fstueber How's your regex Kung Fu? Able to solve this one?

Looking at the example, it seems the actual problem is enumerating tables. After learning about the img2fig-plugin I plan to add this functionality to enumerate-headings-plugin (see https://github.com/timvink/mkdocs-enumerate-headings-plugin/issues/20), and making the figure number bold should be doable.

Perhaps that is already sufficient?

[timvink]

This is an interesting problem and I thought about it some more. This post has an excellent discussion on adding caption support for markdown.

They argue that any caption solutions break the markdown syntax and might also affect portability because you need a specific markdown processor.

That still leaves the problem that you would like to include a richer, formatted caption to an image. They recommend using

![Amazon Rainforest](/path/to/image)

<span class="caption">The [Amazon Rainforest](https://en.wikipedia.org/wiki/Amazon_rainforest) contains a multitude of species and is vital to the Earth's survival.</span>

or

![Amazon Rainforest](/path/to/image)

<figcaption>The <a href="https://en.wikipedia.org/wiki/Amazon_rainforest">Amazon Rainforest</a> contains a multitude of species and is vital to the Earth's survival.</figcaption>

But (with this plugin disabled) both options don't result in a nice caption in mkdocs (both base theme and material theme), probably because they aren't wrapped in <figure> tags:

Drawing from ideas in the article, we could introduce our own single-line syntax (that we can easily parse) that allows to append an optional caption to a figure markdown definition, like:

![Amazon Rainforest](/path/to/image){{< caption >}}The [Amazon Rainforest](https://en.wikipedia.org/wiki/Amazon_rainforest) contains a multitude of species and is vital to the Earth's survival.{{< /caption >}}

But then again:

For any markup that is not covered by Markdown’s syntax, you simply use HTML itself. ~John Gruber daringfireball.net

So in conclusion, I'm inclined to think the best thing would be to recommend users in the README.md of this plugin to use HTML directly if they need more control over formatting options, with an example

<figure class="figure-image">
  <img src="\assets\images\my-image.png" alt="An image caption">
  <figcaption><b>Figure 1</b>: An image caption with <a href="#">link</a></figcaption>
</figure>

[fstueber]

Thank you for your investigation. I will close this issue.