Popularity
8.2
Declining
Activity
8.5
-
7,737
107
667

Code Quality Rank: L5
Programming language: JavaScript
License: MIT License
Tags: Markdown     Static Site Generators     Blog     Generator     Website     Site     File     Static     Jekyll     Blacksmith     Wintersmith    
Latest version: v2.4.2

Metalsmith alternatives and similar modules

Based on the "Static Site Generators" category.
Alternatively, view Metalsmith alternatives based on common mentions on social networks and blogs.

  • docsify

    🃏 A magical documentation site generator.
  • Assemble

    Get the rocks out of your socks! Assemble makes you fast at web development! Used by thousands of projects for rapid prototyping, themes, scaffolds, boilerplates, e-books, UI components, API documentation, blogs, building websites/static site generator, an alternative to Jekyll for gh-pages and more! Gulp- and grunt-friendly.
  • Appwrite is an open source backend server that helps you build native iOS applications much faster with realtime APIs for authentication, databases, files storage, cloud functions and much more!
    Promo
  • Wintersmith

    A flexible static site generator
  • Phenomic

    Modern static website generator based on the React and Webpack ecosystem.
  • DocPad

    Empower your website frontends with layouts, meta-data, pre-processors (markdown, jade, coffeescript, etc.), partials, skeletons, file watching, querying, and an amazing plugin system. DocPad will streamline your web development process allowing you to craft powerful static sites quicker than ever before.
  • gray-matter

    Smarter YAML front matter parser, used by metalsmith, Gatsby, Netlify, Assemble, mapbox-gl, phenomic, vuejs vitepress, TinaCMS, Shopify Polaris, Ant Design, Astro, hashicorp, garden, slidev, saber, sourcegraph, and many others. Simple to use, and battle tested. Parses YAML by default but can also parse JSON Front Matter, Coffee Front Matter, TOML Front Matter, and has support for custom parsers. Please follow gray-matter's author: https://github.com/jonschlinkert
  • front-matter

    Extract YAML front matter from strings
  • Charge

    ⚡️ An opinionated, zero-config static site generator.

Do you think we are missing an alternative of Metalsmith or a related project?

Add another 'Static Site Generators' Module

README

Metalsmith

npm: version ci: build code coverage [license: MIT][license-url] Gitter chat

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!

Installation

NPM:

npm install metalsmith

Yarn:

yarn add metalsmith

Plugins

Check out the website for a list of plugins.

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, and each file can contain YAML front-matter that will be attached as metadata, so a simple file like...

---
title: A Catchy Title
date: 2021-12-01
---

An informative article.

...would be parsed into...

{
  'path/to/my-file.md': {
    title: 'A Catchy Title',
    date: <Date >,
    contents: <Buffer 7a 66 7a 67...>
  }
}

...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](examples/drafts-plugin/index.js).

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

The 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 simple project scaffolder.](examples/project-scaffolder)
  • [A simple build tool for Sass files.](examples/build-tool)
  • [A simple static site generator.](examples/static-site)
  • [A Jekyll-like static site generator.](examples/jekyll)
  • [A Wintersmith-like static site generator.](examples/wintersmith)

Resources

CLI

In addition to a simple Javascript API, the Metalsmith CLI can read configuration from a metalsmith.json file, 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": {} }
  ]
}

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-layouts": true }
  ]
}

And then just install metalsmith and the plugins and run the metalsmith CLI...

metalsmith

# Metalsmith · reading configuration from: /path/to/metalsmith.json
# Metalsmith · successfully built to: /path/to/build

Options recognised by metalsmith.json are source, destination, concurrency, metadata, clean and frontmatter - See "API" section below for usage.

Checkout the [static site](examples/static-site), [Jekyll](examples/jekyll) or [Wintersmith](examples/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 }]
}

API

See API reference at metalsmith.io

Metadata API

Add metadata to your files to access these build features. By default, Metalsmith uses a few different metadata fields:

You can add your own metadata in two ways:

mode

Set the mode of the file. For example, a cleanup.sh file with the contents

---
mode: 0764
---

#!/bin/sh

rm -rf .

would be built with mode -rwxrw-r--, i.e. user-executable.

Troubleshooting

Node Version Requirements

Metalsmith 3.0.0 will support NodeJS versions 12 and higher. Metalsmith 2.4.0 supports NodeJS versions 8 and higher. Metalsmith 2.3.0 and below support NodeJS versions all the way back to 0.12.

Credits

Special thanks to Ian Storm Taylor, Andrew Meyer, Dominic Barnes, Andrew Goodricke, Ismay Wolff, Kevin Van Lierde and others for their contributions!

[License](LICENSE)


*Note that all licence references and agreements mentioned in the Metalsmith README section above are relevant to that project's source code only.