Build a Static Blog using MetalSmith

Ever felt like you didn’t need all the frameworks currently existing to build something simple yet has all the features you want? A listing for an event? A static blog? In this article, we will be building a static blog using MetalSmith. Knowledge of HTML, CSS and JavaScript is required for this tutorial. Knowledge of Jade is also of additional benefit but not required.

What is MetalSmith?

Metalsmith is an extremely pluggable and lightweight static site generator. What is a static site? It’s site delivered to the user as stored. Working with Metalsmith is entirely Vanilla JavaScript — no frameworks whatsoever. When we say MetalSmith is extremely pluggable, it simply means its various diverse functionalities can be implemented with the aid of plugins. Thanks to an active MetalSmith community, there is a host of plugins with various amazing features, and you can find them here.

In building a static site with MetalSmith, content is created in the source folder, and metalsmith manipulates this content using specified plugins. The manipulated content is contained in the output or build folder. This folder is served on the browser.

Installation

First, you must have node installed, as well as its corresponding package manager npm. Create a project folder with:

mkdir metalsmith-blog && cd metalsmith-blog

Now we install metalsmith via the node package manager (npm) with:

npm init
npm install metalsmith

Running npm init initializes a new project and creates a package.json file.

Install Plugins

For this simple blog, we would be making use of a couple of essential plugins:

• metalsmith-markdown: This converts markdown files in our source to HTML
• metalsmith-templates: We would be making use of Jade — a template engine. This would be used to write our source HTML files.
• metalsmith-assets: This plugin helps us use static assets like client-side JavaScript files, as well as CSS files.
• metalsmith-collections: This helps us create grouped content lists like article lists on our page.
• metalsmith-permalinks: This customizes permalinks of files.

These plugins are installed via npm with:

npm install --save metalsmith-collections metalsmith-assets metalsmith-templates metalsmith-markdown metalsmith-permalinks

The — save flag ensures these plugins are created as dependencies in our package.json file.

Lastly, we would have to install Jade. Jade is a server-side templating engine Node.js. Jade is installed also via npm with:

npm install --save jade

Voila, now we have installed all requirements. The package.json file should look like this:

Note: The "scripts``" property is included so we can configure server commands for our site. When we run the build command, the build files are generated on the server. Running the serve command serves a locally hosted version of our website. The build.js file is yet to be created.

Also, to use serve, it must be installed on your machine If not, install it globally with:

npm install serve -g

Creating the Build files

In our root directory, three folders are created, named build, src and templates. The build folder holds the files manipulated by metalsmith to be served. The src folder contains the source files, which include HTML, CSS, and JavaScript. The template folder contains all jade templates used.

Build.js

Here the metalsmith engine is built and configured. In the root directory of the project, the build.js file is created, then it is configured in the following way. First all plugins are loaded with:

Next, these loaded plugins are chained to the metalsmith function with the use() method. Required parameters are also passed in the methods.

Note: The order in which these plugins are chained is very important, as the source files will be manipulated by these plugins in that exact order.

The build.js file is edited to:

Note the source, template, assets, and destination directory as specified. After the plugins are chained, an error function is also declared in case of an error. This is located at the bottom of the script as seen above. We now have our metalsmith engine in place.Now let’s get to creating our templates for the homepage and our articles page.

HTML Templates

The templates folder in the root directory is to hold all article layouts that will be converted to HTML during build. In the templates folder, two Jade templates were created: index.jade and article.jade. index.jade is the template for the home screen on the blog and is edited to this:

Note: Bootstrap is used for styling and is imported from a CDN to the head tag of the file as seen above.

article.jade is the template used for the individual articles in the blog and it is edited to:

Bootstrap classes were also used to style in this template. Notice how we imported Vue from a CDN at the bottom of the Script? Vue’s Data Binding feature will be used on the client-side to handle comments. Also, a JavaScript library moment.js will be used to format date and time on the articles. We also imported a JavaScript file and a CSS file. These have not been created, and we will get to that next.

Creating Assets

Assets required in this blog are a CSS file to handle styling and a JavaScript file to handle the comments. Vue was chosen to write the comment section with, as it is easier than using basic Vanilla JavaScript. In the src folder, two folders are created: the Articles folder and the Assets folder. In the assets folder, two folders are created: CSS and JS. These folders contain the CSS and JavaScript files imported in our Jade templates. The CSS file is created, named style.css and edited to:

Feel free to style it anyhow you like.

A JavaScript file app.js is created in the JS folder and configured as this:

This is mainly a Vue instance including its component and associating methods. In the script above, a Vue instance is created and mounted on the DOM element with an id of app (same as the div with class container-fluid). A component comment is created and passed a form template. The form input is displayed on the screen when the submit button is clicked then the form fields are cleared for the next input. These created assets are exported to the build folder when we run build

Index.html

In the source folder src, the source index.html file is created and edited to this:

In the index.html file, there is no HTML content; rather, we have front matter - this simply displays information usable from the page. In this case, the front matter states we use the index.jade template to render the HTML file. We are all about set with our blog. Now let’s get to the best part - creating content for the blog.

Creating Content

Content is created in the form of markdown files that will be translated to HTML files (remember the metalsmith-markdown plugin). In /src/articles, two markdown files are created, which will be our sample articles.

Article01.md

Article02.md

The front matter in the markdown files will be used to fill in dynamic content on the HTML files. Take a look at the article.jade file to see the value of title, author and date passed in.

We have fully created our blog! Run:

npm run build

This creates the build files. You can look through the build folder to see files created. To view our blog in the browser, serve the project with:

npm serve

Conclusion

In this article, we have built a static blog using MetalSmith. Using just the basic plugins, we implemented features required of a static blog that includes an articles list. Also, Vue.js was used to create a commenting system on the blog. Feel free to try out other template engines instead of Jade, as well as modify the styles on the blog.

About Manifold

Manifold is the first independent marketplace for developer services and the easiest way to manage and share everything from JawsDB, a simple postgres database to Mailgun, an API that makes sending and receiving email dead simple.

For more info visit Manifold.co or follow us on twitter. This post is part of the Manifold Content program. Want to write for us?