[GH-ISSUE #380] MD041 and github templates #319

New issue

Closed

opened 2026-03-03 01:25:42 +03:00 by kerem · 3 comments

kerem commented

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

Owner

Originally created by @hepcat72 on GitHub (Mar 24, 2021).
Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/380

I have a question. I created github templates for issues and pull requests and I'm confused about the default behavior of MD041.

The following github-recognized default-generated templates for github issues do not trigger an MD041 error:

---
name: Bug Report
about: Create a report to help us improve
title: ''
labels: bug
assignees: ''

---

## BUG DESCRIPTION

### Problem

A bird's-eye summation of what the problem is.

...

Github handles the ----delimited portion so that issue submitters do not see it. Their default pull request template however, does not include this ----delimited section, and if you add one (there is no MD041 error but), submitters will see this section. If I remove this section, the MD041 error occurs.

I feel that an h1 is too big for the PR template. Is there a work-around so that other docs require an h1, but the PR template doesn't have to have one?

Originally created by @hepcat72 on GitHub (Mar 24, 2021). Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/380 I have a question. I created github templates for issues and pull requests and I'm confused about the default behavior of MD041. The following github-recognized default-generated templates for github issues do not trigger an MD041 error: ``` --- name: Bug Report about: Create a report to help us improve title: '' labels: bug assignees: '' --- ## BUG DESCRIPTION ### Problem A bird's-eye summation of what the problem is. ... ``` Github handles the `---`-delimited portion so that issue submitters do not see it. Their default pull request template however, does not include this `---`-delimited section, and if you add one (there is no MD041 error *but*), submitters will see this section. If I remove this section, the MD041 error occurs. I feel that an `h1` is too big for the PR template. Is there a work-around so that other docs require an `h1`, but the PR template doesn't have to have one?

kerem

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

closed this issue
added the
question
label

kerem commented

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

Author

Owner

@DavidAnson commented on GitHub (Mar 24, 2021):

My suggestion might be to use an inline comment to customize the exceptional file: https://github.com/DavidAnson/markdownlint#configuration

Something like this at the bottom of the template should do what you want without getting in the way: 

@DavidAnson commented on GitHub (Mar 24, 2021): My suggestion might be to use an inline comment to customize the exceptional file: https://github.com/DavidAnson/markdownlint#configuration Something like this at the bottom of the template should do what you want without getting in the way: ``

kerem commented

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

Author

Owner

@QuAzI commented on GitHub (Sep 10, 2022):

MD041 looks wrong because all note software (QOwnNotes, Obsidian, Foam...) use --- to split title (HEAD) of document and h1...5 just for sectioning BODY

Some title
---

File content

@QuAzI commented on GitHub (Sep 10, 2022): MD041 looks wrong because all note software (QOwnNotes, Obsidian, Foam...) use `---` to split title (HEAD) of document and h1...5 just for sectioning BODY ``` Some title --- File content ```

kerem commented

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

Author

Owner

@DavidAnson commented on GitHub (Sep 10, 2022):

That syntax creates a second-level/H2 heading. Rule MD041 advocates for a top-level/H1 heading as the first line of the document. As such, I believe it is correct to report your example as a violation.

https://spec.commonmark.org/0.30/#setext-headings

https://cirosantilli.com/markdown-style-guide/#top-level-header

http://markdown-it.github.io/#md3=%7B%22source%22%3A%22Some%20title%5Cn---%5Cn%5CnFile%20content%22%2C%22defaults%22%3A%7B%22html%22%3Afalse%2C%22xhtmlOut%22%3Afalse%2C%22breaks%22%3Afalse%2C%22langPrefix%22%3A%22language-%22%2C%22linkify%22%3Atrue%2C%22typographer%22%3Atrue%2C%22_highlight%22%3Atrue%2C%22_strict%22%3Afalse%2C%22_view%22%3A%22src%22%7D%7D

@DavidAnson commented on GitHub (Sep 10, 2022): That syntax creates a second-level/H2 heading. Rule MD041 advocates for a top-level/H1 heading as the first line of the document. As such, I believe it is correct to report your example as a violation. https://spec.commonmark.org/0.30/#setext-headings https://cirosantilli.com/markdown-style-guide/#top-level-header http://markdown-it.github.io/#md3=%7B%22source%22%3A%22Some%20title%5Cn---%5Cn%5CnFile%20content%22%2C%22defaults%22%3A%7B%22html%22%3Afalse%2C%22xhtmlOut%22%3Afalse%2C%22breaks%22%3Afalse%2C%22langPrefix%22%3A%22language-%22%2C%22linkify%22%3Atrue%2C%22typographer%22%3Atrue%2C%22_highlight%22%3Atrue%2C%22_strict%22%3Afalse%2C%22_view%22%3A%22src%22%7D%7D

kerem referenced this issue

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

[GH-ISSUE #319] Fixable tooling #2122