Static HTML sites with Markdown and Metalsmith

by ProDeveloper   |   last updated December 8, 2024   |   Blog · HTML5 ·

HTML

The language in which all websites and web apps are being presented on the web browsers is HTML.

This markup language is what web browsers read, understand, and render. In addition to HTML, web applications in most cases have dedicated JavaScript code and style files.

Many websites are dynamic with HTML and corresponding assets generated dynamically, by the web server backend application.

Recently, static websites started to gain popularity.

A static website means that all HTML and Javascript required by web browsers are statically generated on the server side and will not change.

This brings many benefits for website performance – most of the content can be cached and can be loaded by the browser very fast.

Such pages do not change, you don’t need the backed server at all. Hence the name – static websites.

Because of this nature, static websites can be served from multiple platforms which allows content sharing. Examples would be GitHub pages or even DropBox.

Generating static HTML websites

What are the most common ways of generating static HTML websites?

You can, of course, create and maintain your static website pages in HTML language as a set of files.

However, being a markup language, HTML is hard to read for humans.

Markdown language comes to the rescue. Markdown is easy to read for humans and a large array of tools exists to convert markdown to HTML markup.

Static site generators work this way – they use such converters, plus provide some extra bits for generating structure for static websites.

In this tutorial, we are going to use one of such static site generators – Metalsmith. You will learn how to set up and configure a simple static website.

MobileGap – the list of open-source mobile applications

MobileGap is a simple website we have created to maintain the list of open-source mobile application projects.

The first version of  mobilegap.net site was quickly put together by using an existing WordPress template we had lying around.

But, as the number of developers asking to add their open-source applications to the list grew, we decided to open-source the content creation of this website.

The good option for such a setup was to maintain website content in a Markdown language, generate HTML markup from it, and move generated HTML files to be served by the web server. Markdown pages should be hosted on a publically accessible repository like GitHub.

Now, everyone wishing to add their application to the list only has to issue a GitHub pull request to MobileGap GitHub project to update the pages.

How did we set it up?

Maintain static HTML websites with Markdown and Metalsmith

We are using metalsmith.io simple static site generator to convert Markdown pages to HTML markup.

Now let’s reference the current project structure of mobilegap.net source code

Metalsmith is a NodeJS module and requires NodeJS to be installed on the system. Let’s go through the files in the project.

package.json is a packaging file for Node applications. It has a list of dependencies which the application relies on in the dependencies section. The contents of the file are the following:

{
 "name": "www.mobilegap.net",
 "version": "0.1.0",
 "description": "MobileGap - open source mobile application directory",
 "main": "index.js",
 "repository": { 
 "type" : "git",
 "url" : "https://github.com/sauliuz/mobilegap.net.git"
},
 "dependencies": {
 "handlebars": "^4.0.5",
 "metalsmith": "^2.1.0",
 "metalsmith-markdown": "^0.2.1",
 "metalsmith-templates": "^0.7.0"
},
 "author": "popularowl.com",
 "license": "MIT"
}

The dependencies section lists a few npm packages our project relies on. Metalsmith core is simplistic and minimal, and to use Markdown or templating functionality, we have to list these specific Metalsmith modules. There is also a handlebars module, which helps to set up templates.

Other sections of the file provide information about the project. If you want to understand the structure of a packaging file for NodeJS projects, check the official documentation.

Run npm install on your system and the npm package manager (it comes together with NodeJS installation) will download all the project dependencies.

Now let’s look at index.js

var Metalsmith = require('metalsmith'),
 markdown = require('metalsmith-markdown'),
 templates = require('metalsmith-templates'),
 Handlebars = require('handlebars'),
 fs = require('fs');

 Handlebars.registerPartial('header', fs.readFileSync(__dirname + '/templates/partials/header.hbt').toString());
 Handlebars.registerPartial('footer', fs.readFileSync(__dirname + '/templates/partials/footer.hbt').toString());

Metalsmith(__dirname)
 .use(markdown())
 .use(templates('handlebars'))
 .source('./markdown')
 .destination('./mobilegap.net')
 .build(function (err) { if(err) console.log(err) })

If you are familiar with NodeJS applications, this file doesn’t look very complex.

First, we retrieve all the required modules. Then we are registering partials for Handlebars templates. This allows us to keep a shared header and footer for all pages.

Next, we set Metalsmith static site generator, with Metalsmith(..) providing it with the location to a current directory.

We use Handlebars templates, the markdown directory as a source, and the mobilegap.net directory as a destination for generated HTML files.

The last step is build(). We are catching and logging any errors that might happen during the build process.

As you might have already guessed, Markdown files are located in markdown a directory, template files are located in templates. We like simplicity.

Now, if you run node index.js all the markdown files from the markdown directory will be converted to HTML using the template and partials from the templates directory.

The resulting HTML files are created in the mobilegap.net directory. Metalsmith will delete the old HTML files before creating new ones by default.

Metalsmith will also copy all other files (styles, JavaScript) from a source directory to a destination directory as they are.

What’s left is to move generated HTML files to your web server. In the next part of this post, I’ll describe the process we use to employ a simple CI pipeline to automate the generation of static HTML websites after new code changes are merged into the GitHub repository.