0
# remark-lint-hard-break-spaces
1

2
remark-lint-hard-break-spaces is a specialized remark-lint rule that validates the spacing used in Markdown hard line breaks. It warns when more than two spaces are used at the end of a line to create a hard break, or when spaces are used instead of the recommended backslash escape sequence.
3

4
## Package Information
5

6
- **Package Name**: remark-lint-hard-break-spaces
7
- **Package Type**: npm
8
- **Language**: JavaScript (with TypeScript types)
9
- **Installation**: `npm install remark-lint-hard-break-spaces`
10

11
## Core Imports
12

13
```javascript
14
import remarkLintHardBreakSpaces from "remark-lint-hard-break-spaces";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const remarkLintHardBreakSpaces = require("remark-lint-hard-break-spaces");
21
```
22

23
## Basic Usage
24

25
```javascript
26
import remarkLint from "remark-lint";
27
import remarkLintHardBreakSpaces from "remark-lint-hard-break-spaces";
28
import remarkParse from "remark-parse";
29
import remarkStringify from "remark-stringify";
30
import { unified } from "unified";
31
import { read } from "to-vfile";
32
import { reporter } from "vfile-reporter";
33

34
const file = await read("example.md");
35

36
await unified()
37
  .use(remarkParse)
38
  .use(remarkLint)
39
  .use(remarkLintHardBreakSpaces)
40
  .use(remarkStringify)
41
  .process(file);
42

43
console.error(reporter(file));
44
```
45

46
## Capabilities
47

48
### Lint Rule Plugin
49

50
The main plugin function that creates a remark-lint rule to validate hard break spacing.
51

52
```javascript { .api }
53
/**
54
 * remark-lint rule to warn when spaces are used incorrectly for hard breaks
55
 * @param {Options | null | undefined} options - Configuration options
56
 * @returns {Transformer} Transform function for unified pipeline
57
 */
58
function remarkLintHardBreakSpaces(options);
59
```
60

61
**Usage with unified:**
62

63
```javascript
64
import { unified } from "unified";
65
import remarkParse from "remark-parse";
66
import remarkLint from "remark-lint";
67
import remarkLintHardBreakSpaces from "remark-lint-hard-break-spaces";
68

69
const processor = unified()
70
  .use(remarkParse)
71
  .use(remarkLint)
72
  .use(remarkLintHardBreakSpaces, { allowSpaces: false });
73
```
74

75
**Usage with configuration:**
76

77
```javascript
78
// Allow trailing spaces (default behavior)
79
.use(remarkLintHardBreakSpaces)
80
.use(remarkLintHardBreakSpaces, { allowSpaces: true })
81

82
// Enforce escape-style hard breaks only
83
.use(remarkLintHardBreakSpaces, { allowSpaces: false })
84
```
85

86
**Common integration patterns:**
87

88
```javascript
89
// In package.json remarkConfig
90
{
91
  "remarkConfig": {
92
    "plugins": [
93
      "remark-lint",
94
      "remark-lint-hard-break-spaces",
95
      // or with options
96
      ["remark-lint-hard-break-spaces", { "allowSpaces": false }]
97
    ]
98
  }
99
}
100

101
// With remark CLI
102
remark --use remark-lint --use remark-lint-hard-break-spaces .
103
```
104

105
## Types
106

107
```typescript { .api }
108
/**
109
 * Configuration options for the hard break spaces rule
110
 */
111
interface Options {
112
  /**
113
   * Allow trailing space hard breaks at all
114
   * @default true
115
   * When false: use escape hard breaks (backslash) instead
116
   * When true: allow 2-space hard breaks, warn on more than 2 spaces
117
   */
118
  allowSpaces?: boolean | null | undefined;
119
}
120
```
121

122
## Error Messages
123

124
The plugin generates specific error messages based on configuration:
125

126
- **With `allowSpaces: true` (default)**: `"Unexpected \`3\` spaces for hard break, expected \`2\` spaces"`
127
- **With `allowSpaces: false`**: `"Unexpected \`2\` spaces for hard break, expected escape"`
128

129
**Configuration validation errors:**
130

131
```javascript { .api }
132
// Invalid option type
133
"Unexpected value `🌍` for `options`, expected object"
134

135
// Invalid allowSpaces type  
136
"Unexpected value `🌍` for `options.allowSpaces`, expected `boolean`"
137
```
138

139
## Recommendation
140

141
Less than two spaces do not create hard breaks and more than two spaces have no effect. Due to this, it's recommended to turn this rule on.
142

143
With CommonMark, it is now possible to use a backslash (`\`) at the end of a line to create a hard break. It is now recommended to pass `allowSpaces: false` to enforce this cleaner approach.
144

145
**Valid hard break examples:**
146

147
```markdown
148
<!-- With allowSpaces: true (default) -->
149
**Mercury** is the first planet from the Sun  
150
and the smallest in the Solar System.
151

152
<!-- With allowSpaces: false -->
153
**Venus** is the second planet from\
154
the Sun.
155
```
156

157
**Invalid examples that trigger warnings:**
158

159
```markdown
160
<!-- Too many spaces (3+ spaces) -->
161
**Mercury** is the first planet from the Sun   
162
and the smallest in the Solar System.
163
<!-- Warning: "Unexpected `3` spaces for hard break, expected `2` spaces" -->
164

165
<!-- Spaces when allowSpaces: false -->
166
**Mercury** is the first planet from the Sun  
167
and the smallest in the Solar System.
168
<!-- Warning: "Unexpected `2` spaces for hard break, expected escape" -->
169
```