July 14, 2019

Hugo on Arch and GitLab

hugo bash asciidoc

Hugo is a static site generator in Go created by Steve Francia and Bjørn Erik Pedersen. It has an impressive modular design, you can just plug in different themes and text processors, for example using markdown and asciidoc on the same site is no problem at all. It is easy to set up and there are plenty of open source templates available to pick from. Because it creates static pages you can use GitLab to host your site for free.

To edit the content you can use any text editor. For rendering the html content, hugo will invoke the asciidoc command for files with '.adoc' extension, you can use custom templates to improve the rendered html code.
Here is how to set up a page with hugo and asciidoctor on an Arch Linux System.

Ingredients

You need

Installation

The installation is simple and can be done with a few commands in bash:

GITLAB_USER=whatever_your_username_is

# install the tools on your system
sudo pacman -Syu hugo chromium asciidoctor

# install asciidoctor-html5s
gem install asciidoctor-html5s

# cd to a directoy where you want to keep your site
cd .../Documents/blog

# clone the repo from gitlab
git clone https://gitlab.com/pages/hugo.git

# remove the original remote and push to your own repo on gitlab
git remote rm origin
git remote add origin https://gitlab.com/${GITLAB_USER}/blog.git
git push --set-upstream origin master

# review the example content and theme on your own gitlab site
chromium https://${GITLAB_USER}.gitlab.io/blog/

Configuration

Google Analytics

Hugo is prepared for using Google Analytics, all you need to do is

  1. Login at [https://analytics.google.com](google) and get a trackingId
  2. Add the trackingId as
    googleAnalytics = "UA-xxxxxxxxxx-y"
    to your config.toml

Hugo has an internal template that should be included in the header in your root template file:

template "_internal/google_analytics_async.html" .

Build

In order to have asciidoctor and the asciidoctor-html5s templates available during the build and rendering on GitLab you need to customize the GitLab build image in .gitlab-ci.yml:

image: registry.gitlab.com/pages/hugo:latest
before_script:
  - apk add asciidoctor
  - gem install asciidoctor-html5s
[...]

themes

All hugo Themes are located in the hugo/themes director, you can pick on from https://themes.gohugo.io/ and install it:

cd .../Documents/blog/hugo/themes
git clone https://github.com/gyorb/hugo-dusk.git
rm -rf ./hugo-dusk/.git*

Usually a hugo theme comes with a config.toml file, you have to move it to the root folder of your installation and customize it:

cd .../Documents/blog/hugo/themes
mv ./<fancy theme>/exampleSite/config.toml ../
vi ../config.toml

Check the theme documentation for details about the parameters.

content

The content directory has a page and a post subdirectory, just edit or add a file there, and it will show up when running the next rendering cycle.

cd .../Documents/blog
hugo serve
chromium http://localhost:1313/blog/

the text processor for rendering the page is picked by the file ending (use .md for markdown or .adoc for asciidoc)

to include draft version in local:

hugo --buildDrafts serve

to create a new post:

hugo new posts/2019-07-25-setup-k8s-cluster-on-azure.adoc

some gotchas

I had to learn the hard way…​