Module should not use <blockquote> for captions; use <div> and provide default .image-field-caption CSS

The template uses a <blockquote> element which inherits site-wide blockquote styles and often results in inappropriate formatting for captions as already demonstrated in this issue.

Most themes style blockquotes for quotations, not captions.

I will propose to replace <blockquote> with a <div> and add a default CSS style for the .image-field-caption class to provide a clean, neutral caption appearance out of the box.

This will prevent conflicts with custom blockquote styles and make the module’s output more predictable and easier to theme.

I will suggest the following style for the class:

.image-field-caption {
    display: block;
    width: fit-content;    
    margin: .5rem 0;
    font-size: .95rem;
    color: #6b7280;
    background: #f8fafc;
    border-radius: 6px;
    padding: .5em;
    font-style: italic;
    box-shadow: 0 1px 4px rgba(0,0,0,.03);
}

.image-field-caption p:last-child {
  margin: 0;
}

If okay I can submit a merge request with the changes.

Thank you for reviving this discussion and for preparing a concrete proposal.

I believe the original maintainer's approach is still valid today: the module should provide only the minimal markup needed, leaving it up to site builders and themers to override the template in their own theme. With Twig it is straightforward to copy the template and replace <blockquote> with <div> (or any other element) if a project requires it.

Introducing predefined colors, shadows, and other opinionated styles into the module would reduce flexibility and could conflict with existing design systems. Since there is no truly universal look for captions, it seems better to keep the module neutral and let themes handle presentation.

If someone wants custom styling, it's also easy to attach it directly in the template with their own library, for example:
{{ attach_library('your_theme/your_image_caption_styles') }}
This way both the markup and the styles can be overridden cleanly and in one place.

@foxy-vikvik what do you think about this?

Thanks @kksandr for the response.

I think that making the module render captions as quotes is not 'minimal markup' because most themes will already have styling for blockquote and for someone to customize the captions, he will first have to get rid of the blockquote styles before adding any custom styles. To get rid of the blockquote styles he will have to override the template. This is making the module developer-centric. An average site builder will not find it fun having to copy over template files for every module he installs.

On the other hand, if you make it a div, it will be bare and unobstructive and will allow anyone to now cleanly write styles for the caption as they want (that is in the case there is no default custom styling as I proposed).

The custom style I proposed will fit for most people and if they desire they can override the styles in their custom CSS files, without having to copy template files over.

If you weigh it on a scale, a div is a more 'minimal markup' than a blockquote.

Thanks for raising this point. We discussed it with @foxy-vikvik and decided to add a new markup option, but instead of a styled <div> it will be implemented using <figure> and <figcaption>. Please see 📌 Create accessible formatter using and tags for captions (a11y compliance) Active for details.

I will start working on this now. This approach is semantically correct, meets accessibility requirements, and is already used in Drupal core by CKEditor5.

Now that this issue is closed, please review the contribution record.

As a contributor, attribute any organization helped you, or if you volunteered your own time.

Maintainers, please credit people who helped resolve this issue.

Thanks @kksandr

I did think of <figcaption> as the most semantically correct HTML5 approach but kind of hesitated to mention it as it will involve more work. Good to know you are ready to work on it.