rumdl 0.2.63

A fast Markdown linter and formatter written in Rust
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145

# MD041 - Start Your Document with a Clear Title

Aliases: `first-line-heading`, `first-line-h1`

## What this rule does

Ensures every document begins with a top-level heading (like `# Title`), giving your document a clear title and purpose from the start.

## Why this matters

- **Professional appearance**: Documents without titles look incomplete and unprofessional
- **Better navigation**: Readers and tools can quickly identify what the document is about
- **Improved SEO**: Search engines and documentation systems rely on document titles
- **Consistent structure**: All documents in your project will have a uniform starting point

## Examples

### ✅ Correct

```markdown
# Getting Started Guide

Welcome to our documentation! This guide will help you...
```

```markdown
# Project README

This project provides tools for...
```

Also correct with HTML headings:

```markdown
<h1>Getting Started Guide</h1>

Welcome to our documentation! This guide will help you...
```

Also correct with HTML comments before the heading:

```markdown
<!-- This is a comment -->
# Getting Started Guide

Welcome to our documentation! This guide will help you...
```

### ❌ Incorrect

```markdown
Welcome to our documentation! This guide will help you...

## Installation

First, install the dependencies...
```

```markdown
This project provides tools for...

Some more content here.
```

### 🔧 Fixed

```markdown
# Documentation

Welcome to our documentation! This guide will help you...

## Installation

First, install the dependencies...
```

## Configuration

```toml
[MD041]
level = 1  # Heading level required (1-6, default: 1)
front-matter-title = "title"  # Front matter field to use as title
front-matter-title-pattern = "^(title|header):"  # Regex pattern to match title fields in front matter
allow-preamble = false  # Allow content before the first heading (default: false)
fix = false  # Enable auto-fix (default: false)
```

### `allow-preamble`

With `allow-preamble = true`, the document no longer has to *open* with a heading. The rule instead finds the document's first top-level heading and checks its level:

```markdown
A short introduction before the title.

# Getting Started Guide
```

That document is clean with `allow-preamble = true` and flagged without it. A wrong level is still reported, at the line of the heading itself rather than line 1:

```markdown
A short introduction before the title.

## Getting Started Guide
```

A document with no top-level heading at all is **not** flagged when `allow-preamble = true`. Headings that only appear inside a container (a list, a blockquote, an HTML block) do not count as the document's first heading, so a document whose only heading is nested is treated the same as one with no heading.

## Automatic fixes

By default, this rule does not provide automatic fixes because adding a document title is typically a content decision. However, you can enable opt-in auto-fix with `fix = true`.

When enabled, the fixer will:

1. **Fix wrong heading level**: If the first content is a heading with the wrong level (e.g., `## Title` when level 1 is required), rewrite it to the correct level (`# Title`)
2. **Move heading above preamble**: If a heading appears after only "preamble" (blank lines, HTML comments), move it to the start of the content
3. **Promote a title line**: If the document has no heading and its first content line looks like a title (at most 80 characters, not ending in `.`, `?`, `!`, `:` or `;`, and followed by a blank line or the end of the file), turn that line into a heading of the required level. Only a paragraph line qualifies: a list item, blockquote, thematic break, code fence or indented code line is reported but never promoted, because prefixing `#` would rewrite that construct
4. **Insert a title from the file name**: If the document has no heading and no title line, and holds only directive blocks (such as admonitions and content tabs), insert a heading derived from the file name, with kebab-case and underscores converted to Title Case

With `allow-preamble = true` the fixer only ever does the first of these: the heading is rewritten to the required level where it stands. Moving it to the top would delete the preamble that the option exists to permit.

The fixer will **not** change content when:

- The document has no heading and opens with a body paragraph (a line that is not a title candidate)
- Real content appears before the first heading (unsafe to move)
- The document already has the correct heading at the correct position

## Special cases

- Documents with front matter containing a title field are considered valid
- Empty documents are not checked
- HTML comments at the start are ignored when checking
- HTML heading tags (e.g., `<h1>Title</h1>`) are recognized as valid headings
- The `front-matter-title-pattern` allows custom regex patterns for matching title fields
- In MkDocs flavor, anchor lines like `[](){ #anchor }` are skipped as non-content

## Learn more

- [CommonMark specification for headings](https://spec.commonmark.org/0.31.2/#atx-headings)
- [Writing good documentation titles](https://www.writethedocs.org/guide/writing/beginners-guide-to-docs/#structure)

## Related rules

- [MD001](md001.md) - Keep heading levels organized
- [MD003](md003.md) - Use consistent heading styles
- [MD025](md025.md) - Use only one main title per document