gosw is a minimalist static website generator in less than 300 lines of Go.
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!
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
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:
jroimartin/sites would contain a directory for every site and each
of these directories includes 4 things:
- A directory named
site. The input directory with the markdown files.
- A file named
config.jsonwith the configuration parameters of that site.
- A file called
style.jsonwith the layout and the design of that site.
- A git submodule named
public. The output directory that points to the github pages repo, in the case of this site
So, what’s my workflow?
$ cd src/sites/jroimartin.github.io $ $EDITOR 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.