Empty alt text on reference-style images rendering incorrectly #227

Closed
opened 2026-01-29 14:30:51 +00:00 by claunia · 5 comments
Owner

Originally created by @guypursey on GitHub (Oct 1, 2018).

Good

This:

![](image-without-alt-text.jpg)

Produces this:

<p>
  <img src="image-without-alt-text.jpg" alt="">
</p>

Which is expected behaviour and good for accessibility.

Bad

However, if you use a reference style image:

![][1]

[1]: image-without-alt-text.jpg

You get this:

<p>
  <img src="image-without-alt-text.jpg" alt="1">
</p>

Which is not good for accessibility -- there's no reason the alt text should be the number 1.

You can try this yourself with Markdig here to verify.

Summary

I'd expect the reference-style image to behave in the same way as the inline-style image notation which is listed as example 552 in the CommonMark spec.

But instead it's using the index of the footnote as the alt text.

Expected behaviour renders in most other libraries and crucially you can see this rendering correctly in CommonMark which Markdig purports to be compliant with.

Originally created by @guypursey on GitHub (Oct 1, 2018). ## Good This: `![](image-without-alt-text.jpg)` Produces this: ``` <p> <img src="image-without-alt-text.jpg" alt=""> </p> ``` Which is expected behaviour and good for accessibility. ## Bad However, if you use a reference style image: ``` ![][1] [1]: image-without-alt-text.jpg ``` You get this: ``` <p> <img src="image-without-alt-text.jpg" alt="1"> </p> ``` Which is not good for accessibility -- there's no reason the alt text should be the number `1`. You can [try this yourself with Markdig here](https://babelmark.github.io/?text=Hello+**Markdig**!%0A%0A!%5B%5D(image-without-alt-text.jpg)%0A%0A!%5B%5D%5B1%5D%0A%0A%5B1%5D%3A+image-without-alt-text.jpg%0A%0A) to verify. ## Summary I'd expect the reference-style image to behave in the same way as the inline-style image notation which is listed as [example 552 in the CommonMark spec](https://spec.commonmark.org/0.28/#example-552). But instead it's using the index of the footnote as the alt text. Expected behaviour renders in most other libraries and crucially [you can see this rendering correctly in CommonMark](https://spec.commonmark.org/dingus/?text=!%5B%5D%5B1%5D%0A%0A%5B1%5D%3A%20(%2Fimage-without-alt-text.jpg)%0A) which Markdig purports to be compliant with.
claunia added the bugPR Welcome! labels 2026-01-29 14:30:51 +00:00
Author
Owner

@xoofx commented on GitHub (Oct 1, 2018):

Expected behaviour renders in most other libraries and crucially you can see this rendering correctly in CommonMark which Markdig purports to be compliant with.

Bugs happen, PR Welcome.

@xoofx commented on GitHub (Oct 1, 2018): > Expected behaviour renders in most other libraries and crucially you can see this rendering correctly in CommonMark which Markdig purports to be compliant with. Bugs happen, PR Welcome.
Author
Owner

@xoofx commented on GitHub (Oct 7, 2018):

Fixed by PR #254 by @MihaZupan

@xoofx commented on GitHub (Oct 7, 2018): Fixed by PR #254 by @MihaZupan
Author
Owner

@guypursey commented on GitHub (Oct 8, 2018):

Sorry to follow-up on a closed issue, but any idea when the PR above (#254 ) might be included in a release? Thanks.

@guypursey commented on GitHub (Oct 8, 2018): Sorry to follow-up on a closed issue, but any idea when the PR above (#254 ) might be included in a release? Thanks.
Author
Owner

@xoofx commented on GitHub (Oct 8, 2018):

Sorry to follow-up on a closed issue, but any idea when the PR above (#254 ) might be included in a release? Thanks.

I don't always push a new release for every PR merged. I wait for a few days/weeks if this is not critical to batch them with other PRs. You can always compile it on your own if you want this immediately.

@xoofx commented on GitHub (Oct 8, 2018): > Sorry to follow-up on a closed issue, but any idea when the PR above (#254 ) might be included in a release? Thanks. I don't always push a new release for every PR merged. I wait for a few days/weeks if this is not critical to batch them with other PRs. You can always compile it on your own if you want this immediately.
Author
Owner

@guypursey commented on GitHub (Oct 8, 2018):

Thanks @xoofx. Appreciate the quick response.

@guypursey commented on GitHub (Oct 8, 2018): Thanks @xoofx. Appreciate the quick response.
Sign in to join this conversation.
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: starred/markdig#227