Skip to content

Latest commit

 

History

History

doc

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
archetypes
archetypes
 
 
assets
assets
 
 
content
content
 
 
data
data
 
 
layouts
layouts
 
 
static/images
static/images
 
 
README.md
README.md
 
 
go.mod
go.mod
 
 
hugo.toml
hugo.toml
 
 
make-class-pages.py
make-class-pages.py
 
 

README.md

Quick start guide

Required software

The docs use Hugo and the Hugo Relearn theme, an enhanced fork of the popular Hugo Learn theme.

Supported versions of Hugo and the Hugo Relearn theme

Hugo Relearn 7.3.2 is currently used (defined by a git tag in doc/go.mod).

  • The minimum Hugo version required by the Relearn theme is 0.126.0.
  • The current Ubuntu snap (which provides 0.142.0) also works.

Installation

  • Install Hugo 0.126 or newer (required by the Hugo Relearn theme) follow the guidance on https://gohugo.io/installing. You'll need to install Go as well: see https://go.dev/

    • On Ubuntu, use the snap package:

      • sudo snap install hugo installs the current version apt-get install hugo would install a version that is too old, (this applies up to Ubuntu 24.04)

    • To install Hugo from source, you need a recent golang-1.2x compiler:

      • On Ubuntu 22.04, this can be done with:

        sudo apt install golang-1.23-go
# Add it to your path, assuming your .local/bin/ is early in your PATH:
ln -s /usr/lib/go-1.23/bin/go ~/.local/bin/go
go version
go install github.com/gohugoio/hugo@v0.127.0

Development

  • Run a local server: hugo server

  • Open a browser at http://127.0.0.1:1313/new-docs/

  • Add content to doc/content/:

    • Documents are written in Markdown.
    • Please wrap lines in paragraphs to make reviews more manageable.
    • The menu hierarchy comes mainly from the directory structure in content/.
    • A file called _index.md is needed in a directory to define a new level in the menu.
    • For a page that has images or other stuff included, it is best to create a new directory: Put the contents in an index.md file (no _) and the related files next to it. See https://gohugo.io/content-management/organization/ for more information.

    See https://mcshelby.github.io/hugo-theme-relearn/ for more information about the features of the Relearn theme, including handy "shortcodes".

Note: When switching versions, before re-generating the documentation using hugo server, delete the previously generated static site using rm -r docs/public.

Notes for supporting current versions of Hugo and the Relearn theme

Backported fixes to support newer Hugo versions:

  • layouts/partials/header.html, it fixes: 
    ERROR deprecated: .Sites.First was deprecated in Hugo v0.127.0 and will be removed in Hugo 0.143.0. Use .Sites.Default instead.
  • layouts/partials/menu.html, it fixes: 
    ERROR deprecated: .Site.IsMultiLingual was deprecated in Hugo v0.124.0 and will be removed in Hugo 0.143.0. Use hugo.IsMultilingual instead.

The fixes for those issues were backported from the Hugo Relearn v7.x.x theme. When updating to Hugo Relearn 7.x.x, please remove them (if possible).

Tips when upgradubg to newer Hugo Relearn versions

Check the release notes of the Hugo Relearn theme for breaking changes: https://mcshelby.github.io/hugo-theme-relearn/introduction/releasenotes

These pages might need review when making changes as their content is generated by layouts/partials/content.html:

For a summary of the partials supported by the Hugo Relearn theme, see: https://mcshelby.github.io/hugo-theme-relearn/configuration/customization/partials

Hint: For upgrading the Hugo Relearn theme, you can use:

cd doc; hugo mod get -u github.com/McShelby/hugo-theme-relearn@7.4.0

Summary

Hugo >= 0.126 and the Hugo Relearn >= 7.3.2 are supported to render the docs.

References