Permalink
Find file
Fetching contributors…
Cannot retrieve contributors at this time
134 lines (108 sloc) 9.87 KB
---
title: 'Building a Static Website with Roots'
description: 'How I built this website with Roots, the enlightening static site compiler'
author: andyshora
date: 03/05/2015
image: http://i.imgur.com/bXONeC0.png
url: 'http://www.andyshora.com/building-static-site-with-roots'
type: article
_content: false
---
extends layouts/_base
block header
+large-title-block('Building a', ' static website ', 'with Roots', 'How I built this website with Roots, the enlightening static site compiler.', true, true)
block content
section.section-gutter
:markdown
##What is Roots?
**[Roots](http://roots.cx/ "Roots Static Site Compiler") 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:
+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')
section.section-gutter.section-gutter--alt
:markdown
##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](https://github.com/andyshora/andyshora-roots "andyshora.com Roots Repo"). 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`
section.section-gutter.section-gutter--alt
:markdown
##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
section.section-gutter
:markdown
##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](http://jade-lang.com/reference/mixins/) as modules and components which can be called from a jade file like this:
+code-block('How I produced the quote block module on this page:')
code(class='language-javascript')
|+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')
section.section-gutter
:markdown
You can check out [how I've implemented this quote block module right here](https://github.com/andyshora/andyshora-roots/blob/master/views/modules/quote-block/_quote-block.jade), 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](https://github.com/andyshora/andyshora-roots/blob/master/views/hello.jade).
*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](http://roots.cx/articles/getting-started) docs.*
+gallery()
ul
li()
.gallery__caption
strong Here's what the .jade file for this page looks like
:markdown
View the whole file [building-static-site-with-roots.jade](https://github.com/andyshora/andyshora-roots/blob/master/views/building-static-site-with-roots.jade)
img(class='gallery__image' src='http://i.imgur.com/AUy9ah4.png')
section.section-gutter
:markdown
##Defining Page Variables with Front matter
I'm using the [Roots Dynamic Content](https://github.com/carrot/roots-dynamic-content/blob/master/docs/intro.md) 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.
+code-block('A snippet of the front matter for this page:')
code(class='language-jade')
|---
|title: 'Building a Static Website with Roots'
|description: 'How I built this website with Roots, the enlightening static site compiler'
|author: andyshora
|---
section.section-gutter
:markdown
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](https://github.com/andyshora/andyshora-roots/blob/master/views/building-static-site-with-roots.jade) 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](https://github.com/carrot/roots-dynamic-content/blob/master/docs/intro.md).*
section.section-gutter
:markdown
##Deployment
I deploy my Roots site to [GitHub Pages](https://pages.github.com/), 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](https://help.github.com/articles/setting-up-a-custom-domain-with-github-pages/). 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](https://github.com/andyshora/andyshora-roots/tree/master/views) directory.
+gallery()
ul
li()
.gallery__caption
strong Here's the DNS I use for this site:
:markdown
I also have a [file called CNAME](https://github.com/andyshora/andyshora-roots/blob/master/public/CNAME) containing my domain name.
img(class='gallery__image' src='http://i.imgur.com/3bh1aSh.png')
section.section-gutter.section-gutter--alt
:markdown
##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.
section.section-gutter
:markdown
##Other Advantages
- `roots watch` comes 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](http://roots.cx/docs/configuration) and ensure your functions return a promise.
- Roots is easy to extend. The [number of available plugins](http://roots.cx/extensions) is growing fast, and now is a great time to get involved.
- The author of Roots, [@jescalan](https://twitter.com/jescalan) is active in a chatroom dedicated to the Roots project. Any queries, [pop him a message in here](https://gitter.im/jenius/roots).
section.section-gutter
:markdown
##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](https://twitter.com/andyshora) or leave a comment below!
+bio-block('Andy Shora', 'andyshora', 'https://pbs.twimg.com/profile_images/572092098691907585/skCkcVFS_400x400.jpeg')
:markdown
I'm a Front-end Web Developer based in London. I currently work with some very talented people over at [QuantumBlack](http://www.quantumblack.com). 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!](https://twitter.com/andyshora)
section.section-gutter.section-gutter--full
+comments()