0
# Linkify Plugin
1

2
The linkify plugin provides automatic URL and email detection and conversion to clickable links. It's available as a separate optional plugin that can be imported and used with any Remarkable instance.
3

4
## Capabilities
5

6
### Linkify Function
7

8
Plugin function that enables automatic link detection in text.
9

10
```javascript { .api }
11
/**
12
 * Plugin function to enable automatic URL and email linking
13
 * @param md - Remarkable instance to modify
14
 */
15
function linkify(md: Remarkable): void;
16
```
17

18
**Usage Examples:**
19

20
```javascript
21
import { Remarkable } from "remarkable";
22
import { linkify } from "remarkable/linkify";
23

24
// Apply linkify plugin
25
const md = new Remarkable().use(linkify);
26

27
// URLs are automatically converted to links
28
const result = md.render('Visit https://example.com for more info');
29
// Output: <p>Visit <a href="https://example.com">https://example.com</a> for more info</p>
30

31
// Email addresses are also converted
32
const emailResult = md.render('Contact us at support@example.com');
33
// Output: <p>Contact us at <a href="mailto:support@example.com">support@example.com</a></p>
34
```
35

36
### Import Methods
37

38
Different ways to import and use the linkify plugin.
39

40
```javascript { .api }
41
// ES6 modules
42
import { linkify } from "remarkable/linkify";
43

44
// CommonJS
45
const { linkify } = require("remarkable/linkify");
46

47
// Alternative: from main package (UMD only)
48
// import { Remarkable, linkify } from "remarkable";
49
```
50

51
**Usage Examples:**
52

53
```javascript
54
// Basic usage
55
import { Remarkable } from "remarkable";
56
import { linkify } from "remarkable/linkify";
57

58
const md = new Remarkable('default').use(linkify);
59

60
// Chaining with other plugins
61
const md = new Remarkable()
62
  .use(linkify)
63
  .use(otherPlugin);
64

65
// With options (plugin doesn't accept options directly)
66
const md = new Remarkable('full').use(linkify);
67
```
68

69
### Detection Patterns
70

71
Types of URLs and patterns that are automatically detected.
72

73
```javascript { .api }
74
interface LinkifyPatterns {
75
  /** Web URLs starting with protocol */
76
  protocols: string[]; // ['http://', 'https://', 'ftp://']
77
  /** URLs starting with www */
78
  www: boolean;
79
  /** Email addresses */
80
  email: boolean;
81
  /** IP addresses */
82
  ip: boolean;
83
}
84
```
85

86
**Detection Examples:**
87

88
```javascript
89
const md = new Remarkable().use(linkify);
90

91
// Protocol URLs
92
md.render('Visit https://example.com');
93
// → <p>Visit <a href="https://example.com">https://example.com</a></p>
94

95
md.render('Download from ftp://files.example.com/file.zip');
96
// → <p>Download from <a href="ftp://files.example.com/file.zip">ftp://files.example.com/file.zip</a></p>
97

98
// www URLs
99
md.render('Check out www.example.com');
100
// → <p>Check out <a href="http://www.example.com">www.example.com</a></p>
101

102
// Email addresses
103
md.render('Send email to user@domain.com');
104
// → <p>Send email to <a href="mailto:user@domain.com">user@domain.com</a></p>
105

106
// Mixed content
107
md.render('Visit https://example.com or email support@example.com');
108
// → <p>Visit <a href="https://example.com">https://example.com</a> or email <a href="mailto:support@example.com">support@example.com</a></p>
109
```
110

111
### Link Validation
112

113
Built-in link validation to prevent malicious or invalid URLs.
114

115
```javascript { .api }
116
/**
117
 * Link validation function used internally by the parser
118
 * @param url - URL to validate
119
 * @returns boolean indicating if URL is valid and safe
120
 */
121
function validateLink(url: string): boolean;
122
```
123

124
**Validation Behavior:**
125

