Personal Website and Static Site Generators

I want to build my personal site

It is time to build a personal site. I want to be able to put down some thoughts. So how should I build the site? What technology should I use?

This is a good question. But for now, I should decide how the site is going to be used. What content it will contain.

The main purpose is to present my projects and to host a few blog posts.

What tool to use?

In other words: wordpress to be or not to be? The first thought was to use the wordpress. Everybody uses wordpress. Should I host the wordpress on my own server or rent a space on https://wordpress.com/ ? I don't want my site to have ads. Let's see their plans. The first plan without ads starts from 99EUR per year.

I already rent a server. I don't see the reason to pay additionally 99EUR per year. The wordpress community version can be deployed on my server. But I will have to maintain the wordpress and the mysql. This means I have to install latest bug fixes make thoughts about backup, etc. etc.

Currently, I don't need any dynamic stuff on the site. The site is going to be completely static. This means there is no actually reason to have wordpress.

If not wordpress, so what? Luckily, there are so called static site generators. A "static site generator" is an engine that generates http files from markdown files. It can be markdown but doesn't have to. Markdown is just a simple and widely used markup language.

You don't need PHP or a database if you use a static site generator. You need only a web server such as nginx or apache that will serve the generated http files and images.

The advantage of a static site generator is that your entire site is just a folder with files. You can track them with a version control tool of your choice. Mine is currently git. But this is a topic of another post.

There is plenty of site generators. StaticGen contains a static site generator list sorted by popularity on GitHub.

Which one should I use? I have no idea. Basically, they all generate some static files.

The most popular is jekyll. Jekyll is very mature and has good documentation. It is written in Ruby. This is an issue for me. First, it can become hell installing required plugins because they reside somewhere else and not in the current directory. Second, it can become slow if you have several hundreds of pages. It is not a problem now but worth to mention.

I looked at several others like Octopress, Hexo. But they are all similar in that respect.

Final choice: Hugo

Then I looked at Hugo. The static site generator is written in Go language. This fact caught my attention. It makes it more faster than the other generators. The project has a very extensive documentation. This is a huge plus. Hugo does not target only blog sites. You can create a simple blog or a corporate site with it. It doesn't matter if your site has several pages or several hundreds.

Download hugo here or with Homebrew on a Mac:

brew install hugo

Huge uses Go template library for its template engine. It is a lightweight engine that provides only a very small amount of logic. I see it as an advantage and decided to stick with it.

Configuration

All files needed for the site generation are in a single directory my-site. The content files reside in the content directory. I have just two types of content: post and project. The directory project contains files describing my projects. For each project one. All posts will be organized by years because I don't write much.

content/
├── about.md
├── post
   └── 2015
       └── static-site-generators.md
└── project
    ├── my-clippings-manager.md
    └── zling.md

I don't wont to use any themes. I make the entire layout myself. But I will look at some themes for ideas. Here is my layouts directory structure:

layouts/
├── _default
   └── single.html
├── index.html
├── partials
   ├── footer.html
   └── header.html
├── post
   └── single.html
├── project
   └── single.html
└── section
    ├── post.html
    └── project.html

CSS

The next wish I have is to avoid using CSS directly. I would prefer something like less or sass. The trend is towards sass now. So I chose sass.

The original sass compiler is written in ruby. So it was not a choice for me. I considered two sass compiler: sassc and gulp-less (node.js). Using node.js would mean one more tool need to build the site. So I took sassc and built a small bash script for common tasks.

#!/bin/bash

css(){
  echo "Building CSS"
  sassc -t compressed src/styles.scss static/styles.css
}

buildAll(){
  echo "Building the site in directory 'public'"
  rm -r public
  css
  hugo
}

watchCss(){
  f=src/styles.scss
  hh=$(md5 -q $f)
  while true; do
    h2=$(md5 -q $f)
    if [ $hh != $h2 ]; then
      css
      hh=$h2
    fi
    sleep 1
  done
}

cd $(dirname $0)

case $1 in
  dev)
    hugo -D -w server
    ;;
  build)
    buildAll
    ;;
  css)
    css
    ;;
  watchCss)
    watchCss
    ;;
  deploy)
    buildAll
    rsync -avz --delete public/ alexei@sam701.com:site-sam701/
    ;;
  *)
    echo "Usage: $0 [build|dev|css|watchCss|deploy]"
    ;;
esac