Block extension for adding captions to images

[joapuiib]

Hello,
I was thinking about a customizable and easy way for writing images with captions in markdown.

I've come across the markdown_captions extension, which is simple and works quite well. Basically, it gets the alt text from the image and transforms it in a <figure> element.

From their documentation:

![caption](img.jpg)
![caption2](img2.jpg)

<p>
  <figure><img src="img.jpg" /><figcaption>caption</figcaption></figure>
  <figure><img src="img2.jpg" /><figcaption>caption2</figcaption></figure>
</p>

Nevertheless, in my opinion, it's not customizable.

A set of features that I would love to have are:

• Allow multiple captions in a single <figure>.
• Be able to set a class attribute to each <figcaption>(for styling purposes).
• Add a id attribute to <figure>, that could be set manually or automatically (inspired by markdown-it-figure)
• Be able to set a prefix that would be used in all <figure>, like Figure %d:, where %d its a numerical value.
  • I don't know exactly how would this could be integrated with multiple captions.
• Use Markdown in <figcaption>.

So, a possible way to implement this would be to write a Blocks Extension, similar to Definition.

This would mean that we could provide a flexible syntax that allowed such features and customizations.
I haven't thought a lot about the syntax, but it could be something like:

/// figure
    id: custom-id
    autoincrement: false # This would set figure-1, figure-2 based on the number of figures in the document
![alt](img.jpg)

- Caption 1 {: .attribution}
- Caption __2__
- [Linked caption](url)
///

<figure id="custom-id">
    <img src="img.jpg" alt="alt"/>
    <figcaption class="attribution">Caption 1</figcaption>
    <figcaption>Caption <strong>2</strong></figcaption>
    <figcaption><a href="url">Linked caption</a></figcaption>
</figure>

So, I'm writing this discussion for two main reasons.

First, since I think using the Blocks Extension could be a solution, I would like to know your opinion about this: how to approach it, possible challenges, etc...

Secondly, I'm not asking this feature to be available in pymodwn-extensions. I'm willing to try to implement it and maintain it in a separate package, BUT, if you think this extension could be useful for more users, I'm willing to collaborate in it in this project.

Thanks in advance.

[facelessuser]

I will be honest, I actually do have captions on my radar and something I've been considering implementing.

My goals might be slightly different.

• Captions should not be image-specific. You can caption anything: a table, an image, a code block, example, etc. It's fine is people mainly use it for images, but I don't see a reason it should be restricted exclusively to images.
• Content to be caption and caption should both allow Markdown.
• Captions can be simple or complex.
• Prefix sounds like a reasonable idea. Auto numbering is not a bad idea if this is implemented as well.
• Auto IDs and/or classes is fine, but blocks already support adding manual classes and IDs, so I don't think anything extra is really required for manual IDs or classes.

I'm not sure that I get the multiple captions requirement. I have never seen this in the wild and I'm not convinced it is particularly helpful. I think a syntax that allows complex, multi-paragraph captions if required is sufficient.

I imagine a simple syntax is sufficient:

/// figure
some content

===

caption
///

Anyway, so yeah, it's been on my mind as something I was planning to implement, but the specifics I hadn't yet settled on yet.

[joapuiib]

I like the idea of captions for any kind of blocks.

In my case, the main use case for multiple captions is to set an attribution to an image, along with the caption itself:

<figure id="figure-2">
    <img src="img.jpg" alt="alt"/>
    <figcaption class="attribution">German, Wikipedia Commons</figcaption>
    <figcaption>Figura 2: Llenguatge màquina</figcaption>
</figure>

In this specific example, I've set everything manually.

If the features above are implemented:

• "Figura" would be the prefix, and 2 would be automatically generated.
• figure-2 would be generated automatically

[facelessuser]

Wouldn't it make more sense to nest figure stuff in this case?

//// figure
/// figure
content

===

caption
///

===

caption
////

The reason I question this is because this is a bit niche. Nothing is wrong with this approach, but If I were going to provide an extension that does captions, my goal is to simplify the approach and complexity to make it accessible and not too confusing. This would make prefixing less confusing. Otherwise, you need to make special rules where maybe only last caption gets prefixed (or if you prefer to have captions precede content, then only the first).

