starred/markdownlint

Fork 0

mirror of https://github.com/DavidAnson/markdownlint.git synced 2026-04-25 01:05:55 +03:00

[GH-ISSUE #1957] MD022: Consider adding parameter to require blank lines between front matter and first heading #2635

New issue

Open

opened 2026-03-07 20:09:34 +03:00 by kerem · 4 comments

kerem commented

2026-03-07 20:09:34 +03:00

Owner

Originally created by @thompson-tomo on GitHub (Feb 14, 2026).
Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/1957

What did you do?

My markdown looks like

---
title: page title
---
## Content

What did you expect to happen?

When I run markdownlint I expected a MD022 violation to have been raised due to no space before header.

What actually happened?

No violations were reported

Originally created by @thompson-tomo on GitHub (Feb 14, 2026). Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/1957  ## What did you do? My markdown looks like ```markdown --- title: page title --- ## Content ``` ## What did you expect to happen? When I run markdownlint I expected a MD022 violation to have been raised due to no space before header. ## What actually happened? No violations were reported

kerem added the

enhancement

label

2026-03-07 20:09:34 +03:00

kerem commented

2026-03-07 20:09:34 +03:00

Author

Owner

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

Front matter like that is removed by tooling and not considered part of the Markdown document. As far as the parser is concerned, the document starts its first line with the heading.

I see why this looks like a failure of the rule, but I do not think it is meaningful in the context of the rule's intent which is to make sure that headings are always recognized as such.

https://github.com/DavidAnson/markdownlint/blob/main/doc/md022.md

@DavidAnson commented on GitHub (Feb 14, 2026): Front matter like that is removed by tooling and not considered part of the Markdown document. As far as the parser is concerned, the document starts its first line with the heading. I see why this looks like a failure of the rule, but I do not think it is meaningful in the context of the rule's intent which is to make sure that headings are always recognized as such. https://github.com/DavidAnson/markdownlint/blob/main/doc/md022.md

kerem commented

2026-03-07 20:09:35 +03:00

Author

Owner

@thompson-tomo commented on GitHub (Feb 14, 2026):

I understand, but note for other rules we have an option to consider front matter. Could we do similar here and add an option to consider front matter?

@thompson-tomo commented on GitHub (Feb 14, 2026): I understand, but note for other rules we have an option to consider front matter. Could we do similar here and add an option to consider front matter?

kerem commented

2026-03-07 20:09:35 +03:00

Author

Owner

@dgenio commented on GitHub (Feb 17, 2026):

+1 on this enhancement. I maintain a prompt library repo (my_prompts)
that uses YAML frontmatter extensively — every markdown file starts with --- delimited metadata.

We currently have MD022 entirely disabled in our .markdownlint.json because of this
exact interaction. We'd love to re-enable it with frontmatter awareness.

Our config also disables MD041 (first line should be top-level heading) for the same
reason — frontmatter is always line 1, not a heading. If this enhancement moves forward,
it might be worth considering a similar frontmatter-aware parameter for MD041 as well.

Concrete use case: we have ~30+ prompt files, all following this structure:

---
title: My Prompt
category: coding
tags: [python, testing]
version: "1.0.0"
---

## Purpose
...

We want MD022 to enforce blank lines around ## Purpose and other headings,
but NOT flag the transition from the closing --- to the first heading.
An optional parameter like frontmatter_spacing: true/false or
lines_above_from_front_matter: 1 would let us re-enable MD022 properly.

Happy to help test or contribute a PR if the approach is agreed upon.

@dgenio commented on GitHub (Feb 17, 2026): +1 on this enhancement. I maintain a prompt library repo ([my_prompts](https://github.com/dgenio/my_prompts)) that uses YAML frontmatter extensively — every markdown file starts with `---` delimited metadata. We currently have `MD022` entirely disabled in our `.markdownlint.json` because of this exact interaction. We'd love to re-enable it with frontmatter awareness. Our config also disables `MD041` (first line should be top-level heading) for the same reason — frontmatter is always line 1, not a heading. If this enhancement moves forward, it might be worth considering a similar frontmatter-aware parameter for MD041 as well. Concrete use case: we have ~30+ prompt files, all following this structure: --- title: My Prompt category: coding tags: [python, testing] version: "1.0.0" --- ## Purpose ... We want MD022 to enforce blank lines around `## Purpose` and other headings, but NOT flag the transition from the closing `---` to the first heading. An optional parameter like `frontmatter_spacing: true/false` or `lines_above_from_front_matter: 1` would let us re-enable MD022 properly. Happy to help test or contribute a PR if the approach is agreed upon.

kerem commented

2026-03-07 20:09:35 +03:00

Author

Owner

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

MD041 reports no issues for the example above:

https://dlaa.me/markdownlint/#%25m---%0Atitle%3A%20My%20Prompt%0Acategory%3A%20coding%0Atags%3A%20%5Bpython%2C%20testing%5D%0Aversion%3A%20%221.0.0%22%0A---%0A%0A%23%23%20Purpose%0A

@DavidAnson commented on GitHub (Feb 17, 2026): MD041 reports no issues for the example above: https://dlaa.me/markdownlint/#%25m---%0Atitle%3A%20My%20Prompt%0Acategory%3A%20coding%0Atags%3A%20%5Bpython%2C%20testing%5D%0Aversion%3A%20%221.0.0%22%0A---%0A%0A%23%23%20Purpose%0A