0
# remark-gfm
1

2
remark-gfm is a plugin for the remark markdown processor that adds support for GitHub Flavored Markdown (GFM) extensions. It enables parsing and serialization of autolink literals, footnotes, strikethrough, tables, and task lists in markdown documents.
3

4
## Package Information
5

6
- **Package Name**: remark-gfm
7
- **Package Type**: npm
8
- **Language**: JavaScript (with TypeScript definitions)
9
- **Installation**: `npm install remark-gfm`
10

11
## Core Imports
12

13
ESM (recommended):
14

15
```javascript
16
import remarkGfm from 'remark-gfm';
17
```
18

19
For TypeScript users with type annotations:
20

21
```typescript
22
import remarkGfm, {type Options} from 'remark-gfm';
23
```
24

25
CommonJS:
26

27
```javascript
28
const remarkGfm = require('remark-gfm');
29
```
30

31
## Basic Usage
32

33
```javascript
34
import {unified} from 'unified';
35
import remarkParse from 'remark-parse';
36
import remarkRehype from 'remark-rehype';
37
import rehypeStringify from 'rehype-stringify';
38
import remarkGfm from 'remark-gfm';
39

40
const processor = unified()
41
  .use(remarkParse)
42
  .use(remarkGfm)
43
  .use(remarkRehype)
44
  .use(rehypeStringify);
45

46
const result = await processor.process('~~strikethrough~~ and www.example.com');
47
```
48

49
## Capabilities
50

51
### Plugin Function
52

53
The main function that adds GFM support to a remark processor.
54

55
```typescript { .api }
56
/**
57
 * Add support for GFM (autolink literals, footnotes, strikethrough, tables, tasklists)
58
 * @param options - Configuration options (optional)
59
 * @returns Nothing (undefined)
60
 */
61
declare function remarkGfm(options?: Options | null | undefined): undefined;
62
export default remarkGfm;
63
```
64

65
**Usage Examples:**
66

67
```javascript
68
import {unified} from 'unified';
69
import remarkParse from 'remark-parse';
70
import remarkGfm from 'remark-gfm';
71

72
// Basic usage without options
73
const processor = unified()
74
  .use(remarkParse)
75
  .use(remarkGfm);
76

77
// With options
78
const processor = unified()
79
  .use(remarkParse)
80
  .use(remarkGfm, {
81
    singleTilde: false,
82
    tablePipeAlign: true
83
  });
84

85
// TypeScript usage with explicit types
86
import type {Options} from 'remark-gfm';
87

88
const options: Options = {
89
  singleTilde: false,
90
  stringLength: (value: string) => value.length,
91
  tablePipeAlign: true,
92
  tableCellPadding: true
93
};
94

95
const processor = unified()
96
  .use(remarkParse)
97
  .use(remarkGfm, options);
98
```
99

100
### Configuration Options
101

102
Options interface for customizing remark-gfm behavior.
103

104
```typescript { .api }
105
export interface Options {
106
  /**
107
   * Whether to support strikethrough with a single tilde.
108
   * Single tildes work on github.com but are technically prohibited by GFM.
109
   * You can always use 2 or more tildes for strikethrough.
110
   * @default true
111
   */
112
  singleTilde?: boolean;
113

114
  /**
115
   * Whether to serialize with a blank line for the first line of footnote definitions.
116
   * @default false
117
   */
118
  firstLineBlank?: boolean;
119

120
  /**
121
   * Function to detect the size of table cells, used when aligning cells.
122
   * @default (value) => value.length
123
   */
124
  stringLength?: (value: string) => number;
125

126
  /**
127
   * Whether to align table pipes in serialized output.
128
   * @default true
129
   */
130
  tablePipeAlign?: boolean;
131

132
  /**
133
   * Whether to add a space of padding between table pipes and cells.
134
   * @default true
135
   */
136
  tableCellPadding?: boolean;
137
}
138
```
139

140
**Usage Examples:**
141

142
```javascript
143
import remarkGfm from 'remark-gfm';
144
import stringWidth from 'string-width';
145

146
// Disable single tilde strikethrough
147
processor.use(remarkGfm, {
148
  singleTilde: false
149
});
150

151
// Custom string length for Unicode-aware table alignment
152
processor.use(remarkGfm, {
153
  stringLength: stringWidth
154
});
155

156
// Disable table formatting
157
processor.use(remarkGfm, {
158
  tablePipeAlign: false,
159
  tableCellPadding: false
160
});
161
```
162

163
## GitHub Flavored Markdown Features
164

165
This plugin adds support for the following GFM extensions:
166

167
### Autolink Literals
168
Automatically converts URLs and email addresses to links:
169
- `www.example.com` → `<a href="http://www.example.com">www.example.com</a>`
170
- `https://example.com` → `<a href="https://example.com">https://example.com</a>`
171
- `contact@example.com` → `<a href="mailto:contact@example.com">contact@example.com</a>`
172

173
### Footnotes
174
Support for footnote syntax:
175
```markdown
176
Here is a footnote reference[^1].
177

178
[^1]: Here is the footnote definition.
179
```
180

181
### Strikethrough
182
Support for strikethrough text:
183
- `~~two tildes~~` (standard GFM)
184
- `~one tilde~` (GitHub extension, can be disabled with `singleTilde: false`)
185

186
### Tables
187
Support for GitHub-style tables:
188
```markdown
189
| Header 1 | Header 2 |
190
| -------- | -------- |
191
| Cell 1   | Cell 2   |
192
```
193

194
With alignment:
195
```markdown
196
| Left | Center | Right |
197
| :--- | :----: | ----: |
198
| L    |   C    |     R |
199
```
200

201
### Task Lists
202
Support for task list items:
203
```markdown
204
- [ ] Incomplete task
205
- [x] Complete task
206
```
207

208
## Integration Notes
209

210
- Requires `unified` ecosystem with `remark-parse` for parsing
211
- Use with `remark-stringify` for serialization back to markdown
212
- Compatible with `remark-rehype` for HTML conversion
213
- Works with Node.js 16+ and modern browsers (ESM)
214
- Integrates with micromark extensions for low-level parsing
215
- Uses mdast utilities for syntax tree manipulation