Metalsmith

https://metalsmith.io/docs/
Admin
Metalsmith is a simple, pluggable static site generator for Node.js that transforms source files...
Tokens:15,955
Snippets:170
Trust Score:9.7
Update:6 months ago
Show doc for...
Tokens:
Raw
### Metalsmith CLI usage examples

Source: https://metalsmith.io/docs/cli

Common usage patterns for building projects and managing environment variables.

```bash
# build from metalsmith.json:
metalsmith

# build from lib/config.json:
metalsmith --config lib/config.json

# override env vars
metalsmith --env NODE_ENV=production TZ=Europe/London

# override DEBUG env var (shortcut)
metalsmith --debug @metalsmith/*
```

--------------------------------

### Configure Metalsmith via JSON

Source: https://metalsmith.io/docs/usage-guide

Examples of separate configuration files for development and production environments.

```json
{
  "plugins": [
    { "@metalsmith/markdown": { } },
    { "@metalsmith/layouts": { } }
  ]
}
```

```json
{
  "plugins": [
    { "@metalsmith/drafts": { } },
    { "@metalsmith/markdown": { } },
    { "@metalsmith/layouts": { } },
    { "metalsmith-html-minifier": { } }
  ]
}
```

--------------------------------

### Create and Navigate to Project Folder (Linux/Mac)

Source: https://metalsmith.io/docs/getting-started

Create a new directory for your Metalsmith project and change into it. This is the first step before installing Metalsmith.

```bash
mkdir ~/Documents/metalsmith-website && cd ~/Documents/metalsmith-website
```

--------------------------------

### Defining YAML and JSON front matter

Source: https://metalsmith.io/docs/getting-started

Examples of how to define metadata at the top of a file using YAML or JSON syntax.

```yaml
---
title: Hello World
keywords:
  - hello
  - world
draft: false
---
Welcome to my blog
```

```json
---
{
  "title": "Hello World",
  "keywords": ["hello","world"],
  "draft": false
}
---
Welcome to my blog
```

--------------------------------

### Inspect plugin list output

Source: https://metalsmith.io/docs/writing-plugins

Example output showing how named functions appear when inspecting the metalsmith.plugins array.

```text
plugins: [
  [Function: drafts],
  [Function: metalsmithFavicons],
  [Function: collections],
  [Function: invertInPlaceExtensions],
  [Function (anonymous)],
  [Function: tableOfContents],
  [Function (anonymous)],
  [Function (anonymous)],
  [Function: sass],
  [Function: postcss],
  [Function: jsbundle],
  [Function: plugin],
  [Function (anonymous)]
]
```

--------------------------------

### Initialize Metalsmith with ES Modules

Source: https://metalsmith.io/docs/usage-guide

Use this setup for projects utilizing ES modules. It requires extra lines to determine the current directory.

```javascript
import { dirname } from 'path'
import { fileURLToPath } from 'url'
import Metalsmith from 'metalsmith'

const __dirname =  dirname(fileURLToPath(import.meta.url))

Metalsmith(__dirname)
```

--------------------------------

### Initialize Metalsmith with CommonJS

Source: https://metalsmith.io/docs/usage-guide

Standard initialization for projects using CommonJS modules. This is the most common setup.

```javascript
const Metalsmith = require('metalsmith')

Metalsmith(__dirname)
```

--------------------------------

### Create and Navigate to Project Folder (Windows)

Source: https://metalsmith.io/docs/getting-started

Create a new directory for your Metalsmith project and change into it using Windows command prompt. This is the first step before installing Metalsmith.

```batch
mkdir %userProfile%\Documents\metalsmith-website && cd %userProfile%\Documents\metalsmith-website
```

--------------------------------

### Install Common Metalsmith Plugins with pnpm

Source: https://metalsmith.io/docs/getting-started

Install essential Metalsmith plugins for collections, markdown processing, permalinks, and layouts using pnpm. These plugins extend Metalsmith's functionality.

```bash
pnpm add @metalsmith/collections @metalsmith/markdown @metalsmith/permalinks @metalsmith/layouts
```

--------------------------------

### Install Common Metalsmith Plugins with npm

Source: https://metalsmith.io/docs/getting-started

Install essential Metalsmith plugins for collections, markdown processing, permalinks, and layouts using npm. These plugins extend Metalsmith's functionality.

```bash
npm install @metalsmith/collections @metalsmith/markdown @metalsmith/permalinks @metalsmith/layouts
```

--------------------------------

### Install Metalsmith with pnpm

Source: https://metalsmith.io/docs/getting-started

Install the Metalsmith core package using pnpm. This command adds Metalsmith to your project's dependencies.

```bash
pnpm add metalsmith
```

--------------------------------

### Install Common Metalsmith Plugins with yarn

Source: https://metalsmith.io/docs/getting-started

Install essential Metalsmith plugins for collections, markdown processing, permalinks, and layouts using yarn. These plugins extend Metalsmith's functionality.

```bash
yarn add @metalsmith/collections @metalsmith/markdown @metalsmith/permalinks @metalsmith/layouts
```

--------------------------------

### Install Metalsmith with npm

Source: https://metalsmith.io/docs/getting-started

Install the Metalsmith core package using npm. This command adds Metalsmith to your project's dependencies.

```bash
npm install metalsmith
```

--------------------------------

### Run Snapshot Plugin in Metalsmith

Source: https://metalsmith.io/docs/writing-plugins

Example usage of the snapshot plugin within a Metalsmith build pipeline.

```javascript
const Metalsmith = require('metalsmith')
const snapshot = require('./plugins/snapshot')

Metalsmith(__dirname)
  // log all file data
  .use(snapshot()) 
  // log each .html file's last modified date
  .use(snapshot({ keys: ['stats.mtime'], pattern: '**/*.html' }))
  .build((err, files) => {
    if (err) throw err
    console.log('Build success!')
  })
```

