0
# remark-lint
1

2
remark-lint is a remark plugin that adds support for configuration comments to control remark lint rule messages. It serves as the foundational plugin that enables ignoring lint warnings through HTML comments and provides the core infrastructure for the entire remark-lint ecosystem.
3

4
## Package Information
5

6
- **Package Name**: remark-lint
7
- **Package Type**: npm
8
- **Language**: JavaScript (ESM)
9
- **Installation**: `npm install remark-lint`
10

11
## Core Imports
12

13
```javascript
14
import remarkLint from 'remark-lint';
15
```
16

17
For Deno:
18

19
```javascript
20
import remarkLint from 'https://esm.sh/remark-lint@10';
21
```
22

23
For browsers:
24

25
```html
26
<script type="module">
27
  import remarkLint from 'https://esm.sh/remark-lint@10?bundle';
28
</script>
29
```
30

31
## Basic Usage
32

33
```javascript
34
import remarkLint from 'remark-lint';
35
import remarkParse from 'remark-parse';
36
import remarkStringify from 'remark-stringify';
37
import {read} from 'to-vfile';
38
import {unified} from 'unified';
39
import {reporter} from 'vfile-reporter';
40

41
const file = await read('example.md');
42

43
await unified()
44
  .use(remarkParse)
45
  .use(remarkLint)
46
  .use(remarkStringify)
47
  .process(file);
48

49
console.error(reporter(file));
50
```
51

52
## Architecture
53

54
remark-lint follows the unified plugin architecture:
55

56
- **Plugin Function**: Main export that integrates with unified processors
57
- **Message Control**: Uses remark-message-control to handle configuration comments
58
- **Lint Infrastructure**: Provides the foundation for all remark-lint rules to operate consistently
59
- **Configuration Comments**: Enables HTML-style comments to control lint behavior on a per-document basis
60

61
## Capabilities
62

63
### Configuration Comment Support
64

65
The core capability that enables authors to ignore or control lint messages using HTML comments embedded in markdown documents.
66

67
```javascript { .api }
68
/**
69
 * Add support for configuration comments to control remark lint rule messages.
70
 * This is the main and only export of the remark-lint package.
71
 * 
72
 * When used as a unified plugin, this function registers a transformer that enables
73
 * configuration comments like <!--lint ignore--> in markdown documents.
74
 * The function calls this.use() internally to register the message control transformer.
75
 * 
76
 * @this {Processor} - Unified processor instance (plugin is bound to this context)
77
 * @returns {undefined} - No explicit return value (modifies processor via this.use())
78
 */
79
export default function remarkLint(): undefined;
80
```
81

82
**Configuration Comment Syntax:**
83

84
```html
85
<!-- Ignore all lint rules for the next content -->
86
<!--lint ignore-->
87

88
<!-- Disable specific rule -->
89
<!--lint disable rule-name-->
90

91
<!-- Enable specific rule -->
92
<!--lint enable rule-name-->
93

94
<!-- Disable multiple rules -->
95
<!--lint disable rule-name-1 rule-name-2-->
96
```
97

98
**Usage with Lint Rules:**
99

100
```javascript
101
import {unified} from 'unified';
102
import remarkParse from 'remark-parse';
103
import remarkLint from 'remark-lint';
104
import remarkLintFinalNewline from 'remark-lint-final-newline';
105
import remarkLintNoHeadingPunctuation from 'remark-lint-no-heading-punctuation';
106

107
const processor = unified()
108
  .use(remarkParse)
109
  .use(remarkLint)  // Must be included for comment support
110
  .use(remarkLintFinalNewline)
111
  .use(remarkLintNoHeadingPunctuation);
112

113
const file = await processor.process(markdownContent);
114
```
115

116
**Integration Patterns:**
117

118
```javascript
119
// Can be used before lint rules
120
const processor1 = unified()
121
  .use(remarkParse)
122
  .use(remarkLint)
123
  .use(remarkLintFinalNewline);
124

125
// Can be used after lint rules  
126
const processor2 = unified()
127
  .use(remarkParse)
128
  .use(remarkLintFinalNewline)
129
  .use(remarkLint);
130

131
// Both patterns provide identical functionality
132
```
133

134
**Rule Configuration:**
135

136
```javascript
137
// Rules can be configured with severity levels
138
unified()
139
  .use(remarkParse)
140
  .use(remarkLint)
141
  .use(remarkLintFinalNewline, [2])  // Error level (fatal)
142
  .use(remarkLintNoHeadingPunctuation, true)  // Warning level
143
  .use(remarkLintNoUndefinedReferences, false);  // Disabled
144
```
145

146
## Types
147

148
```javascript { .api }
149
/**
150
 * Internal helper function that configures remark-message-control.
151
 * This function is not directly exported but is used internally by remarkLint.
152
 * It calls remarkMessageControl with the appropriate configuration for lint messages.
153
 * 
154
 * @returns {Function} Transform function from remark-message-control configured for lint
155
 */
156
function lintMessageControl(): Function;
157
```
158

159
## Error Handling
160

161
remark-lint integrates with the vfile message system to provide consistent error reporting:
162

163
- **Message Structure**: All lint messages include line/column positions, rule IDs, and source attribution
164
- **Severity Levels**: Support for warning (1) and error (2) severity levels
165
- **Rule Attribution**: Messages include ruleId and source fields for identification
166
- **URL References**: Messages can include URLs to rule documentation
167

168
**Example Error Output:**
169

170
```
171
virtual.md:3:1-3:24: Unexpected character `.` at end of heading, remove it
172
  3:1-3:24  warning  no-heading-punctuation  remark-lint
173
```
174

175
## Compatibility
176

177
- **Node.js**: 16+ (ESM only)
178
- **Unified**: Compatible with unified 11.0.0+
179
- **remark**: Works with all remark parsers and compilers
180
- **Ecosystem**: Foundation for 80+ specialized lint rule packages
181

182
## Dependencies
183

184
- **@types/mdast**: ^4.0.0 - TypeScript definitions for mdast syntax tree
185
- **remark-message-control**: ^8.0.0 - Core message control functionality  
186
- **unified**: ^11.0.0 - Plugin architecture foundation