126
```javascript
127
// Valid URLs that will be linked
128
const validUrls = [
129
  'https://example.com',
130
  'http://example.com',
131
  'ftp://files.example.com',
132
  'www.example.com',
133
  'user@example.com'
134
];
135

136
// Invalid URLs that will NOT be linked
137
const invalidUrls = [
138
  'javascript:alert(1)',  // JavaScript protocol blocked
139
  'data:text/html,<script>',  // Data protocol blocked
140
  'file:///etc/passwd',  // File protocol blocked
141
  'vbscript:msgbox(1)'   // VBScript protocol blocked
142
];
143
```
144

145
### Link Context Awareness
146

147
The plugin is aware of existing HTML links and markdown links to avoid double-linking.
148

149
**Context Examples:**
150

151
```javascript
152
const md = new Remarkable().use(linkify);
153

154
// Already in markdown link - no auto-linking
155
md.render('[Visit example](https://example.com)');
156
// → <p><a href="https://example.com">Visit example</a></p>
157

158
// Already in HTML link - no auto-linking
159
md.render('<a href="other.com">Visit https://example.com</a>');
160
// → <p><a href="other.com">Visit https://example.com</a></p>
161

162
// Outside of links - will be auto-linked
163
md.render('Visit https://example.com for more info');
164
// → <p>Visit <a href="https://example.com">https://example.com</a> for more info</p>
165

166
// Mixed: some linked, some auto-linked
167
md.render('[Official site](https://main.com) or mirror at https://mirror.com');
168
// → <p><a href="https://main.com">Official site</a> or mirror at <a href="https://mirror.com">https://mirror.com</a></p>
169
```
170

171
### Plugin Architecture
172

173
How the linkify plugin integrates with Remarkable's rule system.
174

175
```javascript { .api }
176
/**
177
 * Internal linkify rule function added to core parser
178
 */
179
function linkifyRule(state: StateCore): void;
180
```
181

182
**Integration Details:**
183

184
```javascript
185
// The plugin adds a rule to the core parser
186
function linkify(md) {
187
  md.core.ruler.push('linkify', linkifyRule);
188
}
189

190
// Custom linkify configuration (advanced usage)
191
function customLinkify(md, options) {
192
  // Remove default linkify if present
193
  md.core.ruler.disable(['linkify']);
194
  
195
  // Add custom linkify rule
196
  md.core.ruler.push('custom_linkify', function(state) {
197
    // Custom link detection logic
198
    return customLinkifyLogic(state, options);
199
  });
200
}
201

202
const md = new Remarkable().use(customLinkify, {
203
  protocols: ['https://'],
204
  emailEnabled: false
205
});
206
```
207

208
### Performance Considerations
209

210
Understanding the performance impact and optimization strategies.
211

212
**Performance Notes:**
213

214
```javascript
215
// Linkify processing occurs after block parsing but before inline parsing
216
// For optimal performance:
217

218
// 1. Apply linkify early in the plugin chain
219
const md = new Remarkable()
220
  .use(linkify)           // Early in chain
221
  .use(otherPlugins);
222

223
// 2. Consider disabling if not needed for performance-critical applications
224
const mdFast = new Remarkable('commonmark');  // No linkify by default
225

226
// 3. For large documents, consider selective enabling
227
const mdSelective = new Remarkable();
228
if (documentContainsUrls) {
229
  mdSelective.use(linkify);
230
}
231
```
232

233
### Package Information
234

235
Information about the linkify plugin package structure.
236

237
```javascript { .api }
238
// Package structure
239
interface LinkifyPackage {
240
  /** Main export path */
241
  main: string;          // "../dist/cjs/linkify.js"
242
  /** ES module export path */
243
  module: string;        // "../dist/esm/linkify.js"
244
  /** Package name */
245
  name: string;          // "remarkable/linkify"
246
}
247

248
// Dependencies
249
interface LinkifyDependencies {
250
  /** Autolinker library for URL detection */
251
  autolinker: string;    // "^3.11.0"
252
}
253
```
254

255
**Installation and Usage:**
256

257
```javascript
258
// The linkify plugin is included with remarkable - no separate installation needed
259
npm install remarkable
260

261
// Import and use
262
import { Remarkable } from "remarkable";
263
import { linkify } from "remarkable/linkify";
264

265
const md = new Remarkable().use(linkify);
266
```