--------------------------------

### Install Metalsmith with yarn

Source: https://metalsmith.io/docs/getting-started

Install the Metalsmith core package using yarn. This command adds Metalsmith to your project's dependencies.

```bash
yarn add metalsmith
```

--------------------------------

### Configure gh-pages Deploy Script

Source: https://metalsmith.io/docs/deployment

Example of how to add a 'deploy' script to your package.json file to automate the deployment of the 'build' directory using the gh-pages package.

```json
{
  "scripts": {
    "deploy": "gh-pages -d build"
  }
}

```

--------------------------------

### Build Website with Metalsmith (ESM)

Source: https://metalsmith.io/docs/getting-started

Use this ESM module to configure and build your static site. Ensure all necessary plugins are installed.

```javascript
import { fileURLToPath } from 'node:url'
import { dirname } from 'path'
import Metalsmith from 'metalsmith'
import collections from '@metalsmith/collections'
import layouts from '@metalsmith/layouts'
import markdown from '@metalsmith/markdown'
import permalinks from '@metalsmith/permalinks'

const __dirname = dirname(fileURLToPath(import.meta.url))
const t1 = performance.now()

Metalsmith(__dirname)         // parent directory of this file
  .source('./src')            // source directory
  .destination('./build')     // destination directory
  .clean(true)                // clean destination before
  .env({
    DEBUG: process.env.DEBUG,
    NODE_ENV: process.env.NODE_ENV
  })
  .metadata({
    sitename: "My Static Site & Blog",
    siteurl: "https://example.com/",
    description: "It's about saying »Hello« to the world.",
    generatorname: "Metalsmith",
    generatorurl: "https://metalsmith.io/"
  })
  .use(collections({
    posts: 'posts/*.md'
  }))
  .use(markdown())
  .use(permalinks())
  .use(layouts({
    pattern: '**/*.html'
  }))
  .build((err) => {
    if (err) throw err
    console.log(`Build success in ${((performance.now() - t1) / 1000).toFixed(1)}s`)
  });

```

--------------------------------

### Abort Plugin with Callback

Source: https://metalsmith.io/docs/writing-plugins

Example of stopping a build by passing an error to the done callback.

```javascript
/**
 * A plugin that will conditionally abort the build
 *  @param {boolean} [confirm=true]
 *  @example metalsmith.use(abort())
 **/
function initAbort(confirm = true) {
  return function abort(metalsmith, files, done) {
    if (confirm) {
      const error = new Error('Build aborted')
      error.name = 'EBUILD_ABORTED'
      error.code = 'build_aborted'
      done(error)
    }
    done()
  }
}

module.exports = initAbort
```

--------------------------------

### Build Website with Metalsmith (CJS)

Source: https://metalsmith.io/docs/getting-started

Use this CommonJS module to configure and build your static site. Ensure all necessary plugins are installed.

```javascript
const Metalsmith  = require('metalsmith')
const collections = require('@metalsmith/collections')
const layouts     = require('@metalsmith/layouts')
const markdown    = require('@metalsmith/markdown')
const permalinks  = require('@metalsmith/permalinks')

const t1 = performance.now()

Metalsmith(__dirname)         // parent directory of this file
  .source('./src')            // source directory
  .destination('./build')     // destination directory
  .clean(true)                // clean destination before
  .env({
    DEBUG: process.env.DEBUG,
    NODE_ENV: process.env.NODE_ENV
  })
  .metadata({
    sitename: "My Static Site & Blog",
    siteurl: "https://example.com/",
    description: "It's about saying »Hello« to the world.",
    generatorname: "Metalsmith",
    generatorurl: "https://metalsmith.io/"
  })
  .use(collections({
    posts: 'posts/*.md'
  }))
  .use(markdown())
  .use(permalinks())
  .use(layouts({
    pattern: '**/*.html'
  }))
  .build((err) => {
    if (err) throw err
    console.log(`Build success in ${((performance.now() - t1) / 1000).toFixed(1)}s`)
  })

```

--------------------------------

### Chaining Multiple Plugins with Logging

Source: https://metalsmith.io/docs/usage-guide

Example of chaining multiple core Metalsmith plugins, interspersed with `console.log` for debugging intermediate states.

```javascript
const Metalsmith = require('metalsmith')
const drafts = require('@metalsmith/drafts')
const markdown = require('@metalsmith/markdown')
const layouts = require('@metalsmith/layouts')

Metalsmith(__dirname)
  .use(console.log)
  .use(drafts())
  .use(console.log)
  .use(markdown())
  .use(console.log)
  .use(layouts())
  .use(console.log)
  .build((err, files) => {
    if (err) throw err
    console.log('Build success!')
  })
```

--------------------------------

### View error stack trace

Source: https://metalsmith.io/docs/writing-plugins

Example of an error stack trace showing how a named function helps identify the source of an issue.

```text
UnhandledPromiseRejectionWarning: EINVALID_ARGUMENT: Requiredoption cannot be empty
  at Ware.snapshot (/home/user/ms/metalsmith.js:9:19)
  at Ware.<anonymous> (/home/user/ms/node_modules/wrap-fn/index.js:45:19)
```

--------------------------------

### Initialize Metalsmith Plugin with Options

Source: https://metalsmith.io/docs/writing-plugins

Wrap plugin logic in an initializer function to accept and process options before the build starts. The initializer runs before the plugin body.

```javascript
function initSnapshot(options = {}) {
  // code in the initializer runs before metalsmith.build()
  return function snapshot(files, metalsmith) {
    // code in the plugin body runs as part of metalsmith.build()
    console.log(files, metalsmith)
  }
}
const Metalsmith = require('metalsmith')

Metalsmith(__dirname)
  .use(initSnapshot())
  .build((err, files) => {
    if (err) throw err
    console.log('Build success!')
  })
```

