Alternative Text for Images in titles

[rachfop]

Have you read the Contributing Guidelines on issues?

• I have read the Contributing Guidelines on issues.

Prerequisites

• I'm using the latest version of Docusaurus.
• I have tried the npm run clear or yarn clear command.
• I have tried rm -rf node_modules yarn.lock package-lock.json and re-installing packages.
• I have tried creating a repro with https://new.docusaurus.io.
• I have read the console error message carefully (if applicable).

Description

Looks like there is a bug with how docusaurus renders alternate texts placed in titles.
But if you have a title with an image and alias:
## ![Run the Application](/img/icons/run.png) Run the Application
The title is duplicated in the sidebar.
This unfortunate because images should have alternate text (alt text) for accessibility.

Reproducible demo

No response

Steps to reproduce

1. Create a title with an svg or image
2. Provide alt text in the image
3. Look at the side bar

Expected behavior

Alt text shouldn't appear in the side bar.

Actual behavior

Your environment

• Public source code:
• Public site URL:
• Docusaurus version used:
• Environment name and version (e.g. Chrome 89, Node.js 16.4):
• Operating system and version (e.g. Ubuntu 20.04.2 LTS):

Self-service

• I'd be willing to fix this bug myself.

[Josh-Cena]

You do not need alt messages if the image is purely decorative (which is the case here—it's an icon). This is especially the case if your alt text is duplicated with the text content—it always leads to poor accessibility.

Imagine two cases. First one is where you are reading the page with a screen reader. When reading the title, the reader will tell you there's an image and its message, and then immediately followed by the title text itself, and you hear the exact information twice. If that's less familiar, consider when you disable images in your browser or when the image is broken. The alt message will be shown in place of the image—which means you end up with duplicated text anyway.

TL;DR: "always add alt messages helps with accessibility" is a myth; adding alt messages where there should be none is a net minus to accessibility. Moreover, images in headings should always be decorative, otherwise the page structure is really weird, and decorative images always have empty alts. All this means our behavior is intended.

#8047 and mdn/mdn-community#168 contain some good information about how to write good alt texts.

[rachfop]

Thanks for pointing me to additional resources. I appreciate it.

I'll close this issue then.