0
# remark-lint-ordered-list-marker-style
1
2
remark-lint rule to warn when the markers of ordered lists violate a given style. This package helps maintain consistency in Markdown documents by ensuring ordered lists use either dots (.) or parentheses ()) consistently throughout the document.
3
4
## Package Information
5
6
- **Package Name**: remark-lint-ordered-list-marker-style
7
- **Package Type**: npm
8
- **Language**: JavaScript (ESM)
9
- **Installation**: `npm install remark-lint-ordered-list-marker-style`
10
11
## Core Imports
12
13
```javascript
14
import remarkLintOrderedListMarkerStyle from 'remark-lint-ordered-list-marker-style';
15
```
16
17
Note: This package is ESM only and does not support CommonJS. Use dynamic imports in CommonJS environments:
18
```javascript
19
// Not supported - package is ESM only
20
// const remarkLintOrderedListMarkerStyle = require('remark-lint-ordered-list-marker-style');
21
22
// Use dynamic import instead:
23
const remarkLintOrderedListMarkerStyle = (await import('remark-lint-ordered-list-marker-style')).default;
24
```
25
26
## Basic Usage
27
28
```javascript
29
import {remark} from 'remark';
30
import remarkLint from 'remark-lint';
31
import remarkLintOrderedListMarkerStyle from 'remark-lint-ordered-list-marker-style';
32
33
const processor = remark()
34
.use(remarkLint)
35
.use(remarkLintOrderedListMarkerStyle); // Uses 'consistent' by default
36
37
const result = await processor.process(`1. First item
38
39
2) Second item (inconsistent - will warn)`);
40
41
console.error(String(result));
42
```
43
44
## Capabilities
45
46
### Ordered List Marker Style Linting
47
48
Validates that ordered list markers are consistent throughout a Markdown document.
49
50
```javascript { .api }
51
/**
52
* remark-lint rule plugin for ordered list marker consistency
53
* This is the default export - a unified plugin created with lintRule()
54
*/
55
declare const remarkLintOrderedListMarkerStyle: Plugin;
56
57
/**
58
* Plugin type that accepts standard unified lint rule configuration
59
* Supports: false (disable), true/'on' (enable), [severity, options], or direct options
60
*/
61
type Plugin = import('unified').Plugin<
62
| []
63
| [false]
64
| [true | 'on' | 'warn' | 'error' | 0 | 1 | 2]
65
| [boolean | 'on' | 'off' | 'warn' | 'error' | 0 | 1 | 2, Options?]
66
| [Options]
67
, Root>;
68
69
type Options = 'consistent' | Marker;
70
type Marker = '.' | ')';
71
```
72
73
**Configuration Options:**
74
75
- **`'consistent'` (default)**: Detects the first ordered list marker style used in the document and enforces consistency with that style throughout
76
- **`'.'`**: Enforces dot markers only (e.g., `1.`, `2.`, `3.`)
77
- **`')'`**: Enforces parenthesis markers only (e.g., `1)`, `2)`, `3)`)
78
79
**Usage Examples:**
80
81
```javascript
82
// Default behavior - consistent style detection
83
.use(remarkLintOrderedListMarkerStyle)
84
.use(remarkLintOrderedListMarkerStyle, 'consistent')
85
86
// Enforce dots only
87
.use(remarkLintOrderedListMarkerStyle, '.')
88
89
// Enforce parentheses only
90
.use(remarkLintOrderedListMarkerStyle, ')')
91
92
// Standard unified plugin configuration
93
.use(remarkLintOrderedListMarkerStyle, false) // Disable rule
94
.use(remarkLintOrderedListMarkerStyle, true) // Enable with default options
95
.use(remarkLintOrderedListMarkerStyle, [1, '.']) // Severity 1 (warn) with dots
96
.use(remarkLintOrderedListMarkerStyle, [2, ')']) // Severity 2 (error) with parens
97
.use(remarkLintOrderedListMarkerStyle, ['error', 'consistent']) // Error severity
98
```
99
100
**Error Messages:**
101
102
When inconsistencies are found, the rule reports:
103
- `"Marker style should be \`.\`"` - When dots are expected but parentheses found
104
- `"Marker style should be \`)\`"` - When parentheses are expected but dots found
105
- `"Incorrect ordered list item marker style \`<invalid>\`: use either \`'.'\` or \`')'\`"` - When invalid option provided
106
107
## Types
108
109
```javascript { .api }
110
/**
111
* MDast Root node type (from @types/mdast)
112
*/
113
type Root = import('mdast').Root;
114
115
/**
116
* Valid ordered list marker characters
117
*/
118
type Marker = '.' | ')';
119
120
/**
121
* Configuration options for the rule
122
*/
123
type Options = 'consistent' | Marker;
124
125
/**
126
* Unified plugin type supporting standard lint rule configuration
127
* Based on unified-lint-rule conventions
128
*/
129
type Plugin = import('unified').Plugin<
130
| []
131
| [false]
132
| [true | 'on' | 'warn' | 'error' | 0 | 1 | 2]
133
| [boolean | 'on' | 'off' | 'warn' | 'error' | 0 | 1 | 2, Options?]
134
| [Options]
135
, Root>;
136
137
/**
138
* Rule metadata interface (from unified-lint-rule)
139
*/
140
interface RuleMeta {
141
origin: string;
142
url?: string | null;
143
}
144
145
/**
146
* VFile interface for error reporting
147
*/
148
type VFile = import('vfile').VFile;
149
```
150
151
## Integration
152
153
### Unified Ecosystem
154
155
This package integrates seamlessly with the unified ecosystem:
156
157
- **Unified Processor**: Works with `unified()` processing pipeline
158
- **Remark**: Specifically designed for remark markdown processing
159
- **Remark-lint**: Requires `remark-lint` as the base linting framework
160
- **VFile**: Uses VFile for error reporting with position information
161
162
### Configuration in Projects
163
164
**Package.json configuration:**
165
```json
166
{
167
"remarkConfig": {
168
"plugins": [
169
"remark-lint",
170
["remark-lint-ordered-list-marker-style", "."]
171
]
172
}
173
}
174
```
175
176
**CLI usage:**
177
```bash
178
remark --use remark-lint --use remark-lint-ordered-list-marker-style example.md
179
```
180
181
### Preset Integration
182
183
This rule is included in several remark-lint presets:
184
185
- **`remark-preset-lint-consistent`**: Uses `'consistent'` setting
186
- **`remark-preset-lint-markdown-style-guide`**: Uses `'.'` setting
187
- **`remark-preset-lint-recommended`**: Uses `'.'` setting
188
189
## Error Handling
190
191
The rule handles various edge cases:
192
193
- **Generated nodes**: Ignores programmatically generated list items
194
- **Task list items**: Properly extracts markers from checkbox lists
195
- **Whitespace variations**: Handles different spacing patterns around markers
196
- **Invalid configurations**: Provides clear error messages for unsupported options
197
198
**Example error output:**
199
```text
200
3:1-3:8: Marker style should be `.`
201
```
202
203
This indicates line 3, column 1 through column 8 has a marker inconsistency.
204
205
## Implementation Notes
206
207
### How the Rule Works
208
209
The rule is built using `unified-lint-rule` and operates on the MDast (Markdown Abstract Syntax Tree):
210
211
1. **AST Traversal**: Uses `unist-util-visit` to traverse all `list` nodes in the syntax tree
212
2. **Ordered List Detection**: Filters for lists where `node.ordered === true`
213
3. **Marker Extraction**: Extracts the marker character from the source text using positional information
214
4. **Consistency Check**: Compares found markers against the configured option or established pattern
215
5. **Error Reporting**: Uses VFile to report position-specific errors
216
217
### Source Code Behavior
218
219
Key implementation details from the source:
220
221
- **Generated Node Handling**: Uses `unist-util-generated` to skip programmatically generated nodes
222
- **Task List Support**: Removes checkbox syntax (`[x]`, `[ ]`) before marker extraction using regex
223
- **Whitespace Normalization**: Strips whitespace and digits from extracted text to isolate markers
224
- **Position Tracking**: Uses `unist-util-position` for accurate error location reporting
225
226
### Rule Origin
227
228
- **Rule ID**: `remark-lint:ordered-list-marker-style`
229
- **Documentation URL**: `https://github.com/remarkjs/remark-lint/tree/main/packages/remark-lint-ordered-list-marker-style#readme`
230
231
These details are automatically added to error messages by the unified-lint-rule framework.
232
233
## Dependencies
234
235
Core dependencies required for functionality:
236
237
- **`@types/mdast`**: TypeScript definitions for Markdown AST
238
- **`unified`**: Core unified processor framework
239
- **`unified-lint-rule`**: Helper for creating lint rules
240
- **`unist-util-generated`**: Utility to check if AST nodes are generated
241
- **`unist-util-position`**: Utility for AST node position information
242
- **`unist-util-visit`**: Utility for traversing AST trees
243
244
## Compatibility
245
246
- **Node.js**: 12.20+, 14.14+, 16.0+
247
- **Environment**: ESM only (not CommonJS compatible)
248
- **Browser**: Compatible via ESM imports from CDN (esm.sh)
249
- **Deno**: Compatible via esm.sh