Image captions/descriptions

[rounakdatta]

Describe the feature you'd like

Although Bookstack collects the Image Description field, it is not used clearly I believe. The description could be used as the caption for the image, and displayed under it.

Describe the benefits this would bring to existing BookStack users

Images having captions is an important feature, users can avoid writing description for the image separately.

Can the goal of this request already be achieved via other means?

Probably, with some custom Javascript, but this should be available to all users by default.

Have you searched for an existing open/closed issue?

• [X] I have searched for existing issues and none cover my fundemental request

How long have you been using BookStack?

0 to 6 months

Additional context

No response

[ssddanbrown]

Thanks for the request @rounakdatta,

Alt text vs Captions

Although Bookstack collects the Image Description field, it is not used clearly I believe. The description could be used as the caption for the image, and displayed under it.

The current input is specifically "Alternative Description" (Or commonly known as "Alt text"), this is intended to be used when the image cannot be viewed, such as when the image fails to load or by users using a screen-reader. Your core request appears to be for visible captions, which I think would in reality have a slightly different use-case. Alt text if often used to describe the contents of an image whereas a caption is often used to add additional context or meaning.

Benefits

Describe the benefits this would bring to existing BookStack users Images having captions is an important feature, users can avoid writing description for the image separately.

It would be good to know why this is an important feature. How would this be used? What would this achieve?

Achieving via other means

Can the goal of this request already be achieved via other means? Probably, with some custom Javascript, but this should be available to all users by default.

If you wanted to use the alt-text as caption text, then yeah, you could add some JavaScript to the "Custom HTML Head Content" settings to allow this for all.

In addition, I guess you can technically achieve simulating captions with current text and formatting options. Placement may be tricky to keep aligned with the image though.

Implementation Challenges

If we were to add captions I'd want to use semantic HTML for the structure, in which using <figure> and <figcaption> would best suit. We don't currently support these elements within the editor, could be a pain in the WYSIWYG as that becomes quite a significant structure to support. Within our Markdown editor, there is no commonmark standard for captions so we'd have to resort to HTML yet again which is not ideal.

[Chansig]

Hi, Adding a caption is essential to specify the copyright of the image. This is what keeps me from using BookStack publicly today.

Thanks for the job.

[gaufde]

Captions are important for scientific documents. Generally, the flow of the body text is kept continuous and references to figures are made by figure number. Images are placed in the text where convenient, but they are not always placed at the same location as where they are referenced. Each image will have a caption that states the figure number as well as a brief description of what the image shows. That caption needs to live with that image, even if the image is moved within the document, therefore it can not be body text. Furthermore, image captions generally have different styling so that it is visually separate from the body text. This makes it easy for the reader to skip over the caption content until the body text references an image. Then, they can find the correct image and study the caption before returning to read the body text.

[mahomedh]

Within our Markdown editor, there is no commonmark standard for captions so we'd have to resort to HTML yet again which is not ideal.

Why not leave the <figure> and <figcaption> html in the markdown page as [Markdown supports inline HTML](https://daringfireball.net/projects/markdown/syntax#html) ?

Then the more complicated thing will be to add a button to the WYSIWIG editor to "Add image with caption" and a form to capture the caption.

[Eekrs]

TinyMCE does provide a sample for using captions: https://tinymce.github.io/tinymce-demos/images/toggle-image-size-context-toolbar.html

[jasell]

I see at least three solutions...

1.  add a special button, add caption, that activate when you select a non-text item, like an image, table, drawig, youtube etc, Or
2.  add a caption attribute in the image dialogue under description, or
3.  add new style with a different look then the regular Paragraph and center-align.

I prefer the first option.