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.
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.
Next let's scaffold out the content for the project with 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:
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
templates. Here's a breakdown of what those directories contain.
/src /src/* # pages /src/posts/* # blog posts /templates /templates/* # page templates to be reference from posts & pages /templates/partials/* # partial html files
The frontend assets are located in
/images /js /scss
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:
To create a new post, type the following command:
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
yo ironsmith to regenerate any files like
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!