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.
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.
First, you must have node installed, as well as its corresponding package manager npm. Create a project folder with:
https://gist.github.com/53eb69e95e3e1cafbb9a3de268b20d38
Now we install metalsmith via the node package manager (npm) with:
https://gist.github.com/368f3eaf92201a5e87fa16057c91aa53
Running npm init initializes a new project and creates a package.json file.
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:
https://gist.github.com/03a8b811665889c8156a35ad77dc54ad
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:
https://gist.github.com/7869daee02f3d816ae2eb011ec9655ac
Voila, now we have installed all requirements. The package.json file should look like this:
https://gist.github.com/70c93b06c32eca6cfb1a3d420d834b92
Note: The
"scripts``"property is included so we can configure server commands for our site. When we run thebuildcommand, the build files are generated on the server. Running theservecommand serves a locally hosted version of our website. Thebuild.jsfile is yet to be created.
Also, to use serve, it must be installed on your machine If not, install it globally with:
https://gist.github.com/f3e3b45183ff1bb780fead72e532fc27
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.
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:
https://gist.github.com/c8ad0da298767e655becded9e6667a02
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:
https://gist.github.com/73052b3929758dcb59a890aad84ceb03
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.
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:
https://gist.github.com/4fb577b9936e0f4851f0225a651f7e31
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:
https://gist.github.com/321fe287d39b8841119c1e3d4a399eaf
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.
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:
https://gist.github.com/2bacc61189ed0b92d130f574d9862e65
Feel free to style it anyhow you like.
A JavaScript file app.js is created in the JS folder and configured as this:
https://gist.github.com/a29a4a1ec0208a3cf4a7e4565d08b3a6
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
In the source folder src, the source index.html file is created and edited to this:
https://gist.github.com/a20e4ee9c70efcc981f0da4b9796a2e2
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.
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 https://gist.github.com/c5bc3c6dffb731f6e993da91bce2a6dd
Article02.md https://gist.github.com/36ed133c1170e314176536e30656b79e
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.jadefile to see the value oftitle,authoranddatepassed in.
We have fully created our blog! Run:
https://gist.github.com/70ce0c05770a3256be7f5979c97dec9f
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:
https://gist.github.com/1cf0b669758273f1ba2796f1d602a3c3
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.