Handover Documentation

Version 0.1

Stuff your users don't care to know about.

How to Hugo

Objective

This section tells you how this online documentation is produced so that you know enough to create Hugo websites of your own.

What is Hugo?

Hugo is a static site generator (SSG) that is used to create this online documentation rendered using hugo-theme-techdoc theme. Contents of this website are written in Markdown

Requirements

Install docker

Or install NodeJS, Hugo, etc. the whole shebang per https://gohugo.io/getting-started/installing/

Procedure

Create a new site named sysdoc

Choose a suitable working directory and chdir to it. A new subdirectory named sysdoc will be created within after the following step. This subdirectory is self-contained and will hold the complete website.

docker run --rm -v $PWD:/usr/share/blog monachus/hugo hugo new site sysdoc

# Without doing this, you will struggle with file permissions
sudo chmod -R ugo+rw sysdoc

When running for the first time, the docker image monachus/hugo has to be downloaded from Docker Hub. So Internet connectivity is required to complete this step.

Within monachus/hugo container, the default working directory is /usr/share/blog. The docker run -v option maps the current directory to it so that sysdoc directory structure being created by hugo new site command will persist after the container has exited.

Change directory to sysdoc. Unless otherwise specified, all instructions below are done within sysdoc directory.

Enable version control (optional)

Install Git, so you can use it to maintain version control on this website

  • Create .gitignore

    # Hugo generated pages
    /public
    
  • Create .gitkeep in empty subdirectories so that they are not ignored by git add

    for _d in archetypes content data layouts resources static themes ; do touch $_d/.gitkeep; done
    
  • Initialize, add and commit

    git init
    git add .
    git commit -m "initial commit"
    
  • Create a new project for this Git repo, e.g. Gitlab.com, etc. and follow the instructions given there to push this Git repository to the remote server. This repo uses https://gitlab.com/dirisa/sysdoc

Install theme

Go over to https://themes.gohugo.io/ to pick a theme you like. I have chosen https://themes.gohugo.io/hugo-theme-techdoc/

git submodule add https://github.com/thingsym/hugo-theme-techdoc.git themes/hugo-theme-techdoc
git add .gitmodules themes/hugo-theme-techdoc
git commit -m "feat: Add theme as submodule"
git push

Configure theme

Customize config.toml using this as a starting point.

See examples of more complex website structure, https://github.com/thingsym/hugo-theme-techdoc/tree/master/exampleSite/content

Create contents

Copy example contents and start editing. Remember to git add-commit-push!

# The trailing / in source path is significant!
rsync -arv themes/hugo-theme-techdoc/exampleSite/content/ content/

Run webserver to serve live contents

By live contents, I mean that hugo watches the content directory for changes in real-time and re-render the HTML pages. So any change you make will appear as you hit browser refresh.

The current directory is sysdoc. Replace {your_ip} in the command below:

docker run -d -v $PWD:/usr/share/blog -p 80:1313 \
 monachus/hugo hugo server \
 --baseURL=http://{your_ip}/ \
 --bind=0.0.0.0 \
 --appendPort=false

Alternatively, if you have docker-compose installed, you can edit docker-compose.yml below, replacing {path/to/sysdoc} and {your_ip} with actual path

version: '2.2'
services:
  hugo:
    image: monachus/hugo
    volumes:
    - {path/to/sysdoc}:/usr/share/blog
    command:
    # https://gohugo.io/commands/hugo_server/
    - hugo
    - server
    - --baseURL=http://{your_ip}/
    - --bind=0.0.0.0
    - --appendPort=false
    ports:
    - "80:1313"
    restart: unless-stopped

Host website on Gitlab (optional)

Gitlab offers free hosting for static websites, https://about.gitlab.com/product/pages/

If you want Gitlab to re-render the website every time you commit to the master branch for example, you can add this .gitlab-ci.yml file to the top-level of the repo.

image: monachus/hugo

variables:
  GIT_SUBMODULE_STRATEGY: recursive

pages:
  script:
  - hugo
  artifacts:
    paths:
    - public
  only:
  - master
  - hugo-trial
Last updated on 29 Mar 2019 / Published on 28 Mar 2019
Edit on GitHub