gosw

TL;DR

gosw is a minimalist static website generator in less than 300 lines of Go.

Context

Around 2012 I wrote a small tool in shell script called sw. It is a static website generator written in around 100 lines of code (excluding the script used to convert markdown to html).

I wrote it because I wanted something simple focused on a very specific task: generating a website from a number of markdown files structured on a file tree. On the other hand, it was a must that the generated site could be used locally. This way, it could be used also for documentation tasks. And, of course, I want to manage my site using git or any other version control system.

Now, it’s 2018 and I didn’t want to keep using a shell script for this task, so I decided to rewrite it in Go. That’s the origin of gosw, a full rewrite of sw that follows the same philosophy that its predecessor. If you are wondering how big it is, the answer is less that 300 lines of code.

Now let’s get started!

Website generation

As you might have noticed this site is built using gosw. You can find its “source code” in my sites repo.

If you look at that repo you will notice that the structure of the site looks like this (only the relevant files have been included):

$ tree jroimartin.github.io/
jroimartin.github.io/
├── config.json
├── site
│   ├── images
│   │   └── nibble.png
│   ├── index.md
│   ├── projects
│   │   ├── gosw.md
│   │   └── index.md
│   └── whoami.md
└── style.css

Basically, the file tree defines the structure of the site. So, directories will end up being sections of the website and their index files will be the front page of each of these sections. On the other hand, the rest of markdown files will be also shown in the navigation bar as individual pages. The other files are just copied to the same location in the output directory.

Finally, the configuration parameters and the style of the site are defined in the config.json and style.css files.

Then the site is generated running the following command:

$ gosw site/ public/

With the result:

$ tree public/
public/
├── images
│   └── nibble.png
├── index.html
├── projects
│   ├── gosw.html
│   └── index.html
└── whoami.html

Ready to serve in a remote server or consume locally.

Publishing the website using github pages

In my case, I use github pages to publish this website.

The setup is based on two repos:

The repo jroimartin/sites would contain a directory for every site and each of these directories includes 4 things:

So, what’s my workflow?

$ cd src/sites/jroimartin.github.io
$ vim site/projects/gosw.md
$ gosw site/ public/
$ cd public
$ git add . && git commit -m 'Update' && git push
$ cd ..
$ git add site public && git commit -m 'jroimartin.github.io: add projects/gosw' && git push

Obviously, it’s up to you to automate it using a Makefile or a shell script.