I love the concept of building project documentation websites out of simple Markdown and Mustache files. Recently I used Metalsmith (with Node.js) for creating the un-official Latvian eID documentation site and more recently Jekyll for the WP Shuttle project. In this post I want to note and compare these tools.
Metalsmith
- Metalsmith uses Javascript and is very easy to setup and configure via
package.jsonand a single build file. - Automatic deployments to GitHub Pages require a Travis CI build process.
- Adding a local preview server with live reloading requires extra configuration.
Jekyll
- Jekyll uses Ruby which I had only used for hacking Vagrantfiles so it takes some time to learn about gems 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.ymlare in the root or thedocsdirectory of the repository. Note that GitHub doesn’t support overriding thesourcedirectory. - Only Markdown files with the front-matter are processed by Jekyll. Source files without the front-matter are not included in the build. 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 so I discovered Netlify which provides free continuous deployment and hosting 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.