Looking to give metalsmith a try but don't want to deal with configuration? Try out Ironsmith, a yeoman generator that packages common features for building out a blog with metalsmith, gulp and scss. Also included is a beautiful theme ported from jekyll called pixyll. Check out the live demo here.

System Prerequisites

Before we go on, you'll need node.js installed. Check out the following links for installing node for your operating system.

Install the tools

From your terminal, enter the following commands to install yeoman, ironsmith and gulp globally.

npm install -g yo generator-ironsmith gulp

Building the project

With that out of the way, let's create an empty directory to work in.

mkdir myawesomesite

Next let's scaffold out the content for the project with ironsmith.

yo ironsmith

After running that command the generator will ask you a series of questions. Type in your answers to the right of the questions and hit enter to submit them.

? enter a project name: (Ironsmith) myawesomesite
? enter a default author name: (Tyler Durden) Robert Paulson

Next you'll see a ton of console output and when it's over you'll be ready to build out your site.

Preview with Gulp

If everything went ok, you'll be able to preview your site at http://localhost:8000 by running the following command:

gulp preview

Your site should look very similar to this demo: eddywashere.github.io/ironsmith-demo/.

Understanding the project structure

The metalsmith content and templates are located in src and templates. Here's a breakdown of what those directories contain.

/src/* # pages
/src/posts/* # blog posts
/templates/* # page templates to be reference from posts & pages
/templates/partials/* # partial html files

The frontend assets are located in js, scss and images.


Included in the project is a configuration file, config.js. Use this to include information details about your site while running in development mode or production mode.

Create additional posts & pages

To create a new page, type the following command:

yo ironsmith:page

To create a new post, type the following command:

yo ironsmith:post

Deploying to github pages

If you link this project to a github repo, you'll be able to deploy to github pages with the following task:

gulp build:prod deploy

Staying up to date

To install updates to ironsmith, run the following command:

npm update generator-ironsmith -g

Then run yo ironsmith to regenerate any files like ironsmith.js or Gulpfile.js.

That's it!

Hopefully I covered everything you need to get started with metalsmith. In the future, I'd like Ironsmith to support options for more themes, better upgrades and last, but not least, refactor the build script. If I missed anything or if you find a bug, please feel free to submit a pr or create an issue at github.com/eddywashere/generator-ironsmith. Thanks!