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 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.js 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
/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 js
, scss
and images
.
/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:
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 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!
Comments