```javascript
+ function initSnapshot(options = {}) {
  // code in the initializer runs before metalsmith.build()
-   function snapshot(files, metalsmith) {
    // code in the plugin body runs as part of metalsmith.build()
+   return function snapshot(files, metalsmith) {
      console.log(files, metalsmith)
    }
+ }
  const Metalsmith = require('metalsmith')

  Metalsmith(__dirname)
-   .use(snapshot)
+   .use(initSnapshot())
    .build((err, files) => {
      if (err) throw err
      console.log('Build success!')
    })
```

--------------------------------

### Represent file object after layout application

Source: https://metalsmith.io/docs/getting-started

Example of the internal file object structure after the layouts plugin has injected content into the template.

```javascript
{
  'relative_to_sourcepath/my-file/index.html': {
    title: 'A Catchy Title',
    draft: false,
    contents: `<!doctype html><html><head>
               <title>A Catchy Title</title></head><body>
               <p>An unfinished article...</p>
               </body></html>`,
    path: 'myfile',
    ...      
  }
}
```

--------------------------------

### Represent file object after markdown transformation

Source: https://metalsmith.io/docs/getting-started

Example of the internal file object structure after the markdown plugin has processed the file.

```javascript
{
  'relative_to_sourcepath/my-file.html': {
    title: 'A Catchy Title',
    draft: false,
    contents: '<p>An unfinished article...</p>',
    ...
  }
}
```

--------------------------------

### Represent file object after permalinks transformation

Source: https://metalsmith.io/docs/getting-started

Example of the internal file object structure after the permalinks plugin has renamed the file and added a path property.

```javascript
{
  'relative_to_sourcepath/my-file/index.html': {
    title: 'A Catchy Title',
    draft: false,
    contents: '<p>An unfinished article...</p>',
    path: 'myfile',
    ...
  }
}
```

--------------------------------

### Set Default File Metadata with @metalsmith/default-values in metalsmith.js

Source: https://metalsmith.io/docs/usage-guide

Use the @metalsmith/default-values plugin to automatically assign metadata to files based on patterns. This example sets a default layout for posts and marks files in 'drafts' as drafts.

```javascript
const Metalsmith = require('metalsmith')
const defaultValues = require('@metalsmith/default-values')
const drafts = require('@metalsmith/drafts')
const markdown = require('@metalsmith/markdown')
const layouts = require('@metalsmith/layouts')

Metalsmith(__dirname)
  .use(defaultValues([
    {
      pattern: 'posts/**/*.md',
      defaults: {
        layout: 'post.hbs'
      }
    },
    {
      pattern: 'drafts/**',
      defaults: { draft: true }
    }
  ]))
  .use(process.env.NODE_ENV === 'production' ? drafts() : () => {})
  .use(markdown())
  .use(layouts())
  .build((err, files) => {
    if (err) throw err
    console.log('Build success')
  })
```

--------------------------------

### Display init command help

Source: https://metalsmith.io/docs/cli

View options available for initializing a new project.

```bash
metalsmith init --help
```

--------------------------------

### Display build command help

Source: https://metalsmith.io/docs/cli

View options available for the build command.

```bash
metalsmith build --help
```

--------------------------------

### Use console.log as a Plugin

Source: https://metalsmith.io/docs/usage-guide

Demonstrates using `console.log` as a simple plugin to inspect the build process. This is useful for debugging.

```javascript
const Metalsmith = require('metalsmith')

Metalsmith(__dirname)
  .use(console.log)
  .build((err, files) => {
    if (err) throw err
    console.log('Build success!')
  })
```

--------------------------------

### metalsmith init

Source: https://metalsmith.io/docs/cli

Initializes a new Metalsmith project by cloning a repository and setting up the file structure.

```APIDOC
## metalsmith init

### Description
Initialize a new metalsmith project from a git repo. Runs a sequence of git and filesystem commands.

### Parameters
#### Arguments
- **source** (string) - Optional - Source directory (default: "starters/bare")
- **destination** (string) - Optional - Destination directory (default: ".")

#### Options
- **-f, --force** (boolean) - Optional - Force overwriting a non-empty directory (default: false)
- **-o, --origin** (string) - Optional - Origin repository (https or ssh url, or a directory path). Defaults to https://github.com/metalsmith/resources
- **-h, --help** (flag) - Optional - Display help for command
```

--------------------------------

### Display clean command help

Source: https://metalsmith.io/docs/cli

View options available for the clean command.

```bash
metalsmith clean --help
```

--------------------------------

### Display Metalsmith CLI help

Source: https://metalsmith.io/docs/cli

View the main help menu for the Metalsmith CLI.

```bash
metalsmith --help
```

--------------------------------

### Deploy Build Output with gh-pages CLI

Source: https://metalsmith.io/docs/deployment

Command-line instruction to deploy the contents of the 'build' directory to GitHub Pages using the gh-pages NPM package.

```bash
node_modules/.bin/gh-pages -d build

```

--------------------------------

### Implement a basic local plugin

Source: https://metalsmith.io/docs/writing-plugins

Demonstrates using a simple function as a plugin within a Metalsmith build pipeline.

```javascript
const Metalsmith = require('metalsmith')

Metalsmith(__dirname)
  .use(console.log) // logs files, then metalsmith
  .build((err, files) => {
    if (err) throw err
    console.log('Build success!')
  })
```

--------------------------------

### Loop Over Files in Metalsmith Plugin

Source: https://metalsmith.io/docs/writing-plugins

Demonstrates various ways to iterate over all files within a Metalsmith build using `Object.values`, `Object.entries`, and `Object.keys`. Also shows how to use `metalsmith.match` with a glob pattern to iterate over a subset of files.

