starred/markdownlint

Fork 0

mirror of https://github.com/DavidAnson/markdownlint.git synced 2026-04-26 01:36:03 +03:00

[GH-ISSUE #1972] First line ... a top-level heading, but what about a funky logo with an alt text instead? (Rule MD041) #793

New issue

Closed

opened 2026-03-03 01:29:54 +03:00 by kerem · 6 comments

kerem commented

2026-03-03 01:29:54 +03:00

Owner

Originally created by @binarykitchen on GitHub (Feb 20, 2026).
Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/1972

Awesome library and great work so far. Totally helped our project very much 🙌

I'm just questioning this rule MD041:
https://github.com/DavidAnson/markdownlint/blob/main/doc/md041.md

Text first isn't very attractive nor inviting. I think an image with alt text as a first like should be accepted as well from a marketing perspective.
And my project is visually oriented for Deaf users, so, has to be an image first.

The first thing in our README.md is the logo image itself, see this example:

And the markdown is:

I've read your documentation and couldn't find any solutions. I am using your latest version:

"eslint-plugin-markdownlint": "0.9.0",

And this is in our ESLint config:

  {
    files: ["**/*md"],
    plugins: {
      markdownlint: markdownlintPlugin,
    },
    languageOptions: {
      parser: markdownlintParser,
    },
    rules: {
      ...markdownlintPlugin.configs.recommended.rules,
      "markdownlint/md013": "off",
      "markdownlint/md041": "off",
    },
  },

Happy to discuss further. Thanks again :)

Originally created by @binarykitchen on GitHub (Feb 20, 2026). Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/1972 Awesome library and great work so far. Totally helped our project very much 🙌 I'm just questioning this rule MD041: https://github.com/DavidAnson/markdownlint/blob/main/doc/md041.md Text first isn't very attractive nor inviting. I think an image with alt text as a first like should be accepted as well from a marketing perspective. And my project is visually oriented for Deaf users, so, has to be an image first. The first thing in our README.md is the logo image itself, see this example: <img width="940" height="334" alt="Image" src="https://github.com/user-attachments/assets/3dd46e20-2b9e-4843-9846-c2b0291b2ea8" /> And the markdown is: <img width="1048" height="311" alt="Image" src="https://github.com/user-attachments/assets/7ba65aa6-dcd7-4d10-92be-e08a4f677912" /> I've read your documentation and couldn't find any solutions. I am using your latest version: ``` "eslint-plugin-markdownlint": "0.9.0", ``` And this is in our ESLint config: ```ts { files: ["**/*md"], plugins: { markdownlint: markdownlintPlugin, }, languageOptions: { parser: markdownlintParser, }, rules: { ...markdownlintPlugin.configs.recommended.rules, "markdownlint/md013": "off", "markdownlint/md041": "off", }, }, ``` Happy to discuss further. Thanks again :)

kerem

2026-03-03 01:29:54 +03:00

closed this issue
added the
question
label

kerem commented

2026-03-03 01:29:55 +03:00

Author

Owner

@DavidAnson commented on GitHub (Feb 20, 2026):

Buy omitting a top-level heading at the beginning of the document, you are violating accessibility guidelines such as these:

You are welcome to do so as appropriate for your scenario. If so, I suggest disabling this rule for the relevant documents/project OR considering the HTML approach outlined in the documentation you link to.

@DavidAnson commented on GitHub (Feb 20, 2026): Buy omitting a top-level heading at the beginning of the document, you are violating accessibility guidelines such as these: - https://usability.yale.edu/web-accessibility/articles/headings - https://www.w3.org/WAI/tutorials/page-structure/headings/ You are welcome to do so as appropriate for your scenario. If so, I suggest disabling this rule for the relevant documents/project OR considering the HTML approach outlined in the documentation you link to.

kerem commented

2026-03-03 01:29:55 +03:00

Author

Owner

@binarykitchen commented on GitHub (Feb 20, 2026):

Thanks, @DavidAnson

