Introduction

This small post will show all about how this site, which is hosted via GitHub Pages, and is for all intents and purposes a blog, is done.

Hopefully this post can also be of help to users that want a similar setup.

Without further ado.

Ingredients

Just like baking a cake, this site also needs ingredients to be mixed together into the content you're seeing. Let's run down over some of them.

GitHub Pages

Certainly the most important ingredient, it is it that provides the hosting for this site, without the resources from GitHub it would be much more inconvenient for me to set it all up.

Zola

You expected jekyll to be your static site engine ? Too bad!

It was me, dio zola!

Zola is a static site engine like any other, hugo, jekyll, werc, sw, etc, etc. There wasn't much thought put into it besides:

  • It is available on Void Linux.
  • It seems easy to use.

Travis CI

Travis CI is a well know Continous Integration service provider, most importantly i picked it because Void Linux uses it extensively to check pull requests from contributors before merging.

So it felt like safe, familiar ground and just a natural choice. I never had any problems with it that were just for me, only the rare global slowdown, which is helpfully warned with their broadcasts feature.

ghp-import

This is the one i know least about, it just was suggested when i was trying to jam zola into GitHub Pages. It just worked, after the fair warning that it will nuke your gh-pages branch or any other branch you point it to completely useless.

It is the one i have the least interaction with, actually i don't have any direct interaction, it is used solely by Travis CI.

maxice8.github.io

This is the repo that host the blog source and the finished content you are reading right now.

It extensively has 2 branches:

  • devel -> where i write stuff to
  • master -> where the final content is pushed and turned into a functional site

Recipe

Now to how we mix all the ingredients into an website!

Zola flow

I will spare the details of how to actually work with it, which is much better served by their docs which helped me get on my feet.

I'm simple, so i simply picked a simple theme called even, it was easy to configure, appeared to just work out of the box, and most importantly it fit the format i want this blog post to have. I write something based on date, publish and done.

There isn't much in the way of workflow, i configured the initial configuration.toml with the theme i wanted, the syntax highlighting and even theme configuration options.

After the initial setup is done, creating a new blog post is a matter of creating a new markdown file, filling the front-matter with:

+++
title = "TITLE"
date = YYYY-MM-DD
+++

And write away! One thing i liked a lot was how nice working with zola was, running zola serve --port 8080 --interface 0.0.0.0 allowed me to just see how my site would ultimately look and automatically refresh as i saved the markdown file that is the post being written, and it looks out for file changes so when you save, the site is refreshed automatically.

Travis CI Flow

Most of the work is done by it, for the initial setup i had to create a token just for it with access to pushing to repos, and then went to travis-ci.org and set it to an environment variable called GH_TOKEN.

This is my .travis.yml file at the time of writing this post.

branches:
    only:
        - devel

before_script:
  # Download and unzip the zola executable
  # Replace the version numbers in the URL by the version you want to use
  - curl -s -L https://github.com/getzola/zola/releases/download/v0.5.1/zola-v0.5.1-x86_64-unknown-linux-gnu.tar.gz | sudo tar xvzf - -C /usr/local/bin

script: |
  cd themes &&
  git clone https://github.com/getzola/even.git &&
  cd ../ &&
  zola build
# If you are using a different folder than `public` for the output directory, you will
# need to change the `zola` command and the `ghp-import` path
after_success: |
  [ $TRAVIS_BRANCH = devel ] &&
  zola build -o docs &&
  sudo pip install ghp-import &&
  ghp-import -n docs -b master &&
  git push -fq https://${GH_TOKEN}@github.com/${TRAVIS_REPO_SLUG}.git master

It does a few things, it downloads zola and tries to build the site. If it succeeds it will build the site again and use ghp-import to create a branch that is pushable, in this case master is being used, and then it is pushed to the repo.

At the end of the day i just push to devel and the website is regenerated completely, i can even make fixes to previous posts.