0
# Metalsmith
1

2
Metalsmith is an extremely simple, pluggable static site generator for Node.js. It works by reading files from a source directory, running them through a series of plugins that manipulate the files, and then writing the results to a destination directory. All logic is handled by plugins, making it highly flexible and extensible.
3

4
## Package Information
5

6
- **Package Name**: metalsmith
7
- **Package Type**: npm
8
- **Language**: JavaScript (with TypeScript definitions)
9
- **Installation**: `npm install metalsmith`
10

11
## Core Imports
12

13
```javascript
14
import Metalsmith from "metalsmith";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const Metalsmith = require("metalsmith");
21
```
22

23
## Basic Usage
24

25
```javascript
26
import Metalsmith from "metalsmith";
27
import markdown from "@metalsmith/markdown";
28
import layouts from "@metalsmith/layouts";
29

30
const metalsmith = Metalsmith(__dirname)
31
  .source("./src")
32
  .destination("./build")
33
  .clean(true)
34
  .metadata({
35
    sitename: "My Static Site",
36
    siteurl: "https://example.com/"
37
  })
38
  .use(markdown())
39
  .use(layouts({
40
    pattern: "**/*.html"
41
  }))
42
  .build((err, files) => {
43
    if (err) throw err;
44
    console.log("Build finished!");
45
  });
46
```
47

48
## Architecture
49

50
Metalsmith follows a simple three-step process:
51

52
1. **Read**: Files are read from the source directory and parsed (including YAML frontmatter)
53
2. **Transform**: A series of plugins manipulate the file objects
54
3. **Write**: The processed files are written to the destination directory
55

56
Key architectural components:
57

58
- **Core Instance**: The main Metalsmith class that orchestrates the build process
59
- **Plugin System**: Middleware-style plugins that transform files in sequence
60
- **File Objects**: Each file is represented as an object with contents, metadata, and filesystem properties
61
- **Front-matter Processing**: YAML/JSON frontmatter is automatically parsed and merged with file metadata
62
- **CLI Interface**: Command-line tool for running builds from configuration files
63

64
## Capabilities
65

66
### Core Configuration
67

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

70
```javascript { .api }
71
function Metalsmith(directory: string): Metalsmith;
72

73
// Configuration methods
74
directory(path?: string): string | Metalsmith;
75
source(path?: string): string | Metalsmith;  
76
destination(path?: string): string | Metalsmith;
77
metadata(data?: object): object | Metalsmith;
78
clean(flag?: boolean): boolean | Metalsmith;
79
concurrency(max?: number): number | Metalsmith;
80
```
81

82
[Core Configuration](./core-configuration.md)
83

84
### Plugin System
85

86
Plugin management and execution system for extending Metalsmith functionality with custom transformations.
87

88
```javascript { .api }
89
use(plugin: Plugin): Metalsmith;
90

91
type Plugin = (
92
  files: Files,
93
  metalsmith: Metalsmith,
94
  callback: (error?: Error) => void
95
) => void | Promise<void>;
96
```
97

98
[Plugin System](./plugin-system.md)
99

100
### Build and Processing
101

102
Core build methods for processing files through the plugin pipeline and outputting results.
103

104
```javascript { .api }
105
build(callback?: BuildCallback): Promise<Files> | void;
106
process(callback?: BuildCallback): Promise<Files> | void;
107
run(files: Files, plugins?: Plugin[], callback?: BuildCallback): Promise<Files> | void;
108

109
type BuildCallback = (error: Error | null, files: Files) => void;
110
```
111

112
[Build and Processing](./build-processing.md)
113

114
### File Operations
115

116
File reading and writing operations for handling individual files and file collections.
117

118
```javascript { .api }
119
read(directory?: string, callback?: Callback): Promise<Files> | void;
120
readFile(filepath: string, callback?: (err: Error | null, file?: File) => void): Promise<File> | void;
121
write(files: Files, directory?: string, callback?: Callback): Promise<void> | void;
122
writeFile(filepath: string, data: File, callback?: (error: Error | null) => void): Promise<void> | void;
123
```
124

125
[File Operations](./file-operations.md)
126

127
### Front-matter Processing
128

129
Front-matter parsing and manipulation utilities for handling YAML/JSON metadata in files.
130

131
```javascript { .api }
132
frontmatter(options?: boolean | GrayMatterOptions): boolean | Metalsmith;
133

134
// Available via metalsmith.matter property
135
matter.parse(contents: Buffer | string): File;
136
matter.stringify(file: File): string;
137
matter.options(options?: GrayMatterOptions): GrayMatterOptions | void;
138
```
139

140
[Front-matter Processing](./frontmatter.md)
141

142
### Utilities and Helpers
143

144
Utility methods for path resolution, file matching, environment variables, and debugging.
145

146
```javascript { .api }
147
path(...paths: string[]): string;
148
match(patterns: string | string[], input?: string[], options?: object): string[];
149
env(name?: string | object, value?: any): any | Metalsmith;
150
ignore(files?: string | string[] | Function): string[] | Metalsmith;
151
watch(options?: boolean | string | string[] | object): boolean | object | Metalsmith;
152
```
153

154
[Utilities and Helpers](./utilities.md)
155

156
### Debugging and Logging
157

158
Debugging system with namespaced loggers and configurable output for development and troubleshooting.
159

160
```javascript { .api }
161
debug(namespace: string): Debugger;
162

163
interface Debugger {
164
  (message: string, ...args: any[]): void;
165
  info(message: string, ...args: any[]): void;
166
  warn(message: string, ...args: any[]): void;
167
  error(message: string, ...args: any[]): void;
168
}
169
```
170

171
[Debugging and Logging](./debugging.md)
172

173
### CLI Interface
174

175
Command-line interface for running Metalsmith builds from configuration files with various options and environment variable support.
176

177
```bash
178
metalsmith [options]
179
metalsmith build [options]
180
```
181

182
[CLI Interface](./cli.md)
183

184
## Core Types
185

186
```javascript { .api }
187
import { Stats } from 'fs';
188
import { Mode } from 'stat-mode';
189
import { Debugger as DebugDebugger } from 'debug';
190
import { GrayMatterFile } from 'gray-matter';
191
import { WatchOptions } from 'chokidar';
192

193
interface Files {
194
  [filepath: string]: File;
195
}
196

197
interface File<AdditionalProperties extends Record<string, unknown> = Record<string, unknown>> {
198
  contents: Buffer;
199
  stats?: Stats; 
200
  mode?: string;
201
} & AdditionalProperties
202

203
interface GrayMatterOptions {
204
  language?: string;
205
  excerpt?: boolean | ((file: GrayMatterFile<string>, options: GrayMatterOptions) => any);
206
  excerpt_separator?: string;
207
  delimiters?: string | string[];
208
  engines?: {
209
    [engine: string]: ((file: string) => any) | {
210
      parse: (file: string) => any;
211
      stringify?: (data: any) => string;
212
    };
213
  };
214
}
215

216
interface Debugger extends DebugDebugger {
217
  info: DebugDebugger;
218
  warn: DebugDebugger;
219
  error: DebugDebugger;
220
}
221

222
type Plugin = (files: Files, metalsmith: Metalsmith, callback: DoneCallback) => void | Promise<void>;
223
type DoneCallback = (err?: Error) => void;
224
type Callback = (err: Error | null, files: Files) => void;
225
type Ignore = (path: string, stat: Stats) => boolean;
226
```