Core Configuration

/**
 * Initialize a new Metalsmith builder with a working directory
 * @param directory - Working directory path (absolute or relative to process.cwd())
 * @returns Metalsmith instance
 */
function Metalsmith(directory: string): Metalsmith;

import Metalsmith from "metalsmith";
import { fileURLToPath } from 'node:url';
import { dirname } from 'path';

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

// Can also be called without 'new'
const ms = new Metalsmith(__dirname);

/**
 * Set the working directory path
 * @param directory - Directory path (relative paths resolve to process.cwd())
 * @returns Metalsmith instance for chaining
 */
directory(directory: string): Metalsmith;

/**
 * Get the absolute working directory path
 * @returns Absolute path to working directory
 */
directory(): string;

/**
 * Set the source directory path (relative to working directory)
 * @param path - Source directory path
 * @returns Metalsmith instance for chaining
 */
source(path: string): Metalsmith;

/**
 * Get the absolute source directory path
 * @returns Absolute path to source directory
 */
source(): string;

metalsmith
  .source("./src")        // Set source to 'src' relative to working directory
  .source("content");     // Change to 'content' directory

const srcPath = metalsmith.source(); // Get current source path

/**
 * Set the destination directory path (relative to working directory)
 * @param path - Destination directory path
 * @returns Metalsmith instance for chaining
 */
destination(path: string): Metalsmith;

/**
 * Get the absolute destination directory path
 * @returns Absolute path to destination directory
 */
destination(): string;

/**
 * Set global metadata (merged with existing metadata)
 * @param metadata - Metadata object to merge
 * @returns Metalsmith instance for chaining
 */
metadata(metadata: object): Metalsmith;

/**
 * Get the current global metadata object
 * @returns Current metadata object
 */
metadata(): object;

metalsmith.metadata({
  sitename: "My Static Site",
  siteurl: "https://example.com/",
  author: "John Doe"
});

// Add more metadata later
metalsmith.metadata({
  buildDate: new Date(),
  version: "1.0.0"
});

const meta = metalsmith.metadata(); // Get all metadata

/**
 * Set whether to clean destination directory before writing
 * @param clean - True to clean destination, false to preserve existing files
 * @returns Metalsmith instance for chaining
 */
clean(clean: boolean): Metalsmith;

/**
 * Get the current clean setting
 * @returns Current clean setting
 */
clean(): boolean;

/**
 * Set maximum number of files to open at once
 * @param max - Maximum concurrent file operations (default: Infinity)
 * @returns Metalsmith instance for chaining
 */
concurrency(max: number): Metalsmith;

/**
 * Get the current concurrency limit
 * @returns Current concurrency limit
 */
concurrency(): number;

// Limit concurrent file operations to prevent EMFILE errors
metalsmith.concurrency(50);

// Set build configuration
metalsmith
  .source("src")
  .destination("build")
  .clean(true)
  .concurrency(100)
  .metadata({
    sitename: "My Blog",
    baseUrl: process.env.NODE_ENV === 'production' 
      ? 'https://myblog.com' 
      : 'http://localhost:3000'
  });

/**
 * Configure front-matter parsing options
 * @param frontmatter - Boolean to enable/disable or options object
 * @returns Metalsmith instance for chaining
 */
frontmatter(frontmatter: boolean | GrayMatterOptions): Metalsmith;

/**
 * Get the current front-matter configuration
 * @returns Current front-matter setting (boolean or options)
 */
frontmatter(): boolean | GrayMatterOptions;

interface GrayMatterOptions {
  /** Enable excerpt parsing from content */
  excerpt?: boolean;
  /** Separator for excerpt content */
  excerpt_separator?: string;
  /** Front-matter language (yaml, json, toml, etc.) */
  language?: string;
  /** Delimiters for front-matter blocks */
  delimiters?: string | string[];
  /** Custom parsing engines */
  engines?: object;
}

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

// Enable with custom options
metalsmith.frontmatter({
  excerpt: true,
  excerpt_separator: '<!-- more -->',
  language: 'yaml'
});

// Check if front-matter is enabled
if (metalsmith.frontmatter()) {
  console.log("Front-matter parsing is enabled");
}