I would probably want to encourage this approach (nesting) for simplicity. I think it makes things easier to manage and simpler for people to understand.

---

I'm considered another approach as well which might make this easier by just following a block with a caption. The caption would be applied to the preceding block content automatically:

some content

/// caption
caption text
///

If you had multiple captions, the next caption would be applied to the figure, nesting the caption content automatically.

some content to have a caption

/// caption
caption text
///

/// caption
More caption text
///

My only concern with this approach is whether Python Markdown will always have the previous block properly visible. Fenced code uses placeholders, so I'd have to test how this works in practice, but if it does, this would simplify the approach to something pretty easily understandable.

[facelessuser]

I'll have to rethink depth handling. It will now have to be context-specific, but I think that it can be managed, but it will require more complexity.

[joapuiib]

That would be awesome!

I had thought of a similar option but I assumed it would complicate things a lot.

[facelessuser]

It does, but if I have a good justification to do it, I can't complain 🙂.

[facelessuser]

It'll probably take me a little to get it all ironed out, but I think we've finally settled on what needs to be in it. I have an overall vision of what it's going to look like, so I'll iron out the fine details.

[joapuiib]

No worries. With the features we have discussed, it's worth the wait 😄

I'm happy to help with anything!

[facelessuser]

I won't rule out the idea of multiple captions, but I think there are ways to handle it without needing multiple captions under one figure. At least that is my initial thought.

[joapuiib]

I'll post this here on a different thread in order not to mix topics.

Looking at markdown-it-figure, I see that the prefix is wrapped in a <span> class, I guess for styling purposes.

<figure id="figure-1234">
  <img src="/images/foo.png" alt="Alt Text" />
  <figcaption>
    <p>
      <span class="figure-id">1234: </span>
      Caption
    </p>
  </figcaption>
</figure>

Would this be interesting to have it here?

[joapuiib]

@facelessuser I think this comment has gone unnoticed.

[facelessuser]

No, it hasn't been ignored, and I already have some code to add such a span.

[joapuiib]

Ok, sorry for the ping then 😶

[facelessuser]

No worries, this was a consideration even before you posted this 🙂 .

[facelessuser]

Starting a new thread. So I refactored the extension and tried to simplify some things.

1. The extension now generates various caption types, by default caption, figure-caption, and table-caption. The user can override the types with their own.

   caption has no prefix template and is a generic caption type. Figure provides a template of Figure {}. and table a template of Table {}..

   To define your own with templates that match your language or use a different style, you could do this in MkDocs.

   pymdownx.blocks.caption:
     types:
     - name: caption
     - name: figure-caption
       prefix: 'Figura {}.'
     - name: more

2. Figure IDs and prefixes are only auto-generated when auto is set to True. IDs and prefixes are only applied to figures that define a prefix template. If auto_level is configured with a non-zero value, prefixes and IDs are limited as specified.

   Previously I had toyed with the idea of using something like - to avoid prefixes, but since we can define types that have no prefix, those should be used instead. This makes things simpler. If you need an ID for a non-numbered figure, you can just add a unique ID yourself in the traditional way.

   Figure depth is determined by nesting under like figures. Parent figures which do not share the same type are ignored in the calculation. So a table figure nested under a normal figure will be considered a level 1 table.

3. Prepending can be set globally via prepend, but if desired, per block handling will allow the use of < and > in the header to specify prepended and appending respectively.

4. In manual mode, numbers are specified in the header. Numbers in the header are ignored in auto mode. Prepend specifiers must come before figure numbers.

Hopefully, with the new flexibility, everything that is needed can be achieved. I realize that I walked back some things, but I did so after considering the interaction based on the new refactor. I'm obviously open to discussing anything that was moved out that we feel may need to come back if a reasonable use case is provided.

The PR was updated with the latest changes.

[facelessuser]

Yes, that is expected. I give a default setup, when you you override, you override everything. This will be fully documented.

[joapuiib]

Yeah, I just figured it out. 😅

