Docs Setup using Hugo

This site uses hugo to generate the help pages. Hugo is a website generator which takes MarkDown (see below) and converts it into HTML. This has several key advantages:

  • pages are stored web-ready, not have to wait to be generated,
  • authors are writing simple text files, not wasting time and effort on ‘making stuff look pretty’,
  • all pages follow the same template, so they all share a strong similar look and feel.

The whole site is stored in a git repository, with all of the benefits of verson control and history. The website is automatically generated when a git commit is made, so authors do not need to know how it works - as with all parts of BaziCloud, it just works.

Markdown is explained in detail here

Local Setup

hugo runs in a docker container, to using hugo commands is a little more complicated, however the local bash function will help. I have added teh following to my ~/.bash_local file

# convert hugo command into docker exec shell command
hugo() { CMD="hugo $@ " ; echo $CMD ; docker exec hugo_server_1 ash -c "$CMD" ; }

Which automatically convert hugo commands into the correct commands for the docker container.

Change of Docker Image

Docker image used is hugomods/hugo (previously I was using klakegg/hugo:alpine, but this is no longer kept up-to-date). The change has 2 effects:

  1. hugo function now uses ash instead of bash.
  2. the docker image no longer includes a web server on port 8080, so I need to change the config of the local web server. Docs can be access at http://pi1.brusch.co.uk:8001/

Based on Agrim Prasad’s Writeup I have created a file:

_layouts/_default/markup/render-link.html containing

<a href="{{ .Destination | safeURL }}" {{ with .Title}} title="{{ . }}" {{ end }}{{ if strings.HasPrefix .Destination "http" }} target="_blank" {{ end }}>{{ .Text }}</a>

This causes link text to include html entities, so I have modified it to:

<a href="{{ .Destination | safeURL }}" {{ with .Title}} title="{{ . }}" {{ end }}{{ if strings.HasPrefix .Destination "http" }} target="_blank" {{ end }}>{{ htmlUnescape .Text }}</a>

Using Shortcodes - Allow Comments in Markdown

This is no longer recommended, the preferred method is to use HTML comments. This is kept here for its value describing shortcodes.

In the directory themes/cupper-hugo-theme/layouts/shortcodes (where cupper-hugo-theme is the name of the active theme), I created a file call comment.html, which contains:

{{ if .Inner }}{{ end }}

This means that anything in the markdown which is surrounded by {{< comment >}} tag is not rendered, e.g.

{{< comment >}}
this is a comment
{{< /comment >}}

Lessons Learnt

After installing modoboa the nginx server kept returning Received HTTP/0.9 when not allowed. The root cause is that a different nginx config enabled http2 on port 80, which affects all servers.

Fix

Remove http2 parameter from all listen on port 80 statements.

server {
    listen 80;