---
title: Notes on Metalsmith and Jekyll
date: 2017-12-03T09:25:00+00:00
modified: 2017-12-03T09:30:21+00:00
image:: https://kaspars.net/wp-content/uploads/2017/12/jekyll-website-readme.png
permalink: https://kaspars.net/blog/jekyll-vs-metalsmith
post_type: post
author:
  name: Kaspars
  avatar: https://reverse.kaspars.net/gravatar/avatar/92bfcd3a8c3a21a033a6484d32c25a40b113ec6891f674336081513d5c98ef76?s=96&d=mm&r=g
category:
  - Development
post_tag:
  - Tool
---

# Notes on Metalsmith and Jekyll

I love the concept of building project documentation websites out of simple [Markdown](https://en.wikipedia.org/wiki/Markdown) and [Mustache](https://mustache.github.io/) files. Recently I used [Metalsmith](https://github.com/segmentio/metalsmith) (with Node.js) for creating the [un-official Latvian eID documentation site](https://github.com/kasparsd/eparaksts-info) and more recently [Jekyll](https://jekyllrb.com/) for the [WP Shuttle](https://wpsh.org) project. In this post I want to note and compare these tools.

[![Instructions for building a documentation website with Jekyll](https://kaspars.net/wp-content/uploads/2017/12/jekyll-website-readme.png?strip=all&quality=90&resize=800,574)](https://github.com/wpsh/wpsh.org)

## Metalsmith

- Metalsmith uses Javascript and is very easy to setup and configure via `package.json` and a single build file.
- Automatic deployments to [GitHub Pages](https://pages.github.com/) require a [Travis CI build process](https://github.com/kasparsd/eparaksts-info/blob/40215d54ecf319dbcc3e2bfefd8c9a5f9a9d053c/.travis.yml).
- Adding a local preview server with live reloading requires [extra configuration](https://github.com/segmentio/metalsmith/issues/44).

## Jekyll

- Jekyll uses Ruby which I had only used for hacking [Vagrantfiles](https://www.vagrantup.com/docs/vagrantfile/) so it takes some time to learn about [gems](https://rubygems.org/) and the way things are done in the Ruby world.
- Automatic deployments to GitHub pages are automatic and don’t require a Travis CI build process as long as the source files and [`_config.yml`](https://jekyllrb.com/docs/configuration/) are [in the root *or* the `docs` directory](https://help.github.com/articles/configuring-a-publishing-source-for-github-pages/) of the repository. Note that [GitHub doesn’t support overriding the `source` directory](https://help.github.com/articles/configuring-jekyll/).
- Only Markdown files with the [front-matter](https://jekyllrb.com/docs/frontmatter/) are processed by Jekyll. Source files without the front-matter [are not included in the build](https://help.github.com/articles/configuring-jekyll/#front-matter-is-required). I couldn’t find a simple way to disable this requirement.

## Continuous Deployment

Unfortunately GitHub pages [don’t support HTTPS for sites with custom domains](https://help.github.com/articles/securing-your-github-pages-site-with-https/) so I discovered [Netlify](https://www.netlify.com/) which provides [free continuous deployment and hosting](https://www.netlify.com/docs/continuous-deployment/) with custom domains and TLS from Let’s Encrypt. Their dashboard is also very nice!

Overall, both Metalsmith and Jekyll are awesome tools, and paired with continuous deployment can reduce the effort required for maintaining a project website.