In my professional life, I often have to lead workshops with customers or partners. During those workshops, participants expect to be trained on a piece of technology or software.
I usually have to provision everything needed to deliver this training and write the training instructions. Those instructions are organized as a step-by-step guide with screenshots, text, verbatim sections, links, files to downloads, etc.
And maybe more important, those instructions have to be well organized, each step has to be clearly stated, identified and formatted. The progression needs to be logic and easy. At any time, the participant needs to know where he is, which steps he has completed and which steps remain.
And for the trainer, it has to be easy to maintain and collaborative.
Crafting support materials that can meet all those requirements is challenging. Slide decks could fit the participants needs but are very difficult to maintain for the trainer. Markdown documentation in a GIT repository are better for suited for maintenance and collaboration but is difficult to work with for the participants.
Hopefully Hugo can help us!
As an example, in the rest of this article, we will craft a mini-training about Hugo!
As a prerequisite, we need to install Hugo. On MacOS, you can use brew:
brew install hugo
If you are on another Operating System, check the Hugo Documentation.
Bootstrap a site
Bootstrap a Hugo site to hold the documentation of our mini-training.
hugo new site hugo-workshop
Add a theme to your site
The learn theme for Hugo is one of the most suited design for training instructions. It features breadcrumb, navigation buttons, table of content in the sidebar, checkmark to know which sections the participant visited and much more!
cd hugo-workshop git init git submodule add https://github.com/matcornic/hugo-theme-learn.git themes/learn echo 'theme = "learn"' >> config.toml
Use the built-in Hugo archetypes to generate your documentation structure:
hugo new _index.md hugo new pre-requisites/_index.md --kind chapter hugo new pre-requisites/install.md hugo new pre-requisites/bootstrap.md hugo new pre-requisites/theme.md hugo new create-content/_index.md --kind chapter hugo new create-content/chapter.md hugo new create-content/section.md hugo new packaging/_index.md --kind chapter hugo new packaging/look-and-feel.md hugo new packaging/test-locally.md hugo new packaging/git-commit.md
_index.md is the home page for your mini-training. Let’s settle for
--- title: "Hugo Workshop" --- # Welcome to my Hugo Workshop Welcome! Please have a seat and relax.
are the first page of each chapter. You will usually use them to introduce the
subject or the use case you will implement.
For instance, the
pre-requisites/_index.md might look like:
+++ title = "Pre-requisites" weight = 1 chapter = true pre = "<b>1. </b>" +++ ### Chapter 1 # Pre-requisites This section will help you complete all the pre-requisites. Let's start with the installation!
Section files are regular Hugo content. The Table of Content on the left side
is ordered using the
weight attribute in the header of each file (both for
chapters and sections).
You can inspect those files from my GIT repository.
Customize the look and feel
config.toml to match the following content:
baseURL = "/" languageCode = "en-us" theme = "learn" [outputs] home = [ "HTML", "RSS", "JSON"] [params] showVisitedLinks = true disableBreadcrumb = false disableNextPrev = false themeVariant = "red"
This will enable cool features such as the search engine, the navigation, the breadcrumb and the checkmarks next in the table of content for visited links.
And, the left sidebar is now red!
Customize the logo and favicon with cool branding:
mkdir -p static/images/ curl https://upload.wikimedia.org/wikipedia/fr/c/cb/Red_hat_logo.png -o static/images/logo.png mkdir -p layouts/partials echo '<img src="/images/logo.png" />' > layouts/partials/logo.html curl "https://www.redhat.com/profiles/rh/themes/redhatdotcom/favicon.ico" -o static/images/favicon.png
You can test locally your new website by running:
hugo server -D
In your web browser you can now open localhost:1313 and admire your work!
Commit your work
By committing your work in a GIT repository, you will be able to collaborate with your peers for reviews and contributions.
Commit your work:
git add . git commit -m 'initial version'
And push it on your GitHub account:
git remote add origin firstname.lastname@example.org:nmasse-itix/hugo-workshop.git git push -u origin master
Congratulations! You now have your training instructions neatly organised and clearly presented. Maintenance and collaboration have been greatly simplified!
In this first part of the series, we presented a very light introduction to Hugo and its application to workshop instructions. Be sure to read part 2: Writing workshop instructions with Hugo, with variables in your content to discover advanced usages.