0
# Built-in Plugins
1

2
Comprehensive documentation of all built-in plugins included with @vuepress/markdown, their functionality, and configuration options.
3

4
## Required Plugins
5

6
These plugins are essential for VuePress functionality and cannot be removed.
7

8
### Component Plugin
9

10
Enables Vue components within markdown content, supporting both PascalCase components and custom elements with hyphens.
11

12
```javascript { .api }
13
// Plugin name constant
14
PLUGINS.COMPONENT: 'component'
15
```
16

17
**Functionality:**
18
- Recognizes PascalCase Vue components (`<MyComponent />`)
19
- Supports custom elements with hyphens (`<custom-element />`) 
20
- Enables component embedding in markdown documents
21
- Essential for VuePress Vue component integration
22

23
**Usage Examples:**
24

25
```markdown
26
<!-- Vue components in markdown -->
27
<MyButton type="primary">Click me</MyButton>
28

29
<CustomCard title="Hello">
30
  This content will be rendered inside the card component.
31
</CustomCard>
32

33
<!-- Custom elements -->
34
<my-widget data="example"></my-widget>
35
```
36

37
### Anchor Plugin
38

39
Generates heading anchors with permalinks for navigation and deep linking.
40

41
```javascript { .api }
42
// Plugin name constant  
43
PLUGINS.ANCHOR: 'anchor'
44
```
45

46
**Default Configuration:**
47
```javascript
48
{
49
  slugify: slugifyFunction,
50
  permalink: true,
51
  permalinkBefore: true, 
52
  permalinkSymbol: '#'
53
}
54
```
55

56
**Functionality:**
57
- Automatically generates anchor links for all headings
58
- Creates permalink buttons for easy sharing
59
- Uses configurable slugify function for anchor generation
60
- Essential for VuePress navigation and table of contents
61

62
## Enhancement Plugins
63

64
These plugins provide additional functionality and can be removed if not needed.
65

66
### Highlight Lines Plugin
67

68
Highlights specific lines within code blocks using line number ranges.
69

70
```javascript { .api }
71
PLUGINS.HIGHLIGHT_LINES: 'highlight-lines'
72
```
73

74
**Usage Examples:**
75

76
```markdown
77
<!-- Highlight lines 1 and 3-5 -->
78
\`\`\`js{1,3-5}
79
console.log('line 1'); // highlighted
80
console.log('line 2');
81
console.log('line 3'); // highlighted
82
console.log('line 4'); // highlighted
83
console.log('line 5'); // highlighted
84
\`\`\`
85

86
<!-- Highlight single line -->
87
\`\`\`python{2}
88
def hello():
89
    print("This line is highlighted")
90
    return True
91
\`\`\`
92
```
93

94
### Pre Wrapper Plugin
95

96
Wraps code blocks with additional container elements for enhanced styling and functionality.
97

98
```javascript { .api }
99
PLUGINS.PRE_WRAPPER: 'pre-wrapper'
100
```
101

102
**Functionality:**
103
- Adds wrapper divs around code blocks
104
- Provides additional CSS hooks for styling
105
- Enables enhanced code block interactions
106
- Supports syntax highlighting integration
107

108
### Line Numbers Plugin
109

110
Adds line numbers to code blocks for better readability and reference.
111

112
```javascript { .api }
113
PLUGINS.LINE_NUMBERS: 'line-numbers'
114
```
115

116
**Configuration:**
117
```javascript
118
const md = createMarkdown({
119
  lineNumbers: true  // Enable line numbers globally
120
});
121
```
122

123
**Usage Examples:**
124

125
```markdown
126
<!-- Code block with line numbers -->
127
\`\`\`javascript
128
function calculateSum(a, b) {
129
  return a + b;
130
}
131

132
const result = calculateSum(5, 3);
133
console.log(result);
134
\`\`\`
135
```
136

137
### Snippet Plugin  
138

