0
# Plugin Management
1

2
Utilities for managing the built-in VuePress markdown plugins, including checking requirements, removing plugins, and bulk plugin management.
3

4
## Capabilities
5

6
### Plugin Requirement Check
7

8
Check if a plugin is required by VuePress and cannot be removed.
9

10
```javascript { .api }
11
/**
12
 * Check if a plugin is required and cannot be removed
13
 * @param {string} plugin - Plugin name to check
14
 * @returns {boolean} True if plugin is required (COMPONENT or ANCHOR)
15
 */
16
function isRequiredPlugin(plugin: string): boolean;
17
```
18

19
**Usage Examples:**
20

21
```javascript
22
const { isRequiredPlugin, PLUGINS } = require('@vuepress/markdown');
23

24
// Check required plugins
25
console.log(isRequiredPlugin(PLUGINS.COMPONENT)); // true
26
console.log(isRequiredPlugin(PLUGINS.ANCHOR)); // true
27
console.log(isRequiredPlugin(PLUGINS.HIGHLIGHT_LINES)); // false
28
console.log(isRequiredPlugin(PLUGINS.EMOJI)); // false
29

30
// Use in conditional logic
31
if (!isRequiredPlugin(PLUGINS.TOC)) {
32
  // Safe to remove TOC plugin
33
}
34
```
35

36
### Single Plugin Removal
37

38
Remove a specific built-in markdown-it plugin from the configuration.
39

40
```javascript { .api }
41
/**
42
 * Remove a specific built-in plugin from the markdown configuration
43
 * @param {object} config - markdown-it-chain configuration object
44
 * @param {string} plugin - Plugin name to remove (use PLUGINS constants)
45
 */
46
function removePlugin(config: ChainConfig, plugin: string): void;
47
```
48

49
**Usage Examples:**
50

51
```javascript
52
const createMarkdown = require('@vuepress/markdown');
53
const { removePlugin, PLUGINS } = require('@vuepress/markdown');
54

55
// Use with VuePress Plugin API chainMarkdown
56
module.exports = {
57
  chainMarkdown(config) {
58
    // Remove specific plugins
59
    removePlugin(config, PLUGINS.HIGHLIGHT_LINES);
60
    removePlugin(config, PLUGINS.LINE_NUMBERS);
61
    removePlugin(config, PLUGINS.EMOJI);
62
    
63
    // Cannot remove required plugins (will log warning)
64
    // removePlugin(config, PLUGINS.COMPONENT); // Not allowed
65
    // removePlugin(config, PLUGINS.ANCHOR); // Not allowed
66
  }
67
};
68

69
// Use with beforeInstantiate hook
70
const md = createMarkdown({
71
  beforeInstantiate(config) {
72
    removePlugin(config, PLUGINS.TOC);
73
    removePlugin(config, PLUGINS.SNIPPET);
74
  }
75
});
76
```
77

78
### Bulk Plugin Removal
79

80
Remove all non-required built-in plugins in one operation.
81

82
```javascript { .api }
83
/**
84
 * Remove all built-in plugins except required ones (COMPONENT, ANCHOR)
85
 * @param {object} config - markdown-it-chain configuration object
86
 */
87
function removeAllBuiltInPlugins(config: ChainConfig): void;
88
```
89

90
**Usage Examples:**
91

92
```javascript
93
const createMarkdown = require('@vuepress/markdown');
94
const { removeAllBuiltInPlugins } = require('@vuepress/markdown');
95

96
// Use with VuePress Plugin API
97
module.exports = {
98
  chainMarkdown(config) {
99
    // Remove all non-required plugins at once
100
    removeAllBuiltInPlugins(config);
101
    
102
    // Add your own plugins
103
    config.plugin('my-custom-plugin')
104
      .use(myCustomPlugin, [options]);
105
  }
106
};
107

108
// Use with beforeInstantiate hook for clean slate
109
const md = createMarkdown({
110
  beforeInstantiate(config) {
111
    // Start with minimal setup
112
    removeAllBuiltInPlugins(config);
113
    
114
    // Add only what you need
115
    config.plugin('highlight-lines')
116
      .use(highlightLinesPlugin);
117
  }
118
});
119
```
120

121
## Plugin Constants
122

123
### PLUGINS Object
124

125
Constant object containing the names of all built-in markdown-it plugins.
126

127
```javascript { .api }
128
const PLUGINS: {
129
  readonly COMPONENT: 'component';
130
  readonly HIGHLIGHT_LINES: 'highlight-lines';
131
  readonly PRE_WRAPPER: 'pre-wrapper';
132
  readonly SNIPPET: 'snippet';
133
  readonly CONVERT_ROUTER_LINK: 'convert-router-link';
134
  readonly HOIST_SCRIPT_STYLE: 'hoist-script-style';
135
  readonly ANCHOR: 'anchor';
136
  readonly EMOJI: 'emoji';
137
  readonly TOC: 'toc';
138
  readonly LINE_NUMBERS: 'line-numbers';
139
};
140
```
141

142
**Usage Examples:**
143

144
```javascript
145
const { PLUGINS, removePlugin } = require('@vuepress/markdown');
146

147
// Use constants instead of strings
148
removePlugin(config, PLUGINS.HIGHLIGHT_LINES); // Good
149
removePlugin(config, 'highlight-lines'); // Works but not recommended
150

151
// List all available plugins
152
Object.keys(PLUGINS).forEach(key => {
153
  console.log(`${key}: ${PLUGINS[key]}`);
154
});
155
```
156

157
### Required Plugins
158

159
The following plugins are required and cannot be removed:
160

161
- **COMPONENT** (`'component'`): Enables Vue components in markdown (required for VuePress)  
162
- **ANCHOR** (`'anchor'`): Generates heading anchors with permalinks (required for navigation)
163

164
### Optional Plugins
165

166
The following plugins can be safely removed:
167

168
- **HIGHLIGHT_LINES** (`'highlight-lines'`): Highlights specific lines in code blocks
169
- **PRE_WRAPPER** (`'pre-wrapper'`): Wraps code blocks with additional containers
170
- **SNIPPET** (`'snippet'`): Includes code snippets from external files
171
- **CONVERT_ROUTER_LINK** (`'convert-router-link'`): Converts links to Vue Router links
172
- **HOIST_SCRIPT_STYLE** (`'hoist-script-style'`): Hoists script/style tags
173
- **EMOJI** (`'emoji'`): Converts emoji shortcodes to Unicode
174
- **TOC** (`'toc'`): Generates table of contents
175
- **LINE_NUMBERS** (`'line-numbers'`): Adds line numbers to code blocks
176

177
## Error Handling
178

179
Plugin management functions include error handling and logging:
180

181
- Attempting to remove required plugins logs a warning but does not fail
182
- Invalid plugin names are ignored
183
- All plugin operations are safe and won't break the markdown processor