starred/markdownlint

Fork 0

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

[GH-ISSUE #366] MD041: errors when using html's `h1` instead of `#` in most cases #309

New issue

Closed

opened 2026-03-03 01:25:35 +03:00 by kerem · 5 comments

kerem commented

2026-03-03 01:25:35 +03:00

Owner

Originally created by @nnmrts on GitHub (Jan 12, 2021).
Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/366

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.

Originally created by @nnmrts on GitHub (Jan 12, 2021). Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/366 With the rule MD041 (first-line-heading) enabled: - no error using `#` - simple code: ```md # title test test ## test level 2 ``` rendered: > # title > > test test > > ## test level 2 - image as title code: ```md # ![](https://via.placeholder.com/200x100) test test ## test level 2 ``` rendered: > # ![](https://via.placeholder.com/200x100) > > test test > > ## test level 2 - centered image as title using `p` and `img` code: ```md # <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)): > # <p align="center"><img src="https://via.placeholder.com/200x100"></p> > > 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: ```md # <h1 align="center"><img src="https://via.placeholder.com/200x100"></h1> test test ## test level 2 ``` rendered: > # <h1 align="center"><img src="https://via.placeholder.com/200x100"></h1> > > test test > > ## test level 2 - no error using h1 - it's okay with `h1` stuff as long as something with `#` comes after it code: ```md <h1>title</h1> # title test test ## test level 2 ``` rendered: > <h1>title</h1> > # title > > test test > > ## test level 2 - error using h1 - simple code: ```md <h1>title</h1> test test ## test level 2 ``` rendered: > <h1>title</h1> > > test test > > ## test level 2 - image as title code: ```md <h1><img src="https://via.placeholder.com/200x100"></h1> test test ## test level 2 ``` rendered: > <h1><img src="https://via.placeholder.com/200x100"></h1> > > 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.

kerem

2026-03-03 01:25:35 +03:00

closed this issue
added the
enhancement

fixed in next
labels

kerem commented

2026-03-03 01:25:36 +03:00

Author

Owner

@nnmrts commented on GitHub (Jan 12, 2021):

I'm writing a new comment here so I don't have to edit the original issue again (sorry):

Is there a rationale behind the rule just accepting # and not h1 as well? I would suggest either:

change the current rule to also accept h1 as top level heading
add a new rule which determines if html headings are allowed (and have the same meaning) instead of markdown headings

@nnmrts commented on GitHub (Jan 12, 2021): I'm writing a new comment here so I don't have to edit the original issue again (sorry): Is there a rationale behind the rule just accepting `#` and not `h1` as well? I would suggest either: - change the current rule to also accept h1 as top level heading - add a new rule which determines if html headings are allowed (and have the same meaning) instead of markdown headings

kerem commented

2026-03-03 01:25:36 +03:00

Author

Owner

@DavidAnson commented on GitHub (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.

@DavidAnson commented on GitHub (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.

kerem commented

2026-03-03 01:25:37 +03:00

Author

Owner

@nnmrts commented on GitHub (Jan 12, 2021):

@DavidAnson I agree. As I said, this is not pure, and it is far from beautiful too. If there was a way to center images (or anything at all) in markdown on GitHub, I (and many others) would definitely use it before even considering using html tags. There is so much potential for styling markdown on GitHub, but after years of proposals and ideas to support a limited version of the style attribute or some sort of inline class attributes on their end, it seems like they just don't want to go in that direction with markup, I guess.

Normally this wouldn't be in the scope of markdownlint at all, and I'd fully understand if this rule never gets changed. But in my mind and since using html to do stuff markdown can't do is a common practice, this would be a great change.

@nnmrts commented on GitHub (Jan 12, 2021): @DavidAnson I agree. As I said, this is not pure, and it is far from beautiful too. If there was a way to center images (or anything at all) in markdown on GitHub, I (and many others) would definitely use it before even considering using html tags. There is so much potential for styling markdown on GitHub, but after years of proposals and ideas to support a limited version of the `style` attribute or some sort of inline `class` attributes on their end, it seems like they just don't want to go in that direction with markup, I guess. Normally this wouldn't be in the scope of markdownlint at all, and I'd fully understand if this rule never gets changed. But in my mind and since using html to do stuff markdown can't do is a common practice, this would be a great change.

kerem commented

2026-03-03 01:25:37 +03:00

Author

Owner

@MichaIng commented on GitHub (Feb 10, 2021):

Ah nice, many thanks, we suffer from this issue just now. I hope for a soon release of markdownlint-cli2 to contain this change?

@MichaIng commented on GitHub (Feb 10, 2021): Ah nice, many thanks, we suffer from this issue just now. I hope for a soon release of markdownlint-cli2 to contain this change?

kerem commented

2026-03-03 01:25:37 +03:00

Author

Owner

@DavidAnson commented on GitHub (Feb 10, 2021):

Yes

@DavidAnson commented on GitHub (Feb 10, 2021): Yes

kerem referenced this issue

2026-03-07 20:04:43 +03:00

[GH-ISSUE #309] [MD036] exclude **Table of Contents** by default or make it configurable #2115