0
# Markdown Processing
1

2
Core markdown processing functionality that creates enhanced markdown-it instances with VuePress-specific plugins and configuration.
3

4
## Capabilities
5

6
### Main Factory Function
7

8
Creates a markdown-it instance pre-configured with VuePress plugins and enhancements.
9

10
```javascript { .api }
11
/**
12
 * Create a markdown processor with VuePress plugins
13
 * @param {object} markdown - Configuration options
14
 * @returns {MarkdownIt} Enhanced markdown-it instance with VuePress plugins
15
 */
16
function createMarkdown(markdown?: MarkdownConfig): MarkdownIt;
17
```
18

19
**Usage Examples:**
20

21
```javascript
22
const createMarkdown = require('@vuepress/markdown');
23

24
// Basic usage with default configuration
25
const md = createMarkdown();
26
const result = md.render('# Hello World');
27
console.log(result.html);        // '<h1 id="hello-world"><a class="header-anchor" href="#hello-world">#</a> Hello World</h1>'
28
console.log(result.data);        // Plugin data collected during rendering
29
console.log(result.dataBlockString); // Serialized data block for Vue components
30

31
// With custom configuration
32
const mdCustom = createMarkdown({
33
  lineNumbers: true,
34
  anchor: {
35
    permalink: true,
36
    permalinkSymbol: '🔗'
37
  },
38
  toc: {
39
    includeLevel: [1, 2, 3]
40
  },
41
  externalLinks: {
42
    target: '_blank',
43
    rel: 'noopener noreferrer'
44
  }
45
});
46

47
// With custom plugins
48
const mdWithPlugins = createMarkdown({
49
  plugins: [
50
    ['markdown-it-custom-plugin', { option: 'value' }]
51
  ]
52
});
53

54
// Real-world VuePress documentation processing
55
const vuepressMarkdown = createMarkdown({
56
  lineNumbers: true,
57
  anchor: {
58
    permalink: true,
59
    permalinkBefore: true,
60
    permalinkSymbol: '#'
61
  },
62
  toc: {
63
    includeLevel: [2, 3, 4],
64
    format: headers => headers
65
  },
66
  externalLinks: {
67
    target: '_blank',
68
    rel: 'noopener noreferrer'
69
  },
70
  beforeInstantiate(config) {
71
    // Remove plugins we don't need
72
    config.plugins.delete('emoji');
73
  },
74
  afterInstantiate(md) {
75
    // Add custom functionality
76
    md.use(require('markdown-it-task-lists'));
77
  }
78
});
79

80
// Process documentation with components and code snippets
81
const docContent = `
82
# API Reference
83

84
<Badge text="v1.9.10" type="warning"/>
85

86
## Overview
87

88
This module provides markdown processing capabilities.
89

90
\`\`\`js{1,3-4}
91
const createMarkdown = require('@vuepress/markdown');
92
const md = createMarkdown();
93
const result = md.render('# Hello');
94
console.log(result.html);
95
\`\`\`
96

97
<<< @/examples/basic-usage.js{js}
98

99
[[toc]]
100
`;
101

102
const result = vuepressMarkdown.render(docContent);
103
console.log('Generated HTML:', result.html);
104
console.log('Component data:', result.data);
105
```
106

107
### Enhanced Render Method
108

109
The created markdown-it instance includes an enhanced render method that returns both HTML and plugin data.
110

111
```javascript { .api }
112
/**
113
 * Enhanced render method that returns HTML and data
114
 * @param {string} src - Markdown source content
115
 * @param {object} env - Environment object
116
 * @returns {RenderResult} Object containing html, data, and dataBlockString
117
 */
118
render(src: string, env?: object): RenderResult;
119

120
interface RenderResult {
121
  html: string;           // Rendered HTML content
122
  data: object;          // Plugin data collected during rendering
123
  dataBlockString: string; // Serialized data block for Vue components
124
}
125
```
126

127
**Usage Examples:**
128

129
```javascript
130
const md = createMarkdown();
131

132
// Render markdown with data collection
133
const result = md.render(`
134
# My Document
135

136
<MyComponent :data="{ title: 'Hello' }" />
137

138
\`\`\`js{1,3}
139
console.log('line 1');
140
console.log('line 2');
141
console.log('line 3');
142
\`\`\`
143
`);
144

145
console.log(result.html);        // Rendered HTML
146
console.log(result.data);        // Plugin data (component info, etc.)
147
console.log(result.dataBlockString); // Serialized data for Vue
148
```
149

150
### Data Returnable Enhancement
151

152
Utility function that enhances a markdown-it instance to return data alongside HTML.
153

154
```javascript { .api }
155
/**
156
 * Enhance markdown-it instance to return data with HTML
157
 * @param {MarkdownIt} md - markdown-it instance to enhance
158
 */
159
function dataReturnable(md: MarkdownIt): void;
160
```
161

162
### Slugify Function Access
163

164
The created markdown-it instance includes access to the slugify function used for generating anchors.
165

166
```javascript { .api }
167
/**
168
 * Slugify function attached to markdown-it instance
169
 * @param {string} str - String to slugify
170
 * @returns {string} Slugified string suitable for anchors
171
 */
172
md.slugify(str: string): string;
173
```
174

175
**Usage Examples:**
176

177
```javascript
178
const md = createMarkdown();
179

180
// Access the slugify function
181
const slug = md.slugify('Hello World!'); // 'hello-world'
182
const customSlug = md.slugify('API Reference 2.0'); // 'api-reference-2-0'
183
```
184

185
## Configuration Options
186

187
### MarkdownConfig Interface
188

189
```javascript { .api }
190
interface MarkdownConfig {
191
  /** Configuration for external link handling */
192
  externalLinks?: ExternalLinksConfig;
193
  /** Page suffix for router link conversion */
194
  pageSuffix?: string;
195
  /** Anchor plugin configuration */
196
  anchor?: AnchorConfig;
197
  /** Table of contents plugin configuration */
198
  toc?: TocConfig;
199
  /** Additional markdown-it plugins to load */
200
  plugins?: Plugin[];
201
  /** Enable line numbers in code blocks */
202
  lineNumbers?: boolean;
203
  /** Custom slugify function for anchors */
204
  slugify?: (str: string) => string;
205
  /** Hook called before markdown-it instantiation */
206
  beforeInstantiate?: (config: ChainConfig) => void;
207
  /** Hook called after markdown-it instantiation */
208
  afterInstantiate?: (md: MarkdownIt) => void;
209
}
210
```
211

212
### Lifecycle Hooks
213

214
```javascript { .api }
215
/**
216
 * Hook called before markdown-it is instantiated
217
 * @param {object} config - markdown-it-chain configuration object
218
 */
219
beforeInstantiate?: (config: ChainConfig) => void;
220

221
/**
222
 * Hook called after markdown-it is instantiated
223
 * @param {MarkdownIt} md - The created markdown-it instance
224
 */
225
afterInstantiate?: (md: MarkdownIt) => void;
226
```
227

228
**Usage Examples:**
229

230
```javascript
231
const md = createMarkdown({
232
  beforeInstantiate(config) {
233
    // Modify configuration before instantiation
234
    config.plugin('my-custom-plugin')
235
      .use(myPlugin, [{ option: 'value' }]);
236
  },
237
  afterInstantiate(md) {
238
    // Modify the instance after creation
239
    md.customProperty = 'custom value';
240
    md.use(anotherPlugin);
241
  }
242
});
243
```