[facelessuser]

My plan is probably to switch auto to default, document things, and call it good. If you find issue between now and when I get that done, let me know. It'll probably be a couple days until I get around to finishing.

[joapuiib]

Sounds good! 😄 Thanks for your patience!

[facelessuser]

No worries. It's nice to have feedback opposed to doing it in a vacuum, which is usually the case.

[joapuiib]

I'm bringing this again:

If I get this correctly, the auto/manual mode is set globally for all caption types. A more flexible approach would be able to override auto for each caption type, so we could have table-caption act as auto and figure-caption be manual.

I don't have a specific use case for this requirement. It's only a thought.

I want to migrate the following page Model ER to mkdocs. As you can see, there are a lot of images in this material.

Each section has a main figure, that explains the usage of an ER diagram in a generic way. Also, it has some examples.

In order to have some order in figure numbering, I was thinking of "nesting" figures by section:

## Section
Some text.

![Generic image](url)
/// figure-caption
    attrs: {class: "attribution"}
    Attribution
///
/// figure-caption| 1
Caption generic
///

//// example
Some example text.

![Example 1](url)
/// figure-caption | 1.1
Example 1 caption
///
////

//// example
Some example text.

![Example 2](url)
/// figure-caption | 1.2
Example 2 caption
///
////

In this case, I need to use manual mode, but maybe other pages doesn't need manual, and I wouldn't like to lose auto mode in all my site. Here, I would like to set a new caption type, figure-manual-caption that was manual, while the rest are auto.

I hope this example makes sense.

[facelessuser]

I'm not sure yet how I would want to approach this or if I want to address it directly, but maybe. I think mixing this stuff can definitely be more confusing for a new editor to come into a document, but I'm not going to dismiss the validity of such a request. I need some time to think about what, if anything, I want to do to address this. 🤔

In the short term, If you absolutely need manual captions in auto, you should can use a non-prefix type and specify your prefix. You may want to have sub-figures with captions (a) whatever and (b) whatever or do something similar to what you are doing. If you need complete control of your caption, you don't have to use auto-generated prefixes.

Some example

/// caption
Figure 1.1. Caption text
///

[facelessuser]

I was looking into some other clever solution for this problem, but in your specific use case, the elements aren't siblings, so no easy way to set a level and have the extension easily figure it out when and how to increment.

I'm thinking about specifying some virtual parent, that might work. Maybe something where you can just reference the parent ID as either the figure number or the actual ID:

![Generic image](url)
/// figure-caption
Caption generic
///

//// example
Some example text.

![Example 1](url)
/// figure-caption
    parent: 1
Example 1 caption
///
////

Or maybe because auto doesn't use numbers, we create references. I guess you could use numbers as a reference....something to think about.

![Generic image](url)
/// figure-caption | some-reference
Caption generic
///

//// example
Some example text.

![Example 1](url)
/// figure-caption
    parent: some-reference
Example 1 caption
///
////

[joapuiib]

Wouldn't it be easier just to be able to set auto as per-block option?

My example was very specific (niche), that it will probably not be used by anyone besides me.

I think other users might find useful having a more flexible approach, that can mix both auto and non-auto figures.

[facelessuser]

Wouldn't it be easier just to be able to set auto as per-block option?

Per block can create duplicate IDs and mess up the auto-numbering.

If you meant per type, sure, you can have redundant types, one manual and one auto. With that said, the people who want auto don't want to think about numbers, they just want figure numbering to be correct in relation to the other figures. The scenario you've presented, while niche, isn't so far-fetched that I think it isn't worth considering.

In your case, it is a relative case. You have a figure that is the first (1), and you want to have to have sub-figures relative to it (1.1 and 1.2), but they aren't children of each other but are children to your example section.

The whole point of auto is so a user can define figures without having to micro-manage the numbers. If I mix auto and manual, then if I want to insert an example with figures, I have to update the whole document ensuring the examples all have updated figures. If all I need to do is provide a relation between them, then I don't need to. I'm trying to take this scenario seriously and consider whether it is something that can and should be handled via auto.

