Image captions/descriptions #2739

New Issue

OVERLORD · 2026-02-05T04:58:17+03:00

OVERLORD commented

2026-02-05 04:58:17 +03:00

Originally created by @rounakdatta on GitHub (Apr 2, 2022).

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?

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

Originally created by @rounakdatta on GitHub (Apr 2, 2022). ### 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_

OVERLORD added the 🔨 Feature Request label 2026-02-05 04:58:17 +03:00

OVERLORD commented

2026-02-05 04:58:22 +03:00

@ssddanbrown commented on GitHub (Apr 3, 2022):

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.

@ssddanbrown commented on GitHub (Apr 3, 2022): 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.

OVERLORD commented

2026-02-05 04:58:38 +03:00

@Chansig commented on GitHub (Sep 15, 2022):

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.

@Chansig commented on GitHub (Sep 15, 2022): 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.

OVERLORD commented

2026-02-05 04:58:42 +03:00

@gaufde commented on GitHub (Jan 4, 2023):

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.

@gaufde commented on GitHub (Jan 4, 2023): 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.

OVERLORD commented

2026-02-05 04:58:45 +03:00

@mahomedh commented on GitHub (Jan 20, 2023):

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.

@mahomedh commented on GitHub (Jan 20, 2023): > 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)](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.

OVERLORD commented

2026-02-05 04:58:51 +03:00

@Eekrs commented on GitHub (Mar 19, 2023):

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

@Eekrs commented on GitHub (Mar 19, 2023): TinyMCE does provide a sample for using captions: https://tinymce.github.io/tinymce-demos/images/toggle-image-size-context-toolbar.html

OVERLORD commented

2026-02-05 04:58:54 +03:00

@jasell commented on GitHub (Feb 16, 2024):

I see at least three solutions...

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

I prefer the first option.

@jasell commented on GitHub (Feb 16, 2024): 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.

OVERLORD commented

2026-02-05 04:58:57 +03:00

@jensbech commented on GitHub (Oct 13, 2024):

For our decade-spanning DND campaign Wiki, image labels on longer pages would be a great way to describe - not only see - our player's heroic deeds.

@jensbech commented on GitHub (Oct 13, 2024): For our decade-spanning DND campaign Wiki, image labels on longer pages would be a great way to describe - not only see - our player's heroic deeds.

OVERLORD commented

2026-02-05 04:59:02 +03:00

@Saturo78 commented on GitHub (Nov 4, 2025):

I like the way wiki.js privedes the image description. There is a textbox below the image.

@Saturo78 commented on GitHub (Nov 4, 2025): I like the way wiki.js privedes the image description. There is a textbox below the image.

OVERLORD commented

2026-02-05 04:59:07 +03:00

@schoettl commented on GitHub (Nov 4, 2025):

Just as a reference, Nextcloud Notes also supports a image caption. It looks like this:

It is saved as markdown:

![ChatGPT](.attachments.4937/grafik.png)

which pandoc converts to this HTML:

<figure>
<img src=".attachments.4937/grafik.png" alt="ChatGPT" />
<figcaption aria-hidden="true">ChatGPT</figcaption>
</figure>

@schoettl commented on GitHub (Nov 4, 2025): Just as a reference, [Nextcloud Notes](https://apps.nextcloud.com/apps/notes) also supports a image caption. It looks like this: <img width="659" height="340" alt="Image" src="https://github.com/user-attachments/assets/bea5347e-c297-4844-bb5a-a83a50245205" /> It is saved as markdown: ```md ![ChatGPT](.attachments.4937/grafik.png) ``` which pandoc converts to this HTML: ```html <figure> <img src=".attachments.4937/grafik.png" alt="ChatGPT" /> <figcaption aria-hidden="true">ChatGPT</figcaption> </figure> ```

Sign in to join this conversation.

Branches Tags

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: starred/BookStack#2739