An extremely simple, pluggable static site generator.
An extremely simple, pluggable static site generator.
In Metalsmith, all of the logic is handled by plugins. You simply chain them together. Here's what the simplest blog looks like...
Metalsmith(__dirname) .use(markdown()) .use(layouts('handlebars')) .build(function(err) { if (err) throw err; console.log('Build finished!'); });
...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(layouts('handlebars')) .build(function(err) { if (err) throw err; console.log('Build finished!'); });
...it's as easy as that!
Special thanks to Ian Storm Taylor, Andrew Meyer, Dominic Barnes, Andrew Goodricke and others for their contributions!
$ npm install metalsmith
Check out the website for a list of plugins.
Metalsmith works in three simple steps:
Each plugin is invoked with the contents of the source directory, and each file can contain YAML front-matter that will be attached as metadata, so a simple file like...
--- title: A Catchy Title date: 2014-12-01 ---An informative article.
...would be parsed into...
{ 'path/to/my-file.md': { title: 'A Catchy Title', date: new Date('2014-12-01'), contents: new Buffer('An informative article.') } }
...which any of the plugins can then manipulate however they want. And writing the plugins is incredibly simple, just take a look at the example drafts plugin.
Of course they can get a lot more complicated too. That's what makes Metalsmith powerful; the plugins can do anything you want!
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...
#metalsmithon freenode!
In addition to a simple Javascript API, the Metalsmith CLI can read configuration from a
metalsmith.jsonfile, so that you can build static-site generators similar to Jekyll or Wintersmith easily. The example blog above would be configured like this:
{ "source": "src", "destination": "build", "plugins": { "metalsmith-drafts": true, "metalsmith-markdown": true, "metalsmith-permalinks": "posts/:title", "metalsmith-layouts": "handlebars" } }
You can specify your plugins as either an object or array. Using an array would allow you to specify use of the same plugin multiple times. The above example is then defined as so:
{ "source": "src", "destination": "build", "plugins": [ {"metalsmith-drafts": true}, {"metalsmith-markdown": true}, {"metalsmith-permalinks": "posts/:title"}, {"metalsmith-templates": "handlebars"} ] }
And then just install
metalsmithand the plugins and run the metalsmith CLI...
$ node_modules/.bin/metalsmithMetalsmith · reading configuration from: /path/to/metalsmith.json Metalsmith · successfully built to: /path/to/build
Or if you install them globally, you can just use:
$ metalsmithMetalsmith · reading configuration from: /path/to/metalsmith.json Metalsmith · successfully built to: /path/to/build
Options recognised by
metalsmith.jsonare
source,
destination,
concurrency,
metadata,
cleanand
frontmatter- See "API" section below for usage.
Checkout the static site, Jekyll or Wintersmith examples to see the CLI in action.
If you want to use a custom plugin, but feel like it's too domain-specific to be published to the world, you can include plugins as local npm modules: (simply use a relative path from your root directory)
{ "plugins": { "./lib/metalsmith/plugin.js": true } }
Checkout the project scaffolder or build tool examples to see a real example of the Javascript API in use.
Create a new
Metalsmithinstance for a working
dir.
Add the given
pluginfunction to the middleware stack. Metalsmith uses ware to support middleware, so plugins should follow the same pattern of taking arguments of
(files, metalsmith, callback), modifying the
filesor
metalsmith.metadata()argument by reference, and then calling
callbackto trigger the next step.
Build with the given settings and a callback having signature
fn(err, files).
Set the relative
pathto the source directory, or get the full one if no
pathis provided. The source directory defaults to
./src.
Set the relative
pathto the destination directory, or get the full one if no
pathis provided. The destination directory defaults to
./build.
Set the maximum number of files to open at once when reading or writing. Defaults to
Infinity. To avoid having too many files open at once (
EMFILEerrors), set the concurrency to something lower than
ulimit -n.
Set whether to remove the destination directory before writing to it, or get the current setting. Defaults to
true.
Set whether to parse YAML frontmatter. Defaults to
true.
Ignore files/paths from being loaded into Metalsmith.
pathcan be a string, a function, or an array of strings and/or functions. Strings use the glob syntax from minimatch to match files and directories to ignore. Functions are called with the full path to the file as their first argument, and the
statobject returned by Node's
fs.statfunction as their second argument, and must return either
trueto ignore the file, or
falseto keep it.
Get the global metadata. This is useful for plugins that want to set global-level metadata that can be applied to all files.
Resolve any amount of
paths...relative to the working directory. This is useful for plugins who want to read extra assets from another directory, for example
./layouts.
Run all of the middleware functions on a dictionary of
filesand callback with
fn(err, files), where
filesis the altered dictionary.
Process the files like build without writing any files. Callback signature
fn(err, files).
Add metadata to your files to access these build features. By default, Metalsmith uses a few different metadata fields:
contents- The body content of the file, not including any YAML frontmatter.
mode- The numeric version of the file's mode.
You can add your own metadata in two ways:
Set the mode of the file. For example,
$ cat cleanup.sh-- mode: 0764 --
rm -rf .
would be built with mode
-rwxrw-r--, i.e. user-executable.
Metalsmith v2.0 and above uses generators which has some considerations for
node.js 0.12.xand below.
node.js 0.10.x
You have two options:
node.js(>=
0.12.x— see "Using
node.js 0.12.x" section below)
"metalsmith": "^1.7.0"in your
package.jsonand
npm installthat version.
node.js 0.12.x
You have three options:
node.jswith
--harmony_generatorsflag set.
node --harmony_generators my_script.js
package.json:
"scripts": {"start": "node --harmony_generators my_script.js"}. Run with
npm run
npm installharmonize and require before Metalsmith is used. e.g.
require("harmonize")(["harmony-generators"]);
"metalsmith": "^1.7.0"in your
package.jsonand
npm installthat version.
This project is no longer maintained by Segment. Instead, Andrew Goodricke, Andrew Meyer and Ismay are maintaining the project.