[GH-ISSUE #913] MD033 triggered by "elements" inside of image description #551

New issue

Closed

opened 2026-03-03 01:27:56 +03:00 by kerem · 4 comments

kerem commented

2026-03-03 01:27:56 +03:00

Owner

Originally created by @queengooborg on GitHub (Jul 20, 2023).
Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/913

First off, I'd like to mention that this isn't actually a case that's covered by either the CommonMark or the GitHub Flavored Markdown specs. Neither specification states what characters must be escaped inside of image descriptions. This may simply be a "sync-with-Prettier" case, or this could actually be a Prettier bug.

After formatting with Prettier, angle brackets inside of image descriptions are unescaped. However, when this is done, rule MD033 is triggered if the found "element" is not listed in the allowed_elements parameter.

<!-- Before Prettier -->
![The \<textarea&gt; element.](textarea_basic.png)

<!-- After Prettier; triggers MD033 -->
![The <textarea> element.](textarea_basic.png)

Note that in both cases, the following HTML is produced on MDN's rendering engine, which uses remark and rehype and does not perform any transformations to the alt. text in image markup AFAIK:

<img src="/en-US/docs/Learn/Forms/Other_form_controls/textarea_basic.png" alt="The <textarea> element." width="636" height="338" loading="lazy">

I've also tested other elements (ex. em, strong, b, i, a) to see if there's any different behavior with other elements -- so far I've seen none. I have noticed that Markdown syntax for inline code, bold and italics is parsed and converted to plain text (AKA ![**Hello**](foo.png) becomes <img src="foo.png" alt="Hello" />, not <img src="foo.png" alt="<strong>Hello</strong>" />).

However, it's unclear whether other Markdown parsers will do the same, as this behavior is undefined by the spec. I'm assuming that if this is a change Prettier is making, it's been thoroughly vetted...but we did just uncover a critical bug with underscores/asterisks in links inside bold/italic spans, so who knows?

Originally created by @queengooborg on GitHub (Jul 20, 2023). Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/913 First off, I'd like to mention that this isn't actually a case that's covered by either the CommonMark or the GitHub Flavored Markdown specs. Neither specification states what characters must be escaped inside of image descriptions. This may simply be a "sync-with-Prettier" case, or **this could actually be a Prettier bug.** --- After formatting with Prettier, angle brackets inside of image descriptions are unescaped. However, when this is done, rule MD033 is triggered if the found "element" is not listed in the `allowed_elements` parameter. ```md  ![The \<textarea> element.](textarea_basic.png)  ![The <textarea> element.](textarea_basic.png) ``` Note that in both cases, the following HTML is produced on MDN's rendering engine, which uses `remark` and `rehype` and does not perform any transformations to the alt. text in image markup AFAIK: ```html <img src="/en-US/docs/Learn/Forms/Other_form_controls/textarea_basic.png" alt="The <textarea> element." width="636" height="338" loading="lazy"> ``` I've also tested other elements (ex. `em`, `strong`, `b`, `i`, `a`) to see if there's any different behavior with other elements -- so far I've seen none. I _have_ noticed that Markdown syntax for inline code, bold and italics _is_ parsed and converted to plain text (AKA `![**Hello**](foo.png)` becomes `<img src="foo.png" alt="Hello" />`, not `<img src="foo.png" alt="<strong>Hello</strong>" />`). However, it's unclear whether other Markdown parsers will do the same, as this behavior is undefined by the spec. I'm _assuming_ that if this is a change Prettier is making, it's been thoroughly vetted...but we did just uncover a critical bug with underscores/asterisks in links inside bold/italic spans, so who knows?

kerem

2026-03-03 01:27:56 +03:00

closed this issue
added the
question
label

kerem commented

2026-03-03 01:27:57 +03:00

Author

Owner

@DavidAnson commented on GitHub (Jul 20, 2023):

See #579 for more discussion. It's not clear to me the situation is any ... clearer today. :)

@DavidAnson commented on GitHub (Jul 20, 2023): See #579 for more discussion. It's not clear to me the situation is any ... clearer today. :)

kerem commented

2026-03-03 01:27:58 +03:00

Author

Owner

@queengooborg commented on GitHub (Jul 20, 2023):

Argh... 💢

I'm not surprised that another MDN contributor ran into the same issue and reported it (heck, looks like they came across it in the same file I was looking at). In the end, we resolved it by simply replacing the angle brackets with quotes, but I'm coming across it again while formatting the translated versions. Looking at the issue opened on the CommonMark spec, it seems that the resolution is primarily blocked on updating the reference implementations.

However, after diving deeper into this rabbit hole, I've found that escaped asterisks and underscores are also unescaped, which will turn them into bold/italics syntax which will then get ignored per the CommonMark spec. As such, I think that my suspicions that this was more of a Prettier bug were accurate. I'll open an issue there (or link to an existing one)!

@queengooborg commented on GitHub (Jul 20, 2023): Argh... 💢 I'm not surprised that another MDN contributor ran into the same issue and reported it (heck, looks like they came across it in the same file I was looking at). In the end, we resolved it by simply replacing the angle brackets with quotes, but I'm coming across it again while formatting the translated versions. Looking at the issue opened on the CommonMark spec, it seems that the resolution is primarily [blocked on updating the reference implementations](https://github.com/commonmark/commonmark-spec/issues/716#issuecomment-1174771852). However, after diving deeper into this rabbit hole, I've found that escaped asterisks and underscores are also unescaped, which will turn them into bold/italics syntax which will then get ignored per the CommonMark spec. As such, I think that my suspicions that this was more of a Prettier bug were accurate. I'll open an issue there (or link to an existing one)!

kerem commented

2026-03-03 01:27:58 +03:00

Author

Owner

@DavidAnson commented on GitHub (Jul 20, 2023):

Yeah, a bit of a mess. I'll probably close this again based on everybody disagreeing about what should happen. :)

@DavidAnson commented on GitHub (Jul 20, 2023): Yeah, a bit of a mess. I'll probably close this again based on everybody disagreeing about what should happen. :)

kerem commented

2026-03-03 01:27:58 +03:00

Author

Owner

@queengooborg commented on GitHub (Jul 20, 2023):

(Disagreement: a software developer's favorite!)

Haha, feel free to close this issue, and thank you for taking the time to respond!

@queengooborg commented on GitHub (Jul 20, 2023): _(Disagreement: a software developer's favorite!)_ Haha, feel free to close this issue, and thank you for taking the time to respond!

kerem referenced this issue

2026-03-07 20:06:27 +03:00

[GH-ISSUE #551] Rules.md does not show up in chrome #2296