Metalsmith is a simple, pluggable static site generator that takes a directory of files and runs them through a series of plugins to transform them into a website. It’s highly flexible and allows you to use plugins for various tasks like parsing markdown, processing images, generating HTML, etc. Here’s a basic tutorial to get you started with Metalsmith:

1. Installation

First, you need to have Node.js and npm installed on your system. Then you can install Metalsmith globally or locally within your project:

npm install -g metalsmith

2. Project Setup

Create a new directory for your Metalsmith project and navigate into it:

mkdir my-metalsmith-project
cd my-metalsmith-project

3. Initialize Project

Initialize your project with npm to create a package.json file:

npm init -y

4. Install Metalsmith and Plugins

Install Metalsmith and any plugins you’ll need for your project. For example, let’s install plugins for processing markdown files:

npm install metalsmith metalsmith-markdown --save-dev

5. Create Source Files

Create a src directory where you’ll place your source files. For example, you can create markdown files for your website content:

# Hello, World!

This is a Metalsmith tutorial.

Save this as src/index.md.

6. Configure Metalsmith

Create a metalsmith.js file in your project’s root directory to configure Metalsmith and define the build process:

const metalsmith = require('metalsmith');
const markdown = require('metalsmith-markdown');

metalsmith(__dirname)
    .source('src') // Source directory
    .destination('build') // Build directory
    .use(markdown()) // Parse markdown files
    .build(function(err) {
        if (err) {
            console.error(err);
        } else {
            console.log('Build completed!');
        }
    });

7. Build Your Website

Now, you can build your website by running the Metalsmith script:

node metalsmith.js

This will process your source files according to the configured plugins and generate the output in the build directory.

8. Explore Output

Explore the generated output in the build directory to see your transformed files.

9. Customize and Extend

You can customize your build process by adding more plugins and configuring them according to your requirements. Metalsmith has a wide range of plugins available for tasks like minification, templating, image processing, etc.

10. Automate

You can automate the build process using npm scripts or tools like Gulp or Grunt. Define scripts in your package.json file to run the Metalsmith build command.

That’s a basic overview of getting started with Metalsmith. From here, you can explore the extensive plugin ecosystem and tailor Metalsmith to fit your specific project needs.