Install it

npm install metalsmith

yarn add metalsmith

pnpm add metalsmith

Or use a starter

Get the feel of it

You want to build a website or blog with a static site generator. Well, here is our elevator pitch. It’s as easy as that:

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

Metalsmith(__dirname)         // __dirname defined by node.js:
                              // name of the directory of this file
  .metadata({                 // add any variable you want
                              // use them in layout-files
    sitename: "My Static Site & Blog",
    siteurl: "https://example.com/",
    description: "It's about saying »Hello« to the world.",
    generatorname: "Metalsmith",
    generatorurl: "https://metalsmith.io/"
  })
  .source('./src')            // source directory
  .destination('./build')     // destination directory
  .clean(true)                // clean destination before
  .use(collections({          // group all blog posts by internally
    posts: 'posts/*.md'       // adding key 'collections':'posts'
  }))                         // use `collections.posts` in layouts
  .use(markdown())            // transpile all md into html
  .use(permalinks({           // change URLs to permalink URLs
    relative: false           // put css only in /css
  }))
  .use(layouts())             // wrap layouts around html
  .build(function(err) {      // build process
    if (err) throw err;       // error handling is required
  });

The package exposes both a JavaScript API, and a CLI if you prefer. To see how they’re used check out the examples or the walkthrough.

You can follow along with a detailed walkthrough or have a go with a very minimal example:

git clone https://github.com/metalsmith/metalsmith.git
cd metalsmith/examples/static-site
npm install
npm start

Build anything

We mainly refer to Metalsmith as a “static site generator”, but it’s a lot more than that. Since everything is a plugin, the core library is just an abstraction for manipulating a directory of files.

Which means you could just as easily use it to make…

• A Project Scaffolder

  1. Read template files from a directory.
  2. Parse files for template placeholders.
  3. Prompt user to fill in each placeholder.
  4. Render files with a templating engine.
  5. Write filled-in files to a new directory.

• A Build Tool

  1. Read files from a source directory.
  2. Convert Sass files to CSS.
  3. Concatenate CSS files.
  4. Minify the CSS file.
  5. Compress images files.
  6. Sprite images in a certain folder.
  7. Write files to a public directory.

• An eBook Generator

  1. Read chapter files from a directory.
  2. Build a table of contents from the tree.
  3. Convert Markdown to HTML.
  4. Convert Markdown to PDF.
  5. Convert Markdown to ePUB.
  6. Convert Markdown to MOBI.
  7. Write compiled files to a directory.

• Technical Docs

  1. Read files from a source directory.
  2. Convert Markdown files to HTML.
  3. Build a navigation from the tree.
  4. Render each file with a template.
  5. Write HTML to the static directory.

Deploy anywhere

Metalsmith builds are static folders. They can be compressed, archived, deployed to a CDN, Netlify, Github Pages, Gitlab Pages, SFTP’d to a shared host, or SSH’d to a custom server.

Use a starter

• 

  metalsmith/startbootstrap-clean-blog
  Code| Demo

  git clone https://github.com/metalsmith/startbootstrap-clean-blog
  cd startbootstrap-clean-blog && npm install

• 

  wernerglinka/metalsmith-bare-bones-starter
  Code| Demo

  git clone https://github.com/wernerglinka/metalsmith-bare-bones-starter
  cd metalsmith-bare-bones-starter && npm install

• 

  wernerglinka/metalsmith-blog-starter
  Code| Demo

  git clone https://github.com/wernerglinka/metalsmith-blog-starter
  cd metalsmith-blog-starter && npm install

• 

  wernerglinka/metalsmith-company-starter
  Code| Demo

  git clone https://github.com/wernerglinka/metalsmith-company-starter
  cd metalsmith-company-starter && npm install

• 

  webketje/metalsmith-starter-resume
  Code| Demo

  git clone https://github.com/webketje/metalsmith-starter-resume
  cd metalsmith-starter-resume && npm install