```javascript
function loopOverFiles(files, metalsmith) {
  // useful if you only need access to the file
  Object.values(files).forEach(file => { /* ...code */ })

  // useful if you need access to both filepath & file
  Object.entries(files).forEach(([filepath, file]) => { /* ...code */ })

  // alternative if you need access to both filepath & file
  Object.keys(files).forEach(filepath => {
    const file = files[filepath]
    /* ...code */ 
  })

  // same as previous but with normalized glob filtering
  const all = '**'
  metalsmith.match(all).forEach(filepath => {
    const file = files[filepath]
    /* ...code */ 
  })
}
```

--------------------------------

### File Actions in Metalsmith

Source: https://metalsmith.io/docs/writing-plugins

Demonstrates adding, updating, renaming, moving, and removing files within the Metalsmith build process. Ensure the 'files' object and 'metalsmith' instance are available.

```javascript
function fileActions(files, metalsmith) {
  const name = 'index.html'
  const file = {
    contents: Buffer.from('Hello world'),
    mode: '0664'
  }
  // check if a file is included
  Object.prototype.hasOwnProperty.call(files, name)

  // add a file
  files[name] = file

  // change the file's metadata
  files[name].description = 'I\'s about saying hello to the world'

  // change the file's contents
  files[name].contents = Buffer.from(files[name].contents.toString().replace('world', 'plugin author'))

  // rename a file
  const newName = 'newindex.html'
  files[newName] = files[name]
  delete files[name]

  // move a file to a subdirectory
  const newPath = require('path').join('blog', newName)
  files[newPath] = files[newName]
  delete files[newName]

  // remove a file
  delete files[newPath]
}
```

--------------------------------

### Configure development watcher and browser sync

Source: https://metalsmith.io/docs/usage-guide

Uses chokidar to watch source files and browsersync to trigger reloads after the build completes.

```javascript
const browserSync = require('browser-sync')
const chokidar = require('chokidar')
const msBuild = require('./metalsmith.js') // <-- here is our metalsmith build

chokidar
  .watch(['src','layouts'], {
    // avoids causing duplicate builds for initially detected files and folders
    ignoreInitial: true
  })
  .on('ready', () => browserSync.init({
    host: 'localhost',
    port: 3000,
    server: './build',
    injectChanges: false,  // false = prefer full reload
    interval: 2000         // adjust if the build hasn't finished before the browser opens
  }))
  .on('all', async (...args) => {
    await msBuild()
    browserSync.reload()
  })

(async function() {
  await msBuild()
}())
```

--------------------------------

### SFTP Deployment Script with LFTP

Source: https://metalsmith.io/docs/deployment

This bash script automates the synchronization of a Metalsmith build directory to a remote server using LFTP over SFTP. Configure SFTP_SERVER, SFTP_PORT, SFTP_USER, SFTP_PASS, and DOCUMENT_ROOT variables. Run with --dry-run for a simulation.

```bash
#!/bin/sh

# if you include this script in git versioning, remove the variables part and define them locally,
# in CI pipelines or on a build server environment instead, eg through the SFTP_USER's .bashrc file
SFTP_SERVER=mysiteorip.com
SFTP_PORT=22
SFTP_USER=root
SFTP_PASS=xxxx
DOCUMENT_ROOT=/var/www/mysiteroot/
MS_DESTINATION=$PWD/build

if [ "$1" == "--dry-run" ]
then
  lftp -d -c "set sftp:auto-confirm yes; open -d -p $SFTP_PORT -u \"$SFTP_USER,$SFTP_PASS\" $SFTP_SERVER; mirror --reverse --verbose --delete --dry-run $MS_DESTINATION/ $DOCUMENT_ROOT; quit"
else 
  lftp -d -c "set sftp:auto-confirm yes; open -d -p $SFTP_PORT -u \"$SFTP_USER,$SFTP_PASS\" $SFTP_SERVER; mirror --reverse --verbose --delete $MS_DESTINATION/ $DOCUMENT_ROOT; quit"
fi

```

--------------------------------

### Configure Metalsmith build chain in JSON

Source: https://metalsmith.io/docs/getting-started

Equivalent configuration for the Metalsmith build process using a JSON file.

```json
{
  "source": "src",
  "destination": "build",
  "plugins": [
    { "markdown": true },
    { "layouts": true },
    { "writemetadata": {
      "pattern": ["**/*"],
      "ignorekeys": ["next", "previous"],
      "bufferencoding": "utf8"
    } }
  ]
}
```

--------------------------------

### Run Metalsmith CLI with specific configurations

Source: https://metalsmith.io/docs/usage-guide

Commands to execute the build process using different configuration files.

```bash
metalsmith --config metalsmith.dev.json
```

```bash
metalsmith --config metalsmith.json
```

--------------------------------

### Basic Metalsmith Build for GitHub Pages

Source: https://metalsmith.io/docs/deployment

Use this Metalsmith configuration to build your site and output it to the 'docs' directory, suitable for GitHub Pages deployment from the root branch.

```javascript
Metalsmith(__dirname)
  .src('src')
  .destination('docs')
  .build((err, files) => {
    if (err) throw err
    console.log('Build success')
  })

```

--------------------------------

### Get File Path Components with Node.js Path Module

Source: https://metalsmith.io/docs/writing-plugins

Use the Node.js `path` module within a Metalsmith plugin to extract directory names, basenames, extensions, and absolute paths from file paths. This is useful for adding metadata about file locations to each file object.

