Building a static website with Roots

How I built this website with Roots, the enlightening static site compiler.

← andyshora.comworth a tweet?+1

What is Roots?

Roots is the hottest SSG (Static Site Generator) being poked by frontend developers right now.

In short, if you haven't used an SSG before, they provide an easy way to compile a whole static website from content files and templates (e.g. Markdown, JS/Coffeescript, SASS, Jade templates), into highly optimized production ready static files (HTML, JS, CSS).

In their own words:

Roots is a static site compiler, that generates static html, css, and javascript files. It's very good at helping to build static front-ends.

Carrot Creative

How do I get it?

  1. Install roots globally by doing npm i roots Note: you might need to sudo this command
  2. Check out how simple this website is on my GitHub. Fork this repo git clone https://github.com/andyshora/andyshora-roots.git and install the dev dependencies with npm i
  3. Preview the site locally with roots watch

My Stack

Right now I'm using: - CoffeeScript for some minor visual enhancements - SASS for all styles - Jade templates containing a mixture of markdown and Jade syntax

Defining New Pages

The way I'm defining templates has caused a bit of a stir. Whilst some other SSG's favour using a plain markdown approach to define posts, I'm in favour of adding a bit more richness to the frontend. The way I've done this, is by defining Jade mixins as modules and components which can be called from a jade file like this:

How I produced the quote block module on this page:
+quote-block('Roots is a static site compiler, that generates static html, css, and javascript files. It\'s very good at helping to build static front-ends.','Carrot Creative')

You can check out how I've implemented this quote block module right here, I believe it's a great way to bake out rich modules with minimal definition in the content files. Whatever your approach, you should still define your posts/articles as Jade files containing front matter at the top, and either have one massive block of markdown, or a mixture like I have. Note: you can use other template systems such as ejs, just make sure you've installed the node module as described in the getting started docs.

Defining Page Variables with Front matter

I'm using the Roots Dynamic Content extension which allows me to add front matter to the top of each jade file. (That's all the metadata in between the --- at the top) The keys specified here will then become available in the template, as well as any base templates which have been extended, under post.key_name.

A snippet of the front matter for this page:
---
title: 'Building a Static Website with Roots'
description: 'How I built this website with Roots, the enlightening static site compiler'
author: andyshora
---

For example, this page extends my base layout file [layouts/base.jade](https://github.com/andyshora/andyshora-roots/blob/master/views/layouts/base.jade), which contains references to variables like the title, description and author.

Now, take a look at how the front matter defined in the jade template populates this base template during the compilation phase. Magic!

Note: if you want programmatic access to all of your posts in a template, for example to create a list of links to them on the homepage, then you'll need to group them into a seperate directory. They will then become available under a site.posts variable as described in the Roots Dynamic Content Docs.

Deployment

I deploy my Roots site to GitHub Pages, and you should too! It's fast, free and easy to do. Assuming your repo is hosted on GitHub: 1. Push the public directory using a subtree in Git, to the branch gh-pages: git subtree push --prefix public origin gh-pages. Your site should now be available at the domain visible in the settings of your repo. 2. To use a custom domain, follow the instructions here. In short, you need to add a file called CNAME which contains the full domain name you want to use for the site (e.g. andyshora.com). You'll also need to alter your DNS to point the domain to your GitHub account. I've shown mine below...

As the roots clean command can wipe the public directory, make sure you include any files which need to be copied to / in the views directory.

how is Roots better than Jekyll?

If you've already got a setup which works for you and delivers the same results, then you're probably looking at the a system pretty similar to what Roots brings. Previously, I had a rather simple SSG I made myself with shell scripts which would extract front matter from posts, pull in static includes and create html pages for me to deploy.

The advantage of Roots, is that it has static site compilation in mind from the beginning. It's been built specifically to build static websites. Other systems can be very over-reaching, and converting them into something which can generate a simple static website can take a bit of time.

Personally, I found Jekyll very difficult to get setup, and pretty heavy and slow once it was up and running. The fact that it was Ruby-based game me some install problems, and I found it difficult to extend due to the lack of my Ruby knowledge.

Roots came along and provided me with a nice lightweight alternative. It feels like it has no bloat compared with other big SSGs. Yeah it does pretty much the same thing, but it feels more suited to the job. It feels like the right tool.

Other Advantages

Summary

Roots is in the early stages of adoption, but the lean approach is provides and the great level of support make it a solid choice for building your next static website. This website is still evolving, so there's no doubt I'll be improving things over the next few months. Any questions? Send me a tweet or leave a comment below!

by Andy Shora

I'm a Front-end Web Developer based in London. I currently work with some very talented people over at QuantumBlack. I love to build sites which are clean and have great performance, and I dabble with whatever technologies are most suitable for the job. Send me tweets!