What is MetalSmith?
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:
mkdir metalsmith-blog && cd metalsmith-blog
Now we install metalsmith via the node package manager (npm) with:
npm install metalsmith
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-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
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.
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:
Feel free to style it anyhow you like.
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:
In the `index.html` file, there is no HTML content; rather, we have frontmatter - 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.
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:
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.
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.