How to Create a Static Site with Metalsmith
My previous posts discussed reasons why you should or should not consider a static site generator. In summary, a static site generator builds HTML-only page files from templates and raw data typically contained in Markdown files. It offers some of the benefits of a CMS without the hosting, performance and security overheads.
A static site may be appropriate for a range of projects, including:
- A small website or personal blog. Sites with a few dozen pages, infrequent posts and one or two authors could be ideal.
- Technical documentation such as a REST API.
- Application prototypes requiring a series of web page views.
- An eBook — Markdown files can be converted to PDF or other formats as well as HTML.
I choose Metalsmith for this tutorial because it:
- is not aimed at specific project types such as blogs
- supports a wide range of template and data format options
- is lightweight
- has few dependencies
- uses a modular structure
- offers a simple plug-in architecture, and
- is easy to get started.
A demonstration website has been built for this tutorial. It won’t win any design awards but it illustrates the basic concepts. The Metalsmith build code can be examined and installed from the GitHub repository. Alternatively, you can follow the instructions here and create your own basic site.
I have used Metalsmith a couple of times—please don’t presume this is the definitive way to build every static site!
cd project && cd project npm init -y
Now install Metalsmith and the assorted plugins we’ll use to build our site. These are:
- metalsmith-assets — includes static assets in your Metalsmith build
- metalsmith-browser-sync — incorporates BrowserSync into your workflow
- metalsmith-collections — adds collections of files to the global metadata
- metalsmith-feed — generates an RSS feed for a collection
- metalsmith-html-minifier — minifies HTML files using kangax/html-minifier
- metalsmith-in-place — renders templating syntax in source files
- metalsmith-layouts — applies layouts to your source files
- metalsmith-mapsite — generates a sitemap.xml file
- metalsmith-markdown — converts markdown files
- metalsmith-permalinks — applies a custom permalink pattern to files
- metalsmith-publish — adds support for draft, private, and future-dated posts
- metalsmith-word-count — computes word count / average reading time of all paragraphs in a HTML file
npm install --save-dev metalsmith metalsmith-assets metalsmith-browser-sync metalsmith-collections metalsmith-feed metalsmith-html-minifier metalsmith-in-place metalsmith-layouts metalsmith-mapsite metalsmith-markdown metalsmith-permalinks metalsmith-publish metalsmith-word-count handlebars
We’ll use the following structure for source (
src) and build (
build) directories within the project.
You can create your example files as described below or copy them directly from the demonstration src directory.
Page Markdown files are contained in
src/html. This can contain one level of sub-directories for each website section, i.e.
src/html/start— pages describing the project in a specific order
src/html/article— assorted articles in reverse chronological order
src/html/contact— a single contact page
Each directory contains a single
index.md file which is the default page for that section. Other pages can use any unique name.
The build process will transform these files into directory-based permalinks, e.g.
Each Markdown file provides the content and meta information known as “front-matter” at the top between
--- markers, e.g.
--- title: My page title description: A description of this page. layout: page.html priority: 0.9 date: 2016-04-19 publish: draft --- This is a demonstration page. ## Example title Body text.
Continue reading %How to Create a Static Site with Metalsmith%