0
# Core Configuration
1

2
Essential methods for configuring Metalsmith instances including source/destination paths, build settings, and global metadata.
3

4
## Capabilities
5

6
### Metalsmith Constructor
7

8
Initialize a new Metalsmith builder with a working directory.
9

10
```javascript { .api }
11
/**
12
 * Initialize a new Metalsmith builder with a working directory
13
 * @param directory - Working directory path (absolute or relative to process.cwd())
14
 * @returns Metalsmith instance
15
 */
16
function Metalsmith(directory: string): Metalsmith;
17
```
18

19
**Usage Examples:**
20

21
```javascript
22
import Metalsmith from "metalsmith";
23
import { fileURLToPath } from 'node:url';
24
import { dirname } from 'path';
25

26
const __dirname = dirname(fileURLToPath(import.meta.url));
27
const metalsmith = Metalsmith(__dirname);
28

29
// Can also be called without 'new'
30
const ms = new Metalsmith(__dirname);
31
```
32

33
### Working Directory
34

35
Get or set the working directory path. All relative paths are resolved relative to this directory.
36

37
```javascript { .api }
38
/**
39
 * Set the working directory path
40
 * @param directory - Directory path (relative paths resolve to process.cwd())
41
 * @returns Metalsmith instance for chaining
42
 */
43
directory(directory: string): Metalsmith;
44

45
/**
46
 * Get the absolute working directory path
47
 * @returns Absolute path to working directory
48
 */
49
directory(): string;
50
```
51

52
### Source Directory
53

54
Get or set the source directory where input files are read from.
55

56
```javascript { .api }
57
/**
58
 * Set the source directory path (relative to working directory)
59
 * @param path - Source directory path
60
 * @returns Metalsmith instance for chaining
61
 */
62
source(path: string): Metalsmith;
63

64
/**
65
 * Get the absolute source directory path
66
 * @returns Absolute path to source directory
67
 */
68
source(): string;
69
```
70

71
**Usage Examples:**
72

73
```javascript
74
metalsmith
75
  .source("./src")        // Set source to 'src' relative to working directory
76
  .source("content");     // Change to 'content' directory
77

78
const srcPath = metalsmith.source(); // Get current source path
79
```
80

81
### Destination Directory
82

83
Get or set the destination directory where output files are written.
84

85
```javascript { .api }
86
/**
87
 * Set the destination directory path (relative to working directory)
88
 * @param path - Destination directory path
89
 * @returns Metalsmith instance for chaining
90
 */
91
destination(path: string): Metalsmith;
92

93
/**
94
 * Get the absolute destination directory path
95
 * @returns Absolute path to destination directory
96
 */
97
destination(): string;
98
```
99

100
### Global Metadata
101

102
Get or set global metadata that is available to all plugins and templates.
103

104
```javascript { .api }
105
/**
106
 * Set global metadata (merged with existing metadata)
107
 * @param metadata - Metadata object to merge
108
 * @returns Metalsmith instance for chaining
109
 */
110
metadata(metadata: object): Metalsmith;
111

112
/**
113
 * Get the current global metadata object
114
 * @returns Current metadata object
115
 */
116
metadata(): object;
117
```
118

119
**Usage Examples:**
120

121
```javascript
122
metalsmith.metadata({
123
  sitename: "My Static Site",
124
  siteurl: "https://example.com/",
125
  author: "John Doe"
126
});
127

128
// Add more metadata later
129
metalsmith.metadata({
130
  buildDate: new Date(),
131
  version: "1.0.0"
132
});
133

134
const meta = metalsmith.metadata(); // Get all metadata
135
```
136

137
### Clean Destination
138

139
Get or set whether the destination directory should be cleaned before writing files.
140

141
```javascript { .api }
142
/**
143
 * Set whether to clean destination directory before writing
144
 * @param clean - True to clean destination, false to preserve existing files
145
 * @returns Metalsmith instance for chaining
146
 */
147
clean(clean: boolean): Metalsmith;
148

149
/**
150
 * Get the current clean setting
151
 * @returns Current clean setting
152
 */
153
clean(): boolean;
154
```
155

156
### File Concurrency
157

158
Get or set the maximum number of files to process concurrently.
159

160
```javascript { .api }
161
/**
162
 * Set maximum number of files to open at once
163
 * @param max - Maximum concurrent file operations (default: Infinity)
164
 * @returns Metalsmith instance for chaining
165
 */
166
concurrency(max: number): Metalsmith;
167

168
/**
169
 * Get the current concurrency limit
170
 * @returns Current concurrency limit
171
 */
172
concurrency(): number;
173
```
174

175
**Usage Examples:**
176

177
```javascript
178
// Limit concurrent file operations to prevent EMFILE errors
179
metalsmith.concurrency(50);
180

181
// Set build configuration
182
metalsmith
183
  .source("src")
184
  .destination("build")
185
  .clean(true)
186
  .concurrency(100)
187
  .metadata({
188
    sitename: "My Blog",
189
    baseUrl: process.env.NODE_ENV === 'production' 
190
      ? 'https://myblog.com' 
191
      : 'http://localhost:3000'
192
  });
193
```
194

195
### Front-matter Configuration
196

197
Get or set front-matter parsing options or disable front-matter parsing entirely.
198

199
```javascript { .api }
200
/**
201
 * Configure front-matter parsing options
202
 * @param frontmatter - Boolean to enable/disable or options object
203
 * @returns Metalsmith instance for chaining
204
 */
205
frontmatter(frontmatter: boolean | GrayMatterOptions): Metalsmith;
206

207
/**
208
 * Get the current front-matter configuration
209
 * @returns Current front-matter setting (boolean or options)
210
 */
211
frontmatter(): boolean | GrayMatterOptions;
212

213
interface GrayMatterOptions {
214
  /** Enable excerpt parsing from content */
215
  excerpt?: boolean;
216
  /** Separator for excerpt content */
217
  excerpt_separator?: string;
218
  /** Front-matter language (yaml, json, toml, etc.) */
219
  language?: string;
220
  /** Delimiters for front-matter blocks */
221
  delimiters?: string | string[];
222
  /** Custom parsing engines */
223
  engines?: object;
224
}
225
```
226

227
**Usage Examples:**
228

229
```javascript
230
// Disable front-matter parsing
231
metalsmith.frontmatter(false);
232

233
// Enable with custom options
234
metalsmith.frontmatter({
235
  excerpt: true,
236
  excerpt_separator: '<!-- more -->',
237
  language: 'yaml'
238
});
239

240
// Check if front-matter is enabled
241
if (metalsmith.frontmatter()) {
242
  console.log("Front-matter parsing is enabled");
243
}
244
```