0
# Front-matter Processing
1

2
Front-matter parsing and manipulation utilities for handling YAML/JSON metadata in files. Metalsmith automatically parses front-matter from files and makes it available as file properties.
3

4
## Capabilities
5

6
### Front-matter Configuration
7

8
Configure how front-matter is parsed and processed for all files.
9

10
```javascript { .api }
11
/**
12
 * Configure front-matter parsing options
13
 * @param options - Boolean to enable/disable or gray-matter options object
14
 * @returns Metalsmith instance for chaining
15
 */
16
frontmatter(options: boolean | GrayMatterOptions): Metalsmith;
17

18
/**
19
 * Get current front-matter configuration
20
 * @returns Current front-matter settings
21
 */
22
frontmatter(): boolean | GrayMatterOptions;
23

24
interface GrayMatterOptions {
25
  /** Front-matter language: "yaml", "json", "toml", etc. (default: "yaml") */
26
  language?: string;
27
  /** Enable excerpt parsing or provide custom excerpt function */
28
  excerpt?: boolean | ((file: GrayMatterFile<string>, options: GrayMatterOptions) => any);
29
  /** Separator for excerpt content (default: "---") */
30
  excerpt_separator?: string;
31
  /** Front-matter delimiters (default: "---") */
32
  delimiters?: string | string[];
33
  /** Custom parsing engines for different formats */
34
  engines?: {
35
    [engine: string]: ((file: string) => any) | {
36
      parse: (file: string) => any;
37
      stringify?: (data: any) => string;
38
    };
39
  };
40
}
41
```
42

43
**Usage Examples:**
44

45
```javascript
46
import Metalsmith from "metalsmith";
47

48
// Enable front-matter with default settings
49
metalsmith.frontmatter(true);
50

51
// Disable front-matter parsing
52
metalsmith.frontmatter(false);
53

54
// Custom front-matter configuration
55
metalsmith.frontmatter({
56
  excerpt: true,
57
  excerpt_separator: '<!-- more -->',
58
  language: 'yaml',
59
  delimiters: '---'
60
});
61

62
// JSON front-matter
63
metalsmith.frontmatter({
64
  language: 'json',
65
  delimiters: [';;;', ';;;']
66
});
67
```
68

69
### Front-matter Parser Access
70

71
Direct access to the front-matter parser for custom operations.
72

73
```javascript { .api }
74
/**
75
 * Front-matter parser instance (available as metalsmith.matter)
76
 */
77
interface Matter {
78
  /** Parse string or buffer for front-matter */
79
  parse(contents: Buffer | string): File;
80
  /** Stringify file object back to front-matter format */
81
  stringify(file: File): string;
82
  /** Get or set parser options */
83
  options(options?: GrayMatterOptions): GrayMatterOptions | void;
84
  /** Wrap data with front-matter delimiters */
85
  wrap(data: string): string;
86
}
87
```
88

89
### Parse Front-matter
90

91
Parse front-matter from string or buffer content manually.
92

93
```javascript { .api }
94
/**
95
 * Parse front-matter from content
96
 * @param contents - String or Buffer containing front-matter and content
97
 * @returns File object with parsed metadata and contents
98
 */
99
matter.parse(contents: Buffer | string): File;
100
```
101

102
**Usage Examples:**
103

104
```javascript
105
const metalsmith = Metalsmith(__dirname);
106

107
// Parse front-matter manually
108
const fileContent = `---
109
title: My Article
110
date: 2024-01-01
111
tags: [javascript, metalsmith]
112
excerpt: This is a preview
113
---
114
<!-- more -->
115
# Article Content
116

117
This is the main content of the article.`;
118

119
const parsed = metalsmith.matter.parse(fileContent);
120

121
console.log('Metadata:', {
122
  title: parsed.title,      // "My Article"
123
  date: parsed.date,        // Date object
124
  tags: parsed.tags,        // ["javascript", "metalsmith"]
125
  excerpt: parsed.excerpt   // "This is a preview" (if excerpt enabled)
126
});
127

128
console.log('Content:', parsed.contents.toString());
129
// "# Article Content\n\nThis is the main content..."
130
```
131

132
### Stringify File Object
133

134
Convert a file object back to front-matter format.
135

136
```javascript { .api }
137
/**
138
 * Stringify file object to front-matter format
139
 * @param file - File object with contents and metadata
140
 * @returns String with front-matter header and content
141
 */
142
matter.stringify(file: File): string;
143
```
144

145
**Usage Examples:**
146

147
```javascript
148
const fileObj = {
149
  contents: Buffer.from('# Hello World\n\nContent here.'),
150
  title: 'Hello World',
151
  date: new Date('2024-01-01'),
152
  published: true
153
};
154

155
const stringified = metalsmith.matter.stringify(fileObj);
156
console.log(stringified);
157

158
// Output:
159
// ---
160
// title: Hello World
161
// date: 2024-01-01T00:00:00.000Z
162
// published: true
163
// ---
164
// # Hello World
165
// 
166
// Content here.
167
```
168

