Add option to ignore converting certain figures

[timvink]

I have a feature request.

I would like the option to specify that some images in my page should not be converted to figures.

For example:

[![Actions Status](https://github.com/timvink/mkdocs-print-site-plugin/workflows/pytest/badge.svg)](https://github.com/timvink/mkdocs-print-site-plugin/actions)
![PyPI - Python Version](https://img.shields.io/pypi/pyversions/mkdocs-print-site-plugin)
![PyPI](https://img.shields.io/pypi/v/mkdocs-print-site-plugin)
![PyPI - Downloads](https://img.shields.io/pypi/dm/mkdocs-print-site-plugin)
[![codecov](https://codecov.io/gh/timvink/mkdocs-print-site-plugin/branch/master/graph/badge.svg)](https://codecov.io/gh/timvink/mkdocs-print-site-plugin)
![GitHub contributors](https://img.shields.io/github/contributors/timvink/mkdocs-print-site-plugin)
![PyPI - License](https://img.shields.io/pypi/l/mkdocs-print-site-plugin)

Should render as:

But renders as:

Proposal

I would suggest two updates:

• If an image does not contain a caption (f.e. ![](<path>)), do not convert
• If an image caption contains the words img2fig-ignore, remove the text from the caption and do not convert to figure

[fstueber]

Hi Tim, makes sense. I would propose following solution:

• Images without captions (e.g. ![](https://example.com/img.png)) should be converted (but without rendering the <figcaption> tag). At least I have a use case for this.
• Images with img2fig-ignore as url param (e.g. ![caption](https://example.com/img.png?img2fig-ignore)) are not converted

What do you think?

[fstueber]

One more: We can control whether images without captions are converted or not via plugin config.

[fstueber]

While thinking more about this plugin I would propose a complete different approach:

• The default syntax ![caption](url "title") should produce the img tag like before. If we want to have a different behavior we should add something instead of trying to ignore the new behaviour for getting the default behaviour.

• A new syntax should be introduced which is compatible with default syntax highlighting.

• Proposal: ![f:caption](url "title") renders an markdown image as <figure>. Syntax is discussable, but with this approach you can safly introduce this plugin to an existing MkDocs project without breaking anything.

• Of course this is a breaking change for projects using this plugin already. Maybe a legacy mode could help.

[timvink]

Good idea, much cleaner!

I would prefer a more explicit syntax, f.e.: ![caption:<your text>](url). Adding a caption: prefix to your markdown images alttext is a syntax that should be easy to memorize for users.

While we're brainstorming, I also think the figure captions are rendered too big, and the whitespace underneath is too narrow. I think it would be a good idea to update the docs with some custom CSS styles for the mkdocs and material themes, and show users how to add those snippets via the extra_css parameter.

[timvink]

So I also thought about this a bit more.

What this plugin is doing is actually just extending the markdown syntax while parsing to HTML. So instead of being a mkdocs plugin, it could be a markdown extension (which you can also install via pip and use in your mkdocs.yml, see https://www.mkdocs.org/user-guide/configuration/#markdown_extensions)

When you install mkdocs-material, the excellent facelessuser/pymdown-extensions is also installed, which contains many extensions to markdown.

@facelessuser have you ever considered the use case of adding an extension to automatically create HTML figcaptions from markdown? Would that fit the scope of pymdown-extensions? Any ideas/advice?

EDIT:

OK there are already lots of markdown extensions that do this. see https://github.com/Python-Markdown/markdown/wiki/Third-Party-Extensions#generic--structure. The syntax most commonly used is with the title attribute:

![Alt text](/path/to/image.png "This is the title of the image.")

becomes

<figure>
<img alt="Alt text" src="/path/to/image.png" title="This is the title of the image." />
<figcaption>This is the title of the image.</figcaption>
</figure>

This meant also mean that this plugin is redundant and could be deprecated..

[fstueber]

I will have a closer look on those markdown extensions. But it seems you are right and someone else has already solved the problem.

[timvink]

I had a look, and:

• yafg (and it's fork caption) actually generates figures for all pictures, even emoticons:
  
• figureAltCaption also converts all images with alt text
• https://github.com/funk1d/markdown-figcap has a weird syntax
• markdown-captions converts all images to figures with captions, except when they have no alt text

So there is still an opportunity here to improve. So not using the caption: prefix should do nothing:

![Alt text](/path/to/image.png "This is the title of the image.")

<img alt="Alt text" src="/path/to/image.png" title="This is the title of the image.">

But adding the caption: prefix to the title should create the figcaption:

![Alt text](/path/to/image.png "caption: This is the title of the image.")

<figure>
     <img alt="Alt text" src="/path/to/image.png" title="This is the title of the image." />
      <figcaption>This is the title of the image.</figcaption>
</figure>

@facelessuser would you be open to a PR to pymdown-extensions that adds a figure caption extension? I'd be happy to contribute!

[facelessuser]

@timvink I have not yet considered adding a figure caption extension. It isn't something I've really need yet.

With that said, I see a lot of custom syntax, but I imagine this could be done quite simply using the existing attr_list extension paired with either a Python Markdown extension or MkDocs plugin.

Basically, just attach some attribute via attr_list to identify this specific image wants to have a caption:

![alt](image.png "title"){: data-fig="My caption or you could just use title."}

Then you just look for images with that attribute in either your Python Markdown extension or MkDocs plugin, and wrap the image as required.

[timvink]

Thanks for the input!

@fstueber if you decide to do the implementation via the img2fig plugin, another cool option would be to add lazy image loading by default (controlled via a plugin option). See squidfunk/mkdocs-material#1867

[fstueber]

I'll see what I can do. Must also think whether the extension (and not plugin) approach is better. Will keep you informed.

[timvink]

Cool, thanks!

From the mkdocs-material docs on figure captions:

Sadly, the Markdown syntax doesn't provide native support for image captions, but it's always possible to resort to HTML. Using figure and figcaption, captions can be added to images.

The section is about markdown extensions, so once there is a proper solution (and nice syntax), perhaps it could be promoted there as well.