A Gentle Introduction to Static Site Generators

This document will be a simple introduction to static site generators. We'll go over the basics of what they are, why you should use them, which one you should use and finally how to get started.

The intended audiences for this tutorial are designers or novice developers with little to no programming experience but with some HTML/CSS skill, simple command line experience. This document was originally written for a presentation I did for a portfolio class at the UC Berkeley School of Information. You can see the presentation I made here

I'm using one on this website called Pelican but there are many different kinds. Feel free to send me an email with any questions and I can recommend the best one for you. When I wrote this tutorial I saw how much more enjoyable it was to use jekyll, so I made the switch myself.

What is a static site generator?

Simply a static site generator generates a static site. You give it a simple format of documents of a certain type and it converts those into HTML content for you. This makes it easy to maintain any changes you make to the underlying pages.

What problem does it solve?

You want a website or portfolio. You want to continue to add to it overtime and be able to make changes to my template and have those go to every single page of my website.

If you just have raw html pages, changing details on every page is a nightmare. If you want to change something like the layout, I'd have to copy and paste my content into every single one. You could use a web framework like Ruby on Rails or Django but then you have to deal with hosting and all the associated overhead and knowledge those things require. Additionally those require full fledged web servers (if you don't know what this is don't worry about it). You can serve static sites for free.

Static site generators abstract the compilation of templates and source writing of documents. Instead of having that done on the server, it does it on your local machine and allows you to take that static site and put it elsewhere.

In simplest terms it takes a template of structure and layout and inserts the content you write in other formats into that template.

I think the working example is easiest to understand.

So you've got a directory like this: (this is just writing)

- Articles (the folder)
    - my_article_about_stuff.md
    - My_other_article_about stuff.md
    - ux_review.md

The static site generator generates a folder structure like this: (that you can put on a web server)

- about.html
- home.html
- articles
    - my_article_about_stuff.html
    - My_other_article_about stuff.html
    - ux_review.html

That would give you a website like this: (that goes on the internet)

mywebsite.com/about.html
mywebsite.com/home.html
mywebsite.com/articles/my_article_about_stuff.html
...

how does one get started?

THIS TUTORIAL IS INTENDED FOR MAC USERS

Let's get started with Jekyll. It's the most popular static site generator and is fairly friendly.

You'll need two things for these next steps:

Your Favorite Text Editor (sublime text, text edit, etc.)
A Terminal (search spotlight for terminal and open it up).

From now on, anything you see in code writing should be executed in the terminal unless otherwise stated.

On Mac run: gem install jekyll

if you have any problems you may need to run. sh rvm get stable rvm osx-ssl-certs update all rvm rubygems latest You may have to do this stuff with sudo in front of it.

These commands just make sure everything you have is up to date.

Then finally run gem install jekyll --source http://rubygems.org in the terminal.

Now you've installed jekyll. What I always like to do is start with the basics and modifying it to meet my needs. Let's create a basic blog then go from there.

jekyll new myblog
cd myblog
jekyll serve

You'll see some text like. It's not important what it says, just that it says something like this.

Configuration file: /sometext/myblog/_config.yml
            Source: /sometext/myblog
       Destination: /sometext/myblog/_site
      Generating... done.
[2014-11-10 14:10:42] INFO  WEBrick 1.3.1
[2014-11-10 14:10:42] INFO  ruby 2.0.0 (2013-06-27) [x86_64-darwin12.3.0]
[2014-11-10 14:10:42] INFO  WEBrick::HTTPServer#start: pid=62126 port=4000

Now go to http://localhost:4000/ and BOOM you've got a website.

So let's dive into customizing the website a bit more.

Take a look at the directory structure but it should be pretty self explanatory.

_layouts/ is where you've got the layouts. Typically you'll have a more navigation centric one then a more post centric one.

_posts/ is where you store...you guessed it. Any posts you want to publish.

_site/ is the actual website that jekyll generates. You'll see that it organizes things by date. You will NEVER edit anything in here because it won't get saved permanently and you'll forget to do it next time.

css/ is where you store the css for your project. Most of what you'll be modifying will be main.css in the css/ folder.

index.html is the home page for your website.

Here's the code for index.html:

---
layout: default
title: Your New Jekyll Site
---

<div id="home">
  <h1>Blog Posts</h1>
  <ul class="posts">
    {% for post in site.posts %}
      <li><span>{{ post.date | date_to_string }}</span> &raquo; 
      <a href="{{ post.url }}">{{ post.title }}</a></li>
    {% endfor %}
  </ul>
</div>

Now remember, we making your website so we need to customize it for you!

In your terminal hit control + c where you entered jekyll serve.

This will turn off the server you started above.

Now run jekyll serve --watch. What this allows us to do is make changes to our files and jekyll will see those changes and automatically compile our new website on http://localhost:4000/.

Changing HTML

Open up index.html in your text editor and let's make some changes.

First, this isn't a blog, it's a portfolio. So I want to make two changes. I want to change the title and the text in the <h1> tag. Here's what I changed in my index.html file.

---
layout: default
title: Bill's Fantastic Portfolio
---

<div id="home">
  <h1>Portfolio</h1>
  <ul class="posts">
    {% for post in site.posts %}
      <li><span>{{ post.date | date_to_string }}</span> &raquo; 
      <a href="{{ post.url }}">{{ post.title }}</a></li>
    {% endfor %}
  </ul>
</div>

Now navigate to http://localhost:4000/ in your browser and refresh the page. You'll see the title is different now.

Changing CSS

Now let's say I want every <h1> tag to be blue. That means changing some css, so I'll head over to main.css.

and add one line at the end of the file

h1 {
  color:blue;
}

Now go back to http://localhost:4000/ and you'll see that Portfolio on the page is now blue!

At this point you've now learned basically everything you need to know to run your own static site. We learned how to:

Change the home page by editing index.html
Change the styles in main.css
Add or edit your "posts" in _posts by creating markdown files.
To put this up on Github pages check out this tutorial.

Typically any questions you have will just be a Google away or Check out the jekyll site for great documentation.

As a side note, when you're ready to finalize the version of the site that you want to run jekyll build. This will put the final version in your _site which you can send up to your static host (like Github Pages).