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:
How do I get it?
- Install roots globally by doing
npm i rootsNote: you might need to sudo this command
- Check out how simple this website is on my GitHub. Fork this repo
git clone https://github.com/andyshora/andyshora-roots.gitand install the dev dependencies with
- Preview the site locally with
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:
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.
--- 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.
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...
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.
roots watchcomes with fast livereload functionality. If you make a content/style/script change, chances are it's been reloaded in the browser before you can even switch app!
- For adding simple build tasks to perform before/after the compilation, you can define before and after functions in the app.coffee file. Read the config docs and ensure your functions return a promise.
- Roots is easy to extend. The number of available plugins is growing fast, and now is a great time to get involved.
- The author of Roots, @jescalan is active in a chatroom dedicated to the Roots project. Any queries, pop him a message in here.
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!