169
### Configure Parser Options
170

171
Get or set options for the front-matter parser.
172

173
```javascript { .api }
174
/**
175
 * Get current parser options
176
 * @returns Current gray-matter options
177
 */
178
matter.options(): GrayMatterOptions;
179

180
/**
181
 * Set parser options
182
 * @param options - Gray-matter configuration options
183
 */
184
matter.options(options: GrayMatterOptions): void;
185
```
186

187
**Usage Examples:**
188

189
```javascript
190
// Get current options
191
const currentOptions = metalsmith.matter.options();
192
console.log('Current language:', currentOptions.language);
193

194
// Set new options
195
metalsmith.matter.options({
196
  excerpt: true,
197
  excerpt_separator: '<!-- more -->',
198
  language: 'yaml'
199
});
200

201
// Enable custom engine for TOML
202
metalsmith.matter.options({
203
  engines: {
204
    toml: {
205
      parse: (str) => require('toml').parse(str),
206
      stringify: (data) => require('toml').stringify(data)
207
    }
208
  }
209
});
210
```
211

212
### Wrap Data with Delimiters
213

214
Wrap stringified data with front-matter delimiters.
215

216
```javascript { .api }
217
/**
218
 * Wrap data string with front-matter delimiters
219
 * @param data - Stringified front-matter data
220
 * @returns Data wrapped with configured delimiters
221
 */
222
matter.wrap(data: string): string;
223
```
224

225
**Usage Examples:**
226

227
```javascript
228
const metadata = 'title: My Page\ndate: 2024-01-01';
229
const wrapped = metalsmith.matter.wrap(metadata);
230
console.log(wrapped);
231

232
// Output:
233
// ---
234
// title: My Page
235
// date: 2024-01-01
236
// ---
237
```
238

239
### Front-matter File Processing
240

241
Understanding how front-matter affects file processing.
242

243
**Automatic Processing:**
244

245
```javascript
246
// File: src/blog/post.md
247
// ---
248
// title: My Blog Post
249
// date: 2024-01-01
250
// tags: [web, javascript]
251
// draft: false
252
// ---
253
// # Post Content
254
// 
255
// This is my blog post content.
256

257
// After reading with metalsmith.read()
258
const files = await metalsmith.read();
259
const post = files['blog/post.md'];
260

261
console.log(post.title);    // "My Blog Post"
262
console.log(post.date);     // Date object
263
console.log(post.tags);     // ["web", "javascript"]
264
console.log(post.draft);    // false
265
console.log(post.contents.toString()); // "# Post Content\n\nThis is..."
266
```
267

268
### Excerpt Processing
269

270
Configure and use excerpt functionality.
271

272
```javascript
273
// Enable excerpt processing
274
metalsmith.frontmatter({
275
  excerpt: true,
276
  excerpt_separator: '<!-- excerpt -->'
277
});
278

279
// File with excerpt:
280
// ---
281
// title: Article
282
// ---
283
// This is the excerpt content.
284
// <!-- excerpt -->
285
// This is the full article content...
286

287
const files = await metalsmith.read();
288
const article = files['article.md'];
289

290
console.log(article.excerpt); // "This is the excerpt content."
291
console.log(article.contents.toString()); // "This is the full article content..."
292
```
293

294
### Custom Front-matter Formats
295

296
Support for different front-matter formats.
297

298
```javascript
299
// YAML (default)
300
metalsmith.frontmatter({
301
  language: 'yaml',
302
  delimiters: '---'
303
});
304

305
// JSON front-matter
306
metalsmith.frontmatter({
307
  language: 'json',
308
  delimiters: [';;;', ';;;']
309
});
310

311
// File with JSON front-matter:
312
// ;;;
313
// {
314
//   "title": "My Article",
315
//   "published": true
316
// }
317
// ;;;
318
// Content here...
319

320
// TOML front-matter
321
metalsmith.frontmatter({
322
  language: 'toml',
323
  delimiters: '+++',
324
  engines: {
325
    toml: require('toml')
326
  }
327
});
328

329
// File with TOML front-matter:
330
// +++
331
// title = "My Article"
332
// published = true
333
// +++
334
// Content here...
335
```
336

337
### Error Handling
338

339
Handle front-matter parsing errors gracefully.
340

341
```javascript
342
try {
343
  const files = await metalsmith.read();
344
} catch (error) {
345
  if (error.code === 'invalid_frontmatter') {
346
    console.error('Invalid front-matter syntax:', error.message);
347
    // Error includes file path information
348
  }
349
}
350

351
// Manual parsing error handling
352
try {
353
  const parsed = metalsmith.matter.parse(invalidContent);
354
} catch (error) {
355
  console.error('Front-matter parse error:', error.message);
356
}
357
```