(the https://usability.yale.edu link does not work - server down?)

you are violating accessibility guidelines such as these ...

How about we take a step back? I am Deaf myself and have used HTML for over 30 years.
Fun question: can you add an image with an alt text/title in a <h1> heading in Markdown format?

I suggest disabling this rule for the relevant

I could, but don't want to. It's like running away from a productive discussion, neglecting the root cause.

I do totally honour Tim Berners-Lee vision re: HTML, yet at the same time it's 2026 now while accessibility becomes a bigger issue than before.

Again, I wonder if it's doable to have a first heading with an alt text and image, both? There are plenty of GitHub repositories out there having an image/logo first.

@binarykitchen commented on GitHub (Feb 20, 2026): Thanks, @DavidAnson (the https://usability.yale.edu link does not work - server down?) > you are violating accessibility guidelines such as these ... How about we take a step back? I am Deaf myself and have used HTML for over 30 years. Fun question: can you add an image with an alt text/title in a `<h1>` heading in Markdown format? > I suggest disabling this rule for the relevant I could, but don't want to. It's like running away from a productive discussion, neglecting the root cause. I do totally honour Tim Berners-Lee vision re: HTML, yet at the same time it's 2026 now while accessibility becomes a bigger issue than before. Again, I wonder if it's doable to have a first heading with an alt text and image, both? There are plenty of GitHub repositories out there having an image/logo first.

kerem commented

2026-03-03 01:29:55 +03:00

Author

Owner

@DavidAnson commented on GitHub (Feb 20, 2026):

(the https://usability.yale.edu link does not work - server down?)

Still works for me. It's the top hit of a Google query for "html h1 best practices accessibility yale" if that's easier.

Fun question: can you add an image with an alt text/title in a <h1> heading in Markdown format?

Yes, this is shown and explained in the rule documentation you link to and I reference at the end of my earlier reply.

Again, I wonder if it's doable to have a first heading with an alt text and image, both? There are plenty of GitHub repositories out there having an image/logo first.

Yes, and the prevalence of the technique is specifically why this rule allows the h1/img approach.

@DavidAnson commented on GitHub (Feb 20, 2026): > (the https://usability.yale.edu link does not work - server down?) Still works for me. It's the top hit of a Google query for "html h1 best practices accessibility yale" if that's easier. > Fun question: can you add an image with an alt text/title in a `<h1>` heading in Markdown format? Yes, this is shown and explained in the rule documentation you link to and I reference at the end of my earlier reply. > Again, I wonder if it's doable to have a first heading with an alt text and image, both? There are plenty of GitHub repositories out there having an image/logo first. Yes, and the prevalence of the technique is specifically why this rule allows the h1/img approach.

kerem commented

2026-03-03 01:29:55 +03:00

Author

Owner

@binarykitchen commented on GitHub (Feb 20, 2026):

The link works now, must have been a network issue.

I've managed it with

# ![logo](src/client/assets/img/logo.png)

But how can I add an ALT text in here?

@binarykitchen commented on GitHub (Feb 20, 2026): The link works now, must have been a network issue. I've managed it with ```markdown # ![logo](src/client/assets/img/logo.png) ``` But how can I add an ALT text in here?

kerem commented

2026-03-03 01:29:55 +03:00

Author

Owner

@DavidAnson commented on GitHub (Feb 21, 2026):

That's typically what the image description ("logo") is used for: https://spec.commonmark.org/0.31.2/#images

@DavidAnson commented on GitHub (Feb 21, 2026): That's typically what the image description ("logo") is used for: https://spec.commonmark.org/0.31.2/#images

kerem commented

2026-03-03 01:29:55 +03:00

Author

Owner

@binarykitchen commented on GitHub (Feb 21, 2026):

That's typically what the image description ("logo") is used for: spec.commonmark.org/0.31.2#images

Nice, I didn't know about that. Thank you very much.

@binarykitchen commented on GitHub (Feb 21, 2026): > That's typically what the image description ("logo") is used for: [spec.commonmark.org/0.31.2#images](https://spec.commonmark.org/0.31.2/#images) Nice, I didn't know about that. Thank you very much.

kerem referenced this issue

2026-03-03 02:01:31 +03:00

[PR #793] [MERGED] Bump eslint-plugin-jsdoc from 43.0.7 to 43.1.1 #1017

kerem referenced this issue

2026-03-07 20:10:57 +03:00

[PR #793] [MERGED] Bump eslint-plugin-jsdoc from 43.0.7 to 43.1.1 #2863