0
# @vuepress/markdown
1

2
@vuepress/markdown is a comprehensive markdown processing library specifically designed for VuePress, the Vue.js-based static site generator. It extends markdown-it with custom plugins and enhancements tailored for documentation sites, including syntax highlighting, component embedding, anchor generation, table of contents, line numbers, snippet inclusion, emoji support, and Vue Router link conversion.
3

4
## Package Information
5

6
- **Package Name**: @vuepress/markdown
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install @vuepress/markdown`
10

11
## Core Imports
12

13
```javascript
14
const createMarkdown = require('@vuepress/markdown');
15
const { PLUGINS, isRequiredPlugin, removePlugin, removeAllBuiltInPlugins, dataReturnable } = require('@vuepress/markdown');
16
```
17

18
For ES modules:
19

20
```javascript
21
import createMarkdown, { PLUGINS, isRequiredPlugin, removePlugin, removeAllBuiltInPlugins, dataReturnable } from '@vuepress/markdown';
22
```
23

24
## Basic Usage
25

26
```javascript
27
const createMarkdown = require('@vuepress/markdown');
28

29
// Create a markdown processor with default VuePress plugins
30
const md = createMarkdown({
31
  lineNumbers: true,
32
  anchor: {
33
    permalink: true,
34
    permalinkBefore: true,
35
    permalinkSymbol: '#'
36
  }
37
});
38

39
// Process markdown content
40
const result = md.render('# Hello World\n\nThis is a test.');
41
console.log(result.html);        // Rendered HTML
42
console.log(result.data);        // Plugin data
43
console.log(result.dataBlockString); // Serialized data for Vue
44
```
45

46
## Architecture
47

48
@vuepress/markdown is built around several key components:
49

50
- **Factory Function**: Main export that creates pre-configured markdown-it instances
51
- **Plugin System**: 11 built-in plugins for VuePress-specific functionality
52
- **Configuration Chain**: Uses markdown-it-chain for fluent configuration
53
- **Data Collection**: Enhanced rendering that collects plugin data alongside HTML
54
- **Plugin Management**: Utilities for removing or configuring built-in plugins
55

56
## Capabilities
57

58
### Markdown Processor Creation
59

60
Factory function that creates a markdown-it instance with VuePress-specific plugins and configuration.
61

62
```javascript { .api }
63
/**
64
 * Create a markdown processor with VuePress plugins
65
 * @param {object} markdown - Configuration options
66
 * @returns {MarkdownIt} Enhanced markdown-it instance
67
 */
68
function createMarkdown(markdown?: MarkdownConfig): MarkdownIt;
69

70
interface MarkdownConfig {
71
  externalLinks?: ExternalLinksConfig;
72
  pageSuffix?: string;
73
  anchor?: AnchorConfig;
74
  toc?: TocConfig;
75
  plugins?: Plugin[];
76
  lineNumbers?: boolean;
77
  slugify?: (str: string) => string;
78
  beforeInstantiate?: (config: ChainConfig) => void;
79
  afterInstantiate?: (md: MarkdownIt) => void;
80
}
81
```
82

83
[Markdown Processing](./markdown-processing.md)
84

85
### Plugin Management
86

87
Utilities for managing built-in VuePress markdown plugins, including removal and configuration.
88

89
```javascript { .api }
90
/**
91
 * Check if a plugin is required and cannot be removed
92
 * @param {string} plugin - Plugin name
93
 * @returns {boolean} True if plugin is required
94
 */
95
function isRequiredPlugin(plugin: string): boolean;
96

97
/**
98
 * Remove a specific built-in plugin
99
 * @param {object} config - markdown-it-chain configuration
100
 * @param {string} plugin - Plugin name to remove
101
 */
102
function removePlugin(config: ChainConfig, plugin: string): void;
103

104
/**
105
 * Remove all non-required built-in plugins
106
 * @param {object} config - markdown-it-chain configuration
107
 */
108
function removeAllBuiltInPlugins(config: ChainConfig): void;
109
```
110

111
[Plugin Management](./plugin-management.md)
112

113
### Built-in Plugins
114

115
Access to plugin names and built-in plugin functionality for VuePress markdown processing.
116

117
```javascript { .api }
118
const PLUGINS: {
119
  COMPONENT: 'component';
120
  HIGHLIGHT_LINES: 'highlight-lines';
121
  PRE_WRAPPER: 'pre-wrapper';
122
  SNIPPET: 'snippet';
123
  CONVERT_ROUTER_LINK: 'convert-router-link';
124
  HOIST_SCRIPT_STYLE: 'hoist-script-style';
125
  ANCHOR: 'anchor';
126
  EMOJI: 'emoji';
127
  TOC: 'toc';
128
  LINE_NUMBERS: 'line-numbers';
129
};
130
```
131

132
[Built-in Plugins](./builtin-plugins.md)
133

134
## Types
135

136
```javascript { .api }
137
interface ExternalLinksConfig {
138
  target?: string;
139
  rel?: string;
140
}
141

142
interface AnchorConfig {
143
  slugify?: (str: string) => string;
144
  permalink?: boolean;
145
  permalinkBefore?: boolean;
146
  permalinkSymbol?: string;
147
}
148

149
interface TocConfig {
150
  slugify?: (str: string) => string;
151
  includeLevel?: number[];
152
  format?: (headers: any) => any;
153
}
154

155
interface Plugin extends Array<any> {
156
  0: string | Function;
157
  1?: any;
158
}
159

160
interface RenderResult {
161
  html: string;
162
  data: object;
163
  dataBlockString: string;
164
}
165
```