feat: Add image captions support

[osulyanov]

Add support for image captions using figcaption tag

Description

Added support for image captions using HTML's semantic figure and figcaption tags.
This enhances image context and improves document accessibility by providing visual relationships between images and their captions.

Features

• New caption syntax with two options:
  1. Use the title as caption: ![Alt text](image.jpg "Caption text" =100x100){ caption }
  2. Explicit caption: ![Alt text](image.jpg "Title" =100x100){ caption="Custom caption text" }
• Outputs semantic HTML using <figure> and <figcaption> tags
• Maintains compatibility with existing image features (eg. SVG inlining)

Example

Input:

![Alt text](image.jpg "Default caption text" =100x100){ caption }
![Alt text](image.jpg "Title" =100x100){ caption="Specified caption text" }

Output:

<figure>
    <img src="image.jpg" alt="Alt text" title="Default caption text" width="100" height="100">
    <figcaption>Default caption text</figcaption>
</figure>

<figure>
    <img src="image.jpg" alt="Alt text" title="Title" width="100" height="100">
    <figcaption>Specified caption text</figcaption>
</figure>

Documentation

Corresponding documentation PR: diplodoc-platform/docs#80

Technical Changes

• Added new markdown-it inline rule for parsing caption syntax
• Implemented token transformation for figure/figcaption wrapping
• Fixed image path replacement to handle multiple occurrences
• Improved loop handling for patched images

Testing

• Manual testing with various image caption configurations
• Verified compatibility with existing image features
• Tested multiple images in a single document

Closes DOCSTOOLS-3428

Related issue: #514

[3y3]

Looks like this is yet another attribute parser.

Can we use already implemented instead of this?

There was attached markdown-it-attrs plugin.

So at this time (when we process something after image) image token should already contain target parsed attribute.

Or we can attach parser in next way:

md.core.ruler.after('curly_attributes', 'image_caption', imageCaption);

[osulyanov]

Omg, that's what I needed, it could save 2 days if I knew about it. Updated the implementation using markdown-it-attrs plugin

[3y3]

Replace default token image with image_with_caption can be wery destructive for external plugins, which searches for image token only.

I propose to implement this in other way:

• Check what image token has caption attr.
• Then generate new token image_caption after this one.
• Add renderer for image_caption which will generate all required a11y compatible html.
• Convert caption attr on image to some class attr image.attrSet('class', image.attrGet('class') + ' yfm-image-with-caption')
• Add some styles to main css.

[osulyanov]

Makes sense, I got rid of image_with_caption token

[osulyanov]

Wdyt, does the current solution work or potentially could have a negative impact on other image-related plugins?
What about the CSS? Do I need to align it to the left?

[3y3]

Thank you, @osulyanov, for your contribution. The PR description was great, making it easy to understand all the changes.

I've added some comments to help reduce the impact of the change.

Check out this comment, where I discuss the issue of backward compatibility.

[osulyanov]

@3y3 Thanks for the fast review and valuable and well-described comments. I made the changes to align with them, please have a look if it works.

[3y3]

This looks like approvable PR. I will merge it at the end of week.
If you want to improve it even more, you can add some tests.

I'm also not sure what this four lines are required, but I need to test it later
https://github.com/diplodoc-platform/transform/pull/586/files#diff-e21601ef2d076218747acc804a5a8a16f35a4eb71ef0b73e6db53d005b074869R204