Hugo

Create Hugo Site

Install Hugo from [https://gohugo.io/]

From Mac

brew install hugo

From Windows

choco install hugo -confirm

Reference: [https://gohugo.io/getting-started/installing#chocolatey-windows]

Create GitHub Page

From GitHub.com -> Create a new Repository, e.g., AlainBouchard.github.io

Create or Clone exiting Hugo repository

In this example, we’ll use project engineering-notes-site

Clone the GitHub repo to publish on the hugo site

engineering-notes-site> git clone git@github.com:AlainBouchard/engineering-notes-site.git

Create a new Hugo site

engineering-notes-site> hugo new site --force
engineering-notes-site> ls
archetypes  config.toml  content  data  layouts  public  static  themes

Clone the Theme directory

Example of theme, many can be found on Hugo site.

Hugo Theme Source: [https://themes.gohugo.io/themes/hugo-theme-relearn/]

cd themes
themes> git clone git@github.com:McShelby/hugo-theme-relearn.git

Update the Hugo config.toml file content with team

> vi config.toml
baseURL = "https://AlainBouchard.github.io/"
languageCode = "en-us"
title = "Alain Bouchard's Engineering Notes"
theme = "hugo-theme-relearn"

[outputs]
    home = [ "HTML", "RSS", "JSON"]

[module]

  [[module.imports]]
    path = "github.com/alain-bouchard-quality/engineering-notes"

    [[module.imports.mounts]]
      source = "content"
      target = "content"

Build

> hugo -t hugo-theme-relearn

Verify if the configuration is good

> hugo server

  • Create statics/logo.png

  • Create layouts/partials/logo.html

    <img src="logo.png">

  • Link (git submodule) the documents into the GitHub Page

    > rm -Rf public
> git submodule add -b master git@github.com:AlainBouchard/AlainBouchard.github.io.git public
> git remote -v

  • Expect the public directory to get created with the repo content

Use github documentation repo as content

In document source github repo

Source repo example: github.com/AlainBouchard/engineering-notes

> hugo mod init github.com/AlainBouchard/engineering-notes

In hugo project github repo

Hugo repo example: github.com/AlainBouchard/engineering-notes-site

> hugo mod init github.com/AlainBouchard/engineering-notes-site

Verify if the module work:

> hugo mod get github.com/AlainBouchard/engineering-notes

Expect go.sum to get created:

github.com/AlainBouchard/engineering-notes v0.0.0-20220518202018-bd023ee889d6 h1:0s4tNjEN0+jGCkNEObTbnW+akRJD5RdjJ8pPsUU5ROU=
github.com/AlainBouchard/engineering-notes v0.0.0-20220518202018-bd023ee889d6/go.mod h1:Z6BTmpjCul+gI1Za7PY2E0LgyfIJpyeII/zcRE3e654=

Expect go.mod to get updated:

module engineering-notes-site

go 1.18

require github.com/AlainBouchard/engineering-notes v0.0.0-20220518202018-bd023ee889d6 // indirect

Try locally

  1. Build

    > hugo
> hugo server --disableFastRender --ignoreCache

  2. Expect Hugo to run on [http://localhost:1313/]

Build for GitHub Page

  1. build for theme

    > hugo -t hugo-theme-relearn
> go the `/public`
> git status
> git add .
> git commit -m "xyz"
> git push

  2. expect the GitHub Page repo to be updated.

Training

(10 min)

References