question-mark
Stuck on an issue?

Lightrun Answers was designed to reduce the constant googling that comes with debugging 3rd party libraries. It collects links to all the places you might be looking at while hunting down a tough bug.

And, if you’re still stuck at the end, we’re happy to hop on a call to see how we can help out.

MD041: errors when using html's `h1` instead of `#` in most cases

See original GitHub issue

With the rule MD041 (first-line-heading) enabled:

  • no error using #
    • simple code:

      # title
      test test
      ## test level 2
      

      rendered:

      title

      test test

      test level 2

    • image as title code:

      # ![](https://via.placeholder.com/200x100)
      
      test test
      
      ## test level 2
      

      rendered:

      test test

      test level 2

    • centered image as title using p and img code:

      # <p align="center"><img src="https://via.placeholder.com/200x100"></p>
      
      test test
      
      ## test level 2
      

      rendered (note: this renders differently in github readmes than comments; the heading line below the image here is above the image in readmes (which is not what we want in general)):

      test test

      test level 2

    • centered image as title using h1 and img (this has two level-1 headings in one line and also (correctly) renders two heading lines, both is not nice) code:

      # <h1 align="center"><img src="https://via.placeholder.com/200x100"></h1>
      
      test test
      
      ## test level 2
      

      rendered:

      test test

      test level 2

  • no error using h1
    • it’s okay with h1 stuff as long as something with # comes after it code:
      <h1>title</h1>
      # title
      test test
      ## test level 2
      
      rendered:

      title

      # title

      test test

      test level 2

  • error using h1
    • simple code:

      <h1>title</h1>
      test test
      ## test level 2
      

      rendered:

      title

      test test

      test level 2

    • image as title code:

      <h1><img src="https://via.placeholder.com/200x100"></h1>
      
      test test
      
      ## test level 2
      

      rendered:

      test test

      test level 2


While I know that using h1 instead of # is not “pure” and that using images as titles is kinda weird, both are often seen in GitHub readme files for a reason. The first one because you can’t center #, but you can center h1 (<h1 align="center">title</h1>). The second one because the first image (or even the first “thing”) in a readme often is the logo, which includes the project name most of the time, so it feels kinda redundant to have the name of your project above the logo of your project which includes the name of your project again.

Issue Analytics

  • State:closed
  • Created 3 years ago
  • Comments:5 (2 by maintainers)

github_iconTop GitHub Comments

1reaction
DavidAnsoncommented, Jan 12, 2021

I kind of feel like this is an abuse of Markdown, but it may be straightforward to add and I’ll have a look.

0reactions
DavidAnsoncommented, Feb 10, 2021

Yes

Read more comments on GitHub >

github_iconTop Results From Across the Web

markdownlint/Rules.md at main - GitHub
Start with an H1 heading ## Then use an H2 for subsections. Note: The level parameter can be ... Some text * Spaces...
Read more >
Markdownlint Rules
MD041 /first-line-heading offers an improved implementation. This rule is intended to ensure document headings start at the top level and is triggered when...
Read more >
rushstack/rushstack - Gitter
My understanding for why markdownlint recommends in-order HTML header cascade is ... to prevent this mistake by using rush install instead of rush...
Read more >
markdownlint - npm
A Node.js style checker and lint tool for Markdown/CommonMark files.. Latest version: 0.26.2, last published: 4 months ago. Start using ...
Read more >
markdownlint/README.md - UNPKG
27, tool for [Node.js](https://nodejs.org/) with a library of rules ... 98, * **[MD041](doc/Rules.md#md041)** *first-line-heading/first-line-h1* - First ...
Read more >

github_iconTop Related Medium Post

No results found

github_iconTop Related StackOverflow Question

No results found

github_iconTroubleshoot Live Code

Lightrun enables developers to add logs, metrics and snapshots to live code - no restarts or redeploys required.
Start Free

github_iconTop Related Reddit Thread

No results found

github_iconTop Related Hackernoon Post

No results found

github_iconTop Related Tweet

No results found

github_iconTop Related Dev.to Post

No results found

github_iconTop Related Hashnode Post

No results found