Everything is a Plugin

All of the logic in Metalsmith is handled by plugins. You simply chain them together. Here’s what the simplest blog looks like…

Metalsmith(__dirname)
  .use(markdown)
  .use(templates('handlebars'))
  .build();

…but what if you want to get fancier by hiding your unfinished drafts and using custom permalinks? Just add plugins…

Metalsmith(__dirname)
  .use(drafts)
  .use(markdown)
  .use(permalinks('posts/:title'))
  .use(templates('handlebars'))
  .build();

…it’s as easy as that!

How does it work?

Metalsmith works in three simple steps:

1. Read all the files in a source directory.
2. Invoke a series of plugins that manipulate the files.
3. Write the results to a destination directory!

Each plugin is invoked with the contents of the source directory, with every file parsed for optional YAML front-matter, like so…

---
title: A Catchy Title
draft: true
---

An unfinished article...

{
  'path/to/my-file.md': {
    title: 'A Catchy Title',
    draft: true,
    contents: new Buffer('An unfinished article...')
  }
}

The plugins can manipulate the files however they want, and writing one is super simple. Here’s the code for the drafts plugin from above:

function drafts(files, metalsmith, done){
  for (var file in files) {
    if (files[file].draft) delete files[file];
  }
  done();
}

Of course they can get a lot more complicated too. That’s what makes Metalsmith powerful; the plugins can do anything you want.

Install it

Metalsmith and its plugins can be installed with npm:

$ npm install metalsmith

The package exposes both a Javascript API, and CLI in case you’re used to that type of workflow from other static site generators.

A Little Secret

We keep referring to Metalsmith as a “static site generator”, but it’s a lot more than that. Since everything is a plugin, the core library is actually 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.

The plugins are all reusable. That PDF generator plugin for eBooks? Use it to generate PDFs for each of your blog posts too!

Check out the code examples to get an idea for what’s possible.

The Plugins

The core Metalsmith library doesn’t bundle any plugins by default. You just require new ones as needed, or make your own!

Here’s a list of the current plugins:

• Build Date

  Add a build date, for things like feeds or sitemaps.

• Collections

  Group files together, like blog posts. That way you can loop over them to generate an index, or add 'next' and 'previous' links between them.

• Drafts

  Hide any files marked as drafts.

• Excerpts

  Extract the first paragraph from the beginning of any Markdown file.

• Ignore

  Ignore any files that match a pattern.

• Markdown

  Convert Markdown files to HTML.

• Metadata

  Load metadata from JSON or YAML files.

• Permalinks

  Apply custom permalinks and rename files to be nested properly for static sites, basically converting about.html into about/index.html.

• Templates

  Render any file through a templating engine of your choice.

If you write your own plugin, submit a pull request to the metalsmith.io repository and it will show up here!