```javascript
function getPaths(filepath, metalsmith) {

  // get the absolute path of the metalsmith working directory
  const msDir = metalsmith.directory() // => '/home/user/metalsmith'
  // get the absolute path of the metalsmith source directory
  const msSource = metalsmith.source() // => '/home/user/metalsmith/src'

  // get the relative path of a file
  filepath // => 'blog/index.html'

  // get the directory of a file relative to metalsmith.source()
  const dirname = path.dirname(filepath) // => 'blog'

  // get the filename of a file without the directories
  const basename = path.basename(filepath) // => 'index.html'

  // get the extension of a file
  const extname = path.extname(filepath) // => '.html'

  // get the filename of a file without the directories & extension
  const barebasename = path.basename(filepath, extname) // => 'index'

  // get the absolute path of a file (relative to filesystem root)
  const absPath = metalsmith.path(msSource, filepath) // => /home/user/metalsmith/src/blog/index.html

  // get the path of a file relative to metalsmith.directory()
  const msDirRelPath = path.relative(msDir, metalsmith.path(msSource, filepath)) // => src/blog/index.html

  return {
    filepath,
    dirname,
    basename,
    extname,
    barebasename,
    absPath,
    msDirRelPath
  }
}

// usage: metalsmith.use(paths())
module.exports = function initPaths() {
  return function paths(files, metalsmith) {
    Object.keys(files).forEach(key => {
      Object.assign(files[key], getPaths(key, metalsmith))
    })
  }
}
```

--------------------------------

### Implement Snapshot Plugin Logic

Source: https://metalsmith.io/docs/writing-plugins

Initial implementation of the snapshot plugin using lodash for metadata path manipulation.

```javascript
const get = require('lodash.get')
const set = require('lodash.set')
const defaultOptions = {
  pattern: '**',
  keys: null
}

function initSnapshot(options = {}) {
  return function snapshot(files, metalsmith) {
    options = { ...defaultOptions, ...options }

    const matchedPaths = metalsmith.match(options.pattern)

    const fileData = matchedPaths.reduce((result, filepath) => {
      const file = files[filepath]
      
      result[filepath] = file
      if (options.keys) {
        const filtered = {}
        options.keys.forEach(key => {
          set(filtered, key, get(file, key))
        })
        result[filepath] = filtered
      }

      return result
    }, {})

    console.log(fileData)
  }
}

module.exports = initSnapshot
```

```diff
+ const get = require('lodash.get')
+ const set = require('lodash.set')
const defaultOptions = {
  pattern: '**',
  keys: null
}

function initSnapshot(options = {}) {
  return function snapshot(files, metalsmith) {
    options = { ...defaultOptions, ...options }
-   // do stuff with options
+
+   const matchedPaths = metalsmith.match(options.pattern)
+ 
+   const fileData = matchedPaths.reduce((result, filepath) => {
+     const file = files[filepath]
+     
+     result[filepath] = file
+     if (options.keys) {
+       const filtered = {}
+       options.keys.forEach(key => {
+         set(filtered, key, get(file, key))
+       })
+       result[filepath] = filtered
+     }
+ 
+     return result
+   }, {})

-   console.log(files)
+   console.log(fileData)
  }
}

module.exports = initSnapshot
```

--------------------------------

### Implement Snapshot Plugin Write Option

Source: https://metalsmith.io/docs/writing-plugins

Logic for handling file snapshots within a Metalsmith plugin.

```javascript
        result[filepath] = file
  
        if (options.keys) {
          const filtered = {}
          options.keys.forEach(key => {
            set(filtered, key, get(file, key))
          })
          result[filepath] = filtered
        }
        
+       // handle new write option
+       if (options.write) {
+         let count = 1, snapshotPath
+         do {
+           snapshotPath = getSnapshotPath(filepath, count)
+           count++
+         } while (files.hasOwnProperty(snapshotPath))
+         files[snapshotPath] = {
+           contents: Buffer.from(JSON.stringify(result[filepath], null, 2))
+         }
+       }
  
        return result
      }, {})
  
      console.log(fileData)
    }
  }

  module.exports = initSnapshot
```

--------------------------------

### Configure Multiple Plugins in JSON

Source: https://metalsmith.io/docs/usage-guide

Configuration for multiple core Metalsmith plugins in `metalsmith.json`, including options for `@metalsmith/layouts`.

```json
{
  "plugins": [
    {"./plugin-console-log": true},
    {"@metalsmith/drafts": {}},
    {"./plugin-console-log": true},
    {"@metalsmith/markdown": {}},
    {"./plugin-console-log": true},
    {"@metalsmith/layouts": { "pattern": "**/*.html" }},
    {"./plugin-console-log": true},
  ]
}
```

--------------------------------

### Abort Plugin with Promise

Source: https://metalsmith.io/docs/writing-plugins

Alternative implementation using Promise rejection to signal build abortion.

```javascript
/**
 * A plugin that will conditionally abort the build
 *  @param {boolean} [confirm=true]
 *  @example metalsmith.use(abort())
 **/
function initAbort(confirm = true) {
  return function abort(metalsmith, files) {
    if (confirm) {
      const error = new Error('Build aborted')
      error.code = 'build_aborted'
      return Promise.reject(error)
    }
    return Promise.resolve()
  }
}

module.exports = initAbort
```

```diff
/**
 * A plugin that will conditionally abort the build
 *  @param {boolean} [confirm=true]
 *  @example metalsmith.use(abort())
 **/
function initAbort(confirm = true) {
  return function abort(metalsmith, files) {
    if (confirm) {
      const error = new Error('Build aborted')
      error.code = 'build_aborted'
-     done(error)
+     return Promise.reject(error)
    }
-   done()
+   return Promise.resolve()
  }
}

module.exports = initAbort
```

--------------------------------

### Match and Filter Files in Metalsmith

Source: https://metalsmith.io/docs/writing-plugins

Illustrates how to select and manipulate specific subsets of files in Metalsmith. This includes using array methods like `slice` and `filter` on file entries, and using `metalsmith.match` with glob patterns to target files, such as all JavaScript files.

```javascript
function matchFiles(files, metalsmith) {
  // match files using array filter
  Object.entries(files)
    .slice(0, 10)  // only apply to the first 10 files
    .filter(([filepath, file]) => !file.draft) // filter out files with draft:true
    .forEach(([filepath, file]) => { /* ...code */ })

  // 
  metalsmith.match('**/*.js')
    .forEach(filepath => {
      const file = files[filepath]
      /* ...code */
    })
}
```