139
Includes code snippets from external files with optional line highlighting and language specification.
140

141
```javascript { .api }
142
PLUGINS.SNIPPET: 'snippet'
143
```
144

145
**Usage Examples:**
146

147
```markdown
148
<!-- Include entire file -->
149
<<< @/path/to/file.js
150

151
<!-- Include with language specification -->
152
<<< @/path/to/file.py{python}
153

154
<!-- Include with line highlighting -->
155
<<< @/path/to/file.js{1,3-5}
156

157
<!-- Include with both language and highlighting -->
158
<<< @/path/to/component.vue{vue}{1-10,15}
159
```
160

161
### Convert Router Link Plugin
162

163
Converts markdown links to Vue Router links for internal navigation and handles external links.
164

165
```javascript { .api }
166
PLUGINS.CONVERT_ROUTER_LINK: 'convert-router-link'
167
```
168

169
**Default Configuration:**
170
```javascript
171
{
172
  target: '_blank',
173
  rel: 'noopener noreferrer'
174
}
175
```
176

177
**Functionality:**
178
- Automatically detects internal vs external links
179
- Converts internal links to Vue Router links
180
- Adds security attributes to external links
181
- Respects page suffix configuration
182

183
### Hoist Script Style Plugin
184

185
Hoists `<script>` and `<style>` tags from markdown content to the document head for proper execution.
186

187
```javascript { .api }
188
PLUGINS.HOIST_SCRIPT_STYLE: 'hoist-script-style'
189
```
190

191
**Usage Examples:**
192

193
```markdown
194
<!-- These will be hoisted to document head -->
195
<script>
196
export default {
197
  mounted() {
198
    console.log('Component mounted');
199
  }
200
}
201
</script>
202

203
<style scoped>
204
.my-component {
205
  color: blue;
206
}
207
</style>
208

209
# My Component
210

211
Regular markdown content here.
212
```
213

214
## Third-Party Plugins
215

216
These plugins are included via external packages.
217

218
### Emoji Plugin
219

220
Converts emoji shortcodes to Unicode emoji characters.
221

222
```javascript { .api }
223
PLUGINS.EMOJI: 'emoji'
224
```
225

226
**Usage Examples:**
227

228
```markdown
229
I love VuePress :heart:!
230
This plugin is :fire: :rocket:!
231
Good job :+1: :thumbsup:
232
```
233

234
Renders as:
235
```
236
I love VuePress ❤️!
237
This plugin is 🔥 🚀!
238
Good job 👍 👍
239
```
240

241
### Table of Contents Plugin
242

243
Generates table of contents from markdown headings.
244

245
```javascript { .api }
246
PLUGINS.TOC: 'toc'  
247
```
248

249
**Default Configuration:**
250
```javascript
251
{
252
  slugify: slugifyFunction,
253
  includeLevel: [2, 3],
254
  format: parseHeaders
255
}
256
```
257

258
**Usage Examples:**
259

260
```markdown
261
<!-- Generate TOC for headings level 2-3 -->
262
[[toc]]
263

264
## Section 1
265
### Subsection 1.1
266
### Subsection 1.2
267

268
## Section 2  
269
### Subsection 2.1
270
```
271

272
## Syntax Highlighting
273

274
All code blocks benefit from built-in syntax highlighting powered by Prism.js.
275

276
**Supported Languages:**
277
- JavaScript, TypeScript, Python, Java, C/C++
278
- HTML, CSS, SCSS, Vue, React JSX
279
- Bash, PowerShell, SQL, JSON, YAML
280
- And many more via Prism.js language components
281

282
**Language Detection:**
283
- Automatic detection from file extensions
284
- Manual specification in code block language tags
285
- Fallback to plain text for unknown languages
286

287
**Features:**
288
- Automatic language component loading
289
- Proper escaping for safe rendering
290
- Integration with highlight lines and line numbers
291
- Theme support via CSS classes