Now, if you wanted to simply start at 1.1 or 1.1.1 without an appropriate parent of 1, well that is very niche. Sure, a manual mode in this scenario would be easier and not worth the effort to provide a workaround; though, I'd argue an even easier approach on my side is to just let the user use a non-prefix type and specify the figure themselves, but yes, a manual type could also solve this scenario, which is much more niche.

[joapuiib]

Per block can create duplicate IDs and mess up the auto-numbering.

Yeah sorry, I meant per-type.

  - pymdownx.blocks.caption:
      auto: true
      auto_level: 1
      types:
        - caption
        - name: figure-caption
          prefix: "Figura {}."
        - name: "table-caption"
          prefix: "Taula {}."
        - name: "figure-manual-caption"
          auto: false # This will override extension `auto`
          prefix: "Figura {}."

With that said, the people who want auto don't want to think about numbers, they just want figure numbering to be correct in relation to the other figures.

With this config, If I need a specific numbering, I can use figure-manual-caption. All other caption types will be auto so I don't need to worry about numbering.

If I mix auto and manual, then if I want to insert an example with figures.

As each type is different, and the counters are independent. They are not affected by each other, and it's possible to use each one of them all based on your needs.

## Section
Some text.

![Generic image](url)
/// figure-caption
This is automatic
///

![Generic image](url)
/// figure-caption
This is automatic too
///

/// figure-manual-caption | 2
This is manual
///

![Generic image](url)
/// figure-manual-caption | 4
This is manual too
///

The point of this example is that if I would like to use manual mode in a specific case (regardless of the nature), I will need to give up on auto entirely.

[joapuiib]

I think we are feature-complete as far as the first release is concerned.

I think so, too.

I'll let you know if I find anything!

[facelessuser]

Slight update, ^depth is now relative to the figure's current depth. So if at depth 2, ^1 increases to depth 3 (one level). Children under such an element will now be relative to a depth-adjusted parent. This provides more sane handling.

[facelessuser]

I need to make some adjustments to manual numbers so they work within the relative depth systems

[facelessuser]

Okay, I think I fixed everything. I'll add formal tests later today.

[facelessuser]

Tests are in place and documentation has been updated. I will give it until the end of Friday for feedback and will then merge it. Obviously, issues can be created after that if bugs are found.

[joapuiib]

Hi, I'm testing manual depth ^1 in auto figures.

In this case, I would like that the nested attribution didn't have a prefix prepended, but the virtual nested did.
Since attribution and virtual nested are at the same level, I can't just enable one of them.

  - pymdownx.blocks.caption:
      auto: true
      auto_level: 2

![Image](https://via.placeholder.com/150)
/// figure-caption
    attrs: {class: "attribution"}
Attribution
///
/// figure-caption
Caption for image
///

![Image](https://via.placeholder.com/150)
/// figure-caption | ^1
Virtual nested caption
///

Setting auto_level to 1 will prevent the virtual nested caption to show the prefix.

[joapuiib]

Is this released to pypi?

[facelessuser]

No release has been made. The feature has just been merged to main.

[joapuiib]

When do you have planned to release it?

[facelessuser]

Once I determine I have no plans to add anything else to the release. I have at least one more thing I'm considering.

[facelessuser]

I had plans to get more stuff into the next release, but I don't really have the time, so I'll probably make a release in the next couple of days.

[joapuiib]

I don't know if it's too late to address this, but the caption syntax /// caption | < ^1 doesn't work well with editor syntax highlight.

Using < at the end doesn't cause an issue in my setup, but this syntax is not allowed by the extension.

[facelessuser]

This is going to be highly dependent upon the editor. For instance, in my editor, it does just fine:

To be honest, I normally wouldn't expect something like this to be highlighted as tag names don't start with numbers, per the spec. But yes, some syntax implementations will have lazy approaches that assume < will always start a tag. I'm not sure how much I am concerned with such things. You are always going to run into potential highlight issues when using custom syntax.

There are potential ways we could address this, I just don't know if it is worth the effort. You are welcome to open an issue for this so that I can consider if it is worth addressing.