tessl/npm-metalsmith

An extremely simple, pluggable static site generator for NodeJS

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Metalsmith

Name: tessl/npm-metalsmith
Author: tessl

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.

Package Information

Package Name: metalsmith
Package Type: npm
Language: JavaScript (with TypeScript definitions)
Installation: npm install metalsmith

Core Imports

import Metalsmith from "metalsmith";

For CommonJS:

const Metalsmith = require("metalsmith");

Basic Usage

import Metalsmith from "metalsmith";
import markdown from "@metalsmith/markdown";
import layouts from "@metalsmith/layouts";

const metalsmith = Metalsmith(__dirname)
  .source("./src")
  .destination("./build")
  .clean(true)
  .metadata({
    sitename: "My Static Site",
    siteurl: "https://example.com/"
  })
  .use(markdown())
  .use(layouts({
    pattern: "**/*.html"
  }))
  .build((err, files) => {
    if (err) throw err;
    console.log("Build finished!");
  });

Architecture

Metalsmith follows a simple three-step process:

Read: Files are read from the source directory and parsed (including YAML frontmatter)
Transform: A series of plugins manipulate the file objects
Write: The processed files are written to the destination directory

Key architectural components:

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

Capabilities

Core Configuration

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

function Metalsmith(directory: string): Metalsmith;

// Configuration methods
directory(path?: string): string | Metalsmith;
source(path?: string): string | Metalsmith;  
destination(path?: string): string | Metalsmith;
metadata(data?: object): object | Metalsmith;
clean(flag?: boolean): boolean | Metalsmith;
concurrency(max?: number): number | Metalsmith;

Core Configuration

Plugin System

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

use(plugin: Plugin): Metalsmith;

type Plugin = (
  files: Files,
  metalsmith: Metalsmith,
  callback: (error?: Error) => void
) => void | Promise<void>;

Plugin System

Build and Processing

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

build(callback?: BuildCallback): Promise<Files> | void;
process(callback?: BuildCallback): Promise<Files> | void;
run(files: Files, plugins?: Plugin[], callback?: BuildCallback): Promise<Files> | void;

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

Build and Processing

File Operations

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

read(directory?: string, callback?: Callback): Promise<Files> | void;
readFile(filepath: string, callback?: (err: Error | null, file?: File) => void): Promise<File> | void;
write(files: Files, directory?: string, callback?: Callback): Promise<void> | void;
writeFile(filepath: string, data: File, callback?: (error: Error | null) => void): Promise<void> | void;

File Operations

Front-matter Processing

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

frontmatter(options?: boolean | GrayMatterOptions): boolean | Metalsmith;

// Available via metalsmith.matter property
matter.parse(contents: Buffer | string): File;
matter.stringify(file: File): string;
matter.options(options?: GrayMatterOptions): GrayMatterOptions | void;

Front-matter Processing

Utilities and Helpers

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

path(...paths: string[]): string;
match(patterns: string | string[], input?: string[], options?: object): string[];
env(name?: string | object, value?: any): any | Metalsmith;
ignore(files?: string | string[] | Function): string[] | Metalsmith;
watch(options?: boolean | string | string[] | object): boolean | object | Metalsmith;

Utilities and Helpers

Debugging and Logging

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

debug(namespace: string): Debugger;

interface Debugger {
  (message: string, ...args: any[]): void;
  info(message: string, ...args: any[]): void;
  warn(message: string, ...args: any[]): void;
  error(message: string, ...args: any[]): void;
}

Debugging and Logging

CLI Interface

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

metalsmith [options]
metalsmith build [options]

CLI Interface

Core Types

import { Stats } from 'fs';
import { Mode } from 'stat-mode';
import { Debugger as DebugDebugger } from 'debug';
import { GrayMatterFile } from 'gray-matter';
import { WatchOptions } from 'chokidar';

interface Files {
  [filepath: string]: File;
}

interface File<AdditionalProperties extends Record<string, unknown> = Record<string, unknown>> {
  contents: Buffer;
  stats?: Stats; 
  mode?: string;
} & AdditionalProperties

interface GrayMatterOptions {
  language?: string;
  excerpt?: boolean | ((file: GrayMatterFile<string>, options: GrayMatterOptions) => any);
  excerpt_separator?: string;
  delimiters?: string | string[];
  engines?: {
    [engine: string]: ((file: string) => any) | {
      parse: (file: string) => any;
      stringify?: (data: any) => string;
    };
  };
}

interface Debugger extends DebugDebugger {
  info: DebugDebugger;
  warn: DebugDebugger;
  error: DebugDebugger;
}

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