diff --git a/content/blog/writing-workshop-instructions-with-hugo.md b/content/blog/writing-workshop-instructions-with-hugo.md new file mode 100644 index 0000000..0981048 --- /dev/null +++ b/content/blog/writing-workshop-instructions-with-hugo.md @@ -0,0 +1,202 @@ +--- +title: "Writing mini-training with Hugo" +date: 2019-02-20T00:00:00+02:00 +opensource: +- Hugo +--- + +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](https://gohugo.io/) can help us! + +As an example, in the rest of this article, we will craft a mini-training +about Hugo! + +# Installation + +As a prerequisite, we need to install Hugo. On MacOS, you can use brew: + +```sh +brew install hugo +``` + +If you are on another Operating System, check the +[Hugo Documentation](https://gohugo.io/getting-started/quick-start/). + +# Bootstrap a site + +Bootstrap a Hugo site to hold the documentation of our mini-training. + +```sh +hugo new site hugo-workshop +``` + +# Add a theme to your site + +The [learn theme](https://learn.netlify.com/en/) 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! + +Install the learn theme: + +```sh +cd hugo-workshop +git init +git submodule add https://github.com/matcornic/hugo-theme-learn.git themes/learn +echo 'theme = "learn"' >> config.toml +``` + +# Generate content + +Use the [built-in Hugo archetypes](https://learn.netlify.com/en/cont/archetypes/) +to generate your documentation structure: + +```sh +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 +``` + +The `_index.md` is the home page for your mini-training. Let's settle for +something short: + +```md +--- +title: "Hugo Workshop" +--- + +# Welcome to my Hugo Workshop + +Welcome! Please have a seat and relax. +``` + +The `pre-requisites/_index.md`, `content/_index.md` and `packaging/_index.md` +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: + +```md ++++ +title = "Pre-requisites" +weight = 1 +chapter = true +pre = "1. " ++++ + +### 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](https://github.com/nmasse-itix/hugo-workshop/tree/master/content). + +# Customize the look and feel + +Edit the `config.toml` to match the following content: + +```toml +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: + +```sh +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 '' > layouts/partials/logo.html +curl "http://www.myiconfinder.com/icon/download/16895e53b6d340dffee1c9b84d90ca94-Redhat.png~10057" -o static/images/favicon.png +``` + +# Test locally + +You can test locally your new website by running: + +```sh +hugo server -D +``` + +In your web browser you can now open [localhost:1313](http://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: + +```sh +git add . +git commit -m 'initial version' +``` + +And push it on your GitHub account: + +```sh +git remote add origin git@github.com:nmasse-itix/hugo-workshop.git +git push -u origin master +``` + +# Next steps + +Congratulations! You now have your training instructions neatly organised and +clearly presented. Maintenance and collaboration have been greatly simplified! + +![Screenshot of our mini-training](hugo-screenshot.png) + +This article is the first of a serie. To be continued. \ No newline at end of file diff --git a/static/blog/writing-workshop-instructions-with-hugo/hugo-screenshot.png b/static/blog/writing-workshop-instructions-with-hugo/hugo-screenshot.png new file mode 100644 index 0000000..acc78f2 Binary files /dev/null and b/static/blog/writing-workshop-instructions-with-hugo/hugo-screenshot.png differ