Prevent image alt text from showing up under images as captions

[joelostblom]

Description

While many markdown implementations (e.g. github, common mark, pandoc) define the link text for images (within []) as the image alt text, quarto seems to use it as the caption instead. Is there any way to change this behavior via a setting or similar in quarto? I have a lot of existing material that I want to render with quarto, but I don't want the images' alt text to show up as captions and instead be considered as the actual alt text also in the HTML output (or possibly suppressed altogether if that is the only option).

[mcanouil]

Yes, use the Pandoc/Quarto Sy tex as described: https://quarto.org/docs/authoring/figures.html#alt-text

Note that, the caption is used as alt-text only because there is no alt-text set.

[joelostblom]

Thanks @mcanouil , that's the same section I linked in the question and my issue is that I want to avoid the alt text being used as the caption rather than the other way around.

[mcanouil]

I want to avoid the alt text being used as the caption rather than the other way around.

Sorry, you are confusing me here.
From the link you have:

![](elephant.png){fig-alt="A drawing of an elephant."}

Which allows you to have alternative text and no caption.

So, the only explanation is that you don't want to use the documented syntax. (If that is the case, that was not clear in your question)
Anyhow, you have no other choice than to edit your syntax either to include the backslash or use the syntax showed in the documentation.

[joelostblom]

Sorry if the description was confusing. As I mentioned what I want to do is to "define the link text for images (within []) as the image alt text". So not using a different syntax, but having the text withing [] be the alt text and there being no caption. The appended backslash does exactly that!

[mcanouil]

May I ask why do you prefer this syntax over the explicit one? Any particular reasons? (It's to get the whole picture in case your use case matches what future readers might want to do)

[joelostblom]

Yes, sure! One use case for me is migrating existing material to quarto where I have already used [] to indicate what's the alt text and I don't want to show that as the figure caption (I want to avoid rewriting that material as much as possible). A related one would be the creation of new material that is widely compatible if I need to migrate in the future.

Another use case is that in notebook environments (e.g. JupyterLab and VS Code), images that are pasted into a markdown cell have their file name automatically inserted inside [] so I end up with many image captions in quarto that are just file names (it seems like this is controlled by the browser environment and hard to change on the IDE side). These are not ideal as alt text either, but it is not as much of an issue as it is when showing up in the caption of every pasted image.

[cderv]

While many markdown implementations (e.g. github, common mark, pandoc) define the link text for images (within []) as the image alt text, quarto seems to use it as the caption instead.

@joelostblom, note that Pandoc does the same thing when the extension implicit_figures is active. And this is the case in Quarto.
See https://pandoc.org/MANUAL.html#extension-implicit_figures

An image with nonempty alt text, occurring by itself in a paragraph, will be rendered as a figure with a caption. The image’s alt text will be used as the caption.

So when using a tool that will use Pandoc, you need to make sure that Images are not considered figures.

Here is an example of different syntax.

---
title: "Test alt"
---

Pandoc's Markdown syntax for Image being a figure with caption

![Test](https://placehold.co/400)

Pandoc's Markdown syntax for Image as inline image (no caption)

![Test](https://placehold.co/400)\

Quarto explicit syntax for no caption and alt text

![](https://placehold.co/400){fig-alt="Test"}

Quarto explicit syntax for caption and alt text

![Caption](https://placehold.co/400){fig-alt="Test"}

[joelostblom]

Knowing that quarto uses the implicit_figures extension and that I can change the default behavior with appending a backslash is super helpful! Thank you @cderv! Is there already somewhere in the documentation? Otherwise I can make a PR for the alt text section

[mcanouil]

• https://pandoc.org/chunkedhtml-demo/8.17-images.html (I don't believe we want to copy all Pandoc's documentation and maintain that)
• https://quarto.org/docs/authoring/figures.html#alt-text

[joelostblom]

I didn't suggest that you copy of all Pandoc's documentation. I suggest adding one sentence mentioning \ and linking the pandoc docs. To avoid more confusion, here is the PR with the exact change that I think would be helpful quarto-dev/quarto-web#1072

[ptram]

An additional note about the use of backslash to make the text between square brackets appear as alt-text:

• Just adding a backslash also adds a new line, that you may or may not want.
• Adding a backslash and a white space still forces the text to be alt-text, but without adding a new line.