Rule - MD002

Property	Value
Aliases	md002, first-heading-h1, first-header-h1
Autofix Available	No
Enabled By Default	No

Deprecation

This rule has been deprecated in favor of Rule Md041.

Summary

First heading of the document should be a top-level heading.

Reasoning

Consistency

In most cases, the top-level heading of a document is used as the title of that document. Therefore, the first heading in the document should be a level 1 header to reflect that reality.

Examples

Failure Scenarios

This rule triggers when the first heading in the document is not a level 1 heading in either an Atx Heading format:

```Markdown

This isn't an Atx H1 heading

```

or a SetExt Heading format:

```Markdown This isn't a SetExt H1 heading

---

```

Correct Scenarios

This rule does not trigger when there is a single level increase between heading items or any decrease of the heading levels, as follows:

```Markdown

This is an Atx H1 heading

```

or:

Markdown This is a SetExt H1 heading ===

Note that configuration may be applied to change the expected top-level of this rule from its default of 1 to another value. This should only be done if an external process is generating the title of the document. For example, if the level configuration value is set to 2, then the following document will not trigger this rule:

```Markdown

This isn't an Atx H1 heading

```

Fix Description

The reason for not being able to auto-fix this rule is its deprecation in favor of Rule Md041

Configuration

Prefixes
plugins.md002.
plugins.first-heading-h1.
plugins.first-header-h1.

Value Name	Type	Default	Description
enabled	boolean	False	Whether the Rule Plugin is enabled.
level	integer	1	Level that is expected from the first heading (Atx or SetExt) in the document.

Origination of Rule

This rule is largely inspired by the MarkdownLint rule Md002, which is in turn inspired by this article.