--------------------------------

### Add Multiple External Files Asynchronously with Promises

Source: https://metalsmith.io/docs/writing-plugins

This plugin handles multiple asynchronous file reads in parallel using `Promise.all`. It returns a Promise that resolves when all files have been read and added to the build.

```javascript
const { basename } = require('path')

function initAddExternalFiles(filepaths = []) {
  return function addExternalFiles(files, metalsmith) {
    return Promise.all(filepaths.map(filepath => {
      return new Promise((resolve, reject) => {
        metalsmith.readFile(metalsmith.path(filepath), (err, file) => {
          if (err) reject(err)
          files[basename(filepath)] = file
          resolve()
        })
      })
    }))
  }
}

module.exports = initAddExternalFile

```

--------------------------------

### Configure console.log Plugin in JSON

Source: https://metalsmith.io/docs/usage-guide

Configuration for using `console.log` as a plugin via `metalsmith.json`. Requires a separate plugin file.

```json
{
  "plugins": [
    {"./plugin-console-log": true}
  ]
}
```

--------------------------------

### Add node_modules/.bin to PATH on Linux/Mac

Source: https://metalsmith.io/docs/getting-started

Add the Metalsmith CLI to your PATH by exporting it in your shell configuration file. Remember to source the file after modification.

```bash
export PATH=node_modules/.bin:$PATH
```

--------------------------------

### Metalsmith Configuration (JSON)

Source: https://metalsmith.io/docs/getting-started

Configure your Metalsmith build process using a JSON file. This is useful for simpler projects or when not using JavaScript for configuration.

```json
{
  "source": "src",
  "destination": "build",
  "clean": true,
  "env": {
    "DEBUG": "$DEBUG",
    "NODE_ENV": "$NODE_ENV"
  },
  "metadata": {
    "sitename": "My Static Site & Blog",
    "siteurl": "https://example.com/",
    "description": "It's about saying »Hello« to the world.",
    "generatorname": "Metalsmith",
    "generatorurl": "https://metalsmith.io/"
  },
  "plugins": [
    { "@metalsmith/collections": { "posts": "posts/*.md" }},
    { "@metalsmith/markdown": {}},
    { "@metalsmith/permalinks": {}},
    { "@metalsmith/layouts": { "pattern": "**/*.html" }}
  ]
}

```

--------------------------------

### Configure Metalsmith build chain in JavaScript

Source: https://metalsmith.io/docs/getting-started

Defines the build process using the Metalsmith API, including source, destination, and plugin sequence.

```javascript
Metalsmith(__dirname)            
  .source('src')      
  .destination('build')   
  .use(markdown())          
  .use(layouts())
  .use(writemetadata({            // write the JS object
    pattern: ['**/*'],            // for each file into .json
    ignorekeys: ['next', 'previous'],
    bufferencoding: 'utf8'        // also put 'content' into .json
  }))
  .build(function(err) {         
    if (err) throw err;          
  });
```

--------------------------------

### Defining multi-line strings in YAML

Source: https://metalsmith.io/docs/getting-started

Demonstrates using '>' to remove line breaks and '|' to preserve them in YAML front matter.

```yaml
description: >
  This is a long text string,
  but we actually only want the line breaks for readability in the source.
  The line breaks will be removed in the output.
```

```yaml
description: |
  This is a long text string.
  It should read like a poem
  So we want to preserve the line breaks.
```

--------------------------------

### metalsmith build

Source: https://metalsmith.io/docs/cli

Executes the Metalsmith build process based on configuration files and environment settings.

```APIDOC
## metalsmith build

### Description
Run a metalsmith build process.

### Parameters
#### Options
- **-c, --config** (path) - Optional - Configuration file location (default: "metalsmith.json")
- **--env** (setting...) - Optional - Set or override one or more metalsmith environment variables.
- **--debug** (flag) - Optional - Set or override debug namespaces
- **--dry-run** (flag) - Optional - Process metalsmith files without outputting to the file system
- **-h, --help** (flag) - Optional - Display help for command
```

--------------------------------

### Define and Merge Plugin Options

Source: https://metalsmith.io/docs/writing-plugins

Define default options for a plugin and merge them with user-provided options using the spread syntax. This ensures all options are available within the plugin.

```javascript
const defaultOptions = {
  pattern: '**',
  keys: null
}

function initSnapshot(options = {}) {
  return function snapshot(files, metalsmith) {
    options = { ...defaultOptions, ...options }
    // do stuff with options
    console.log(files, metalsmith)
  }
}

module.exports = initSnapshot
```

```javascript
+ const defaultOptions = {
+   pattern: '**',
+   keys: null
+ }
+ 
+ function initSnapshot(options = {}) {
+   return function snapshot(files, metalsmith) {
+     options = { ...defaultOptions, ...options }
+     console.log(files, metalsmith)
+   }
+ }
+ 
+ module.exports = initSnapshot
```

--------------------------------

### Representing multiple files as a Files object

Source: https://metalsmith.io/docs/getting-started

Demonstrates the final structure of the Files object containing multiple file representations.

```javascript
{
  'relative_to_sourcepath/file1.md': {
    title: 'A Catchy Title',
    draft: false,
    contents: 'An unfinished article...',
    mode: '0664',
    stats: {
      /* keys with information on the file */
    }    
  },
  'relative_to_sourcepath/file2.md': {
    title: 'An Even Better Title',
    draft: false,
    contents: 'One more unfinished article...',
    mode: '0664',
    stats: {
      /* keys with information on the file */
    }    
  }
}
```

--------------------------------

### Enable Debugging via metalsmith.env (API)

Source: https://metalsmith.io/docs/usage-guide

Enable all debugging logs by passing `true` to `metalsmith.env('DEBUG', true)`. This is equivalent to using the `*` wildcard.

```javascript
const Metalsmith = require('metalsmith')
Metalalsmith(__dirname)
  .env('DEBUG', true)
```

--------------------------------

### Enable Debugging via metalsmith.json with process.env.DEBUG (CLI)

Source: https://metalsmith.io/docs/usage-guide

Configure Metalsmith to use the OS-level `DEBUG` environment variable by setting `DEBUG: "$DEBUG"` in the `env` section of `metalsmith.json`.

```json
{
  "env": {
    "DEBUG": "$DEBUG"
  }
}
```

--------------------------------

### Gitlab CI Configuration for Metalsmith Deployment

Source: https://metalsmith.io/docs/deployment

This `.gitlab-ci.yml` file configures a Gitlab CI pipeline to test the project and deploy the Metalsmith site to Gitlab Pages. Ensure your `metalsmith.destination()` is set to 'public'.

```yaml
image: node:16

cache:
  paths:
    - node_modules/

stages:
  - test
  - deploy

workflow:
  rules:
    - if: $CI_COMMIT_BRANCH

before_script:
  npm install

test:
  stage: test
  script:
    - npm test

pages:
  stage: deploy
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
  script:
    # choose one of the following
    - NODE_ENV=production node metalsmith.js  # metalsmith.js uses Metalsmith JS API
    - NODE_ENV=production npm run build       # same as previous, but in npm script
    - NODE_ENV=production metalsmith          # via Metalsmith CLI
  artifacts:
    paths:
      - public
```

--------------------------------

### Bash Script for Rsync Deployment

Source: https://metalsmith.io/docs/deployment

This bash script automates deployment to a remote server using rsync over SSH. It requires SSH access and write permissions to the target directory. Use `--dry-run` for testing.

```bash
#!/bin/sh

# if you include this script in git versioning, remove the variables part and
# define them in the server environment instead, eg through the SSH_USER's .bashrc file
SSH_USER=root
REMOTE=mysiteorip.com
DOCUMENT_ROOT=/var/www/mysiteroot/
MS_DESTINATION=$PWD/build

if [ "$1" == "--dry-run" ]
then
  rsync -avhn ${SSH_USER}@${REMOTE}:${DOCUMENT_ROOT} $MS_DESTINATION --delete
else 
  rsync -avh ${SSH_USER}@${REMOTE}:${DOCUMENT_ROOT} $MS_DESTINATION --delete
fi

```

--------------------------------

### Define File Metadata using Front-Matter

Source: https://metalsmith.io/docs/usage-guide

Add metadata directly to your content files using front-matter. This metadata is specific to each file and is processed if front matter parsing is enabled.

```markdown
---
title: My first post went a little like this
description: A turn, an ending, and a twist
---
No more drafts and no more waiting
```

--------------------------------

### Static Options Validation

Source: https://metalsmith.io/docs/writing-plugins

Validate plugin options immediately during initialization by throwing an error.

```javascript
function initMyPlugin(options) {
  if (!options.requiredOption) {
    throw new Error('requiredOption is required')
  }
  return function MyPlugin() { ... }
}
```

--------------------------------

### Run Metalsmith with DEBUG enabled (Mac/Linux)

Source: https://metalsmith.io/docs/usage-guide

Execute your Metalsmith build script with debugging enabled for all logs by prefixing the command with `DEBUG=* node`.

```bash
DEBUG=* node metalsmith.js
```

--------------------------------

### Move Build Output to Branch Root

Source: https://metalsmith.io/docs/deployment

Bash command to move all files from the 'build' directory to the current directory (the root of the new branch) and then remove the empty 'build' directory.

```bash
mv build/** . && rmdir build

```

--------------------------------

### Add External File Asynchronously

Source: https://metalsmith.io/docs/writing-plugins

Use this plugin to read a file from the filesystem and add it to the Metalsmith build. It requires a filepath and uses a callback for asynchronous file reading.

```javascript
const { basename } = require('path')

function initAddExternalFile(filepath) {
  return function addExternalFile(files, metalsmith, done) {
    metalsmith.readFile(metalsmith.path(filepath), (err, file) => {
      if (err) done(err)
      files[basename(filepath)] = file
      done()
    })
  }
}

module.exports = initAddExternalFile

```

--------------------------------

### Enable Debugging via metalsmith.json (CLI)

Source: https://metalsmith.io/docs/usage-guide

Configure debugging to be enabled for all logs by setting `DEBUG: true` within the `env` section of your `metalsmith.json` file.

```json
{
  "env": {
    "DEBUG": true
  }
}
```

--------------------------------

### Add Write Option to Snapshot Plugin

Source: https://metalsmith.io/docs/writing-plugins

Extended plugin implementation that supports writing metadata snapshots to JSON files.

```javascript
const path = require('path')
const get = require('lodash.get')
const set = require('lodash.set')
const defaultOptions = {
  pattern: '**',
  keys: null,
  write: false
}

// get the matching snapshot path for a given filepath
function getSnapshotPath(filepath, index) {
  const name = path.basename(filepath, path.extname(filepath))
  const dir = path.dirname(filepath)
  return path.join(dir, `${name}.snapshot${index}.json`)
}

function initSnapshot(options = {}) {
  return function snapshot(files, metalsmith) {
    options = { ...defaultOptions, ...options }

    const matchedPaths = metalsmith.match(options.pattern)

    const fileData = matchedPaths.reduce((result, filepath) => {
      const file = files[filepath]
      
      result[filepath] = file

      if (options.keys) {
        const filtered = {}
        options.keys.forEach(key => {
          set(filtered, key, get(file, key))
        })
        result[filepath] = filtered
      }
      
      // handle new write option
      if (options.write) {
        let count = 1, snapshotPath
        do {
          snapshotPath = getSnapshotPath(filepath, count)
          count++
        } while (files.hasOwnProperty(snapshotPath))
        files[snapshotPath] = {
          contents: Buffer.from(JSON.stringify(result[filepath], null, 2))
        }
      }

      return result
    }, {})

    console.log(fileData)
  }
}

module.exports = initSnapshot
```

```diff
+ const path = require('path')
  const get = require('lodash.get')
  const set = require('lodash.set')
  const defaultOptions = {
    pattern: '**',
    keys: null,
    write: false
  }
  
+  // get the matching snapshot path for a given filepath
+  function getSnapshotPath(filepath, index) {
+    const name = path.basename(filepath, path.extname(filepath))
+    const dir = path.dirname(filepath)
+    return path.join(dir, `${name}.snapshot${index}.json`)
+  }
  
  function initSnapshot(options = {}) {
    return function snapshot(files, metalsmith) {
      options = { ...defaultOptions, ...options }
  
      const matchedPaths = metalsmith.match(options.pattern)
  
      const fileData = matchedPaths.reduce((result, filepath) => {
        const file = files[filepath]

```

--------------------------------

### Metadata Manipulation in Metalsmith

Source: https://metalsmith.io/docs/writing-plugins

Shows how plugins can read, add, and update metadata using the Metalsmith instance. This includes adding timestamps and making files accessible via metadata.

```javascript
function plugin(files, metalsmith) {
  // read metadata
  const metadata = metalsmith.metadata()
  
  // add a metadata key:value
  metadata.buildTimestamp = Date.now()

  // add multiple metadata key:value's
  Object.assign(metadata, {
    // make all html files available on metadata as "pages"
    pages: metalsmith.match('**/*.html').map(key => files[key])
  })

  // pass global metadata to all files in the "globalMetadata" key (not recommended)
  Object.keys(files).forEach(filepath => {
    files[filepath].globalMetadata = metadata
  })
}
```

--------------------------------

### Run Metalsmith with DEBUG enabled (cross-env)

Source: https://metalsmith.io/docs/usage-guide

Use the `cross-env` package to set the `DEBUG` environment variable, providing a cross-platform solution for enabling debugging logs.

```bash
cross-env DEBUG=* node metalsmith.js
```

--------------------------------

### Create Orphan Branch for GitHub Pages

Source: https://metalsmith.io/docs/deployment

Command to create a new, empty orphan branch named 'gh-pages'. This is useful for deploying build output to a separate branch without merge conflicts.

```bash
git switch --orphan gh-pages

```

--------------------------------

### Enable Specific Plugin Debugging (API)

Source: https://metalsmith.io/docs/usage-guide

To debug a specific plugin, like `@metalsmith/markdown`, provide its name with a wildcard to `metalsmith.env('DEBUG', '@metalsmith/markdown*')`.

```javascript
const Metalsmith = require('metalsmith')
Metalalsmith(__dirname)
  .env('DEBUG', '@metalsmith/markdown*')
```

--------------------------------

### Implement a named plugin

Source: https://metalsmith.io/docs/writing-plugins

Defines a named function to serve as a plugin, which improves clarity in logs and stack traces.

```javascript
function snapshot(files, metalsmith) {
 console.log(files, metalsmith)
}
const Metalsmith = require('metalsmith')

Metalsmith(__dirname)
  .use(snapshot)
  .build((err, files) => {
    if (err) throw err
    console.log('Build success!')
  })
```

```diff
+ function snapshot(files, metalsmith) {
+  console.log(files, metalsmith)
+ }
  const Metalsmith = require('metalsmith')

  Metalsmith(__dirname)
-   .use(console.log) // logs files, then metalsmith
+   .use(snapshot)
    .build((err, files) => {
      if (err) throw err
      console.log('Build success!')
    })
```

--------------------------------

### Set Default File Metadata with @metalsmith/default-values in metalsmith.dev.json

Source: https://metalsmith.io/docs/usage-guide

Configure the @metalsmith/default-values plugin in metalsmith.dev.json to apply default metadata to files based on patterns. This offers a declarative approach to setting defaults.

```json
{
  "plugins": [
    {
      "@metalsmith/default-values": [
        { "pattern": "posts/**/*.md", defaults: { "layout": "post.hbs" }},
        { "pattern": "drafts/**", defaults: { "draft": true }},
      ]
    },
    { "@metalsmith/drafts": {} },
    { "@metalsmith/markdown": {} },
    { "@metalsmith/layouts": {} }
  ]
}
```

--------------------------------

### Enable Debugging via process.env.DEBUG (API)

Source: https://metalsmith.io/docs/usage-guide

For older plugins that use the debug package directly, pass the operating system's `DEBUG` environment variable to Metalsmith using `metalsmith.env('DEBUG', process.env.DEBUG)`.

```javascript
const Metalsmith = require('metalsmith')
Metalalsmith(__dirname)
  .env('DEBUG', process.env.DEBUG)
```

--------------------------------

### Load Metadata from YAML File in metalsmith.json

Source: https://metalsmith.io/docs/usage-guide

Configure the @metalsmith/metadata plugin in metalsmith.json to load metadata from a YAML file. This is an alternative to defining it directly in the build script.

```json
{
  "plugins": [
    { "@metalsmith/metadata": { "site": "src/site.yaml" } }
  ]
}
```

--------------------------------

### Representing a file as a JavaScript object

Source: https://metalsmith.io/docs/getting-started

Shows the transformation of a markdown file into a JavaScript object with metadata and contents.

```text
---
title: A Catchy Title
draft: false
---

An unfinished article...
```

```javascript
{
  'post/my-file.md': {
    title: 'A Catchy Title',
    draft: false,
    contents: 'An unfinished article...',
    mode: '0664',
    stats: {
      /* keys with information on the file */
    }    
  }
}
```
Tokens:
Raw