Using hugo

Overview

This post can probably be read in two ways: for some people, it might serve as a concise introduction on how to use hugo for setting up and maintaining a blog/homepage - the kind of concise, where almost only the bare commands are provided without much explanation. For others (including myself, and the main reason for this post) it can be a short reference of the (my) most used hugo commands.

Starting a new project

To create the required folder structures with some basic files etc.:

> hugo new site SITENAME

It is highly recommend to directly init a git repository in the new site’s folder, i.e.

> cd SITENAME
> git init

But at this point, there is no theme installed, and usually not even the main config file present (see next section).

Configuring the site as a whole

To configure the site (as a whole) a file named hugo.toml is used (old convention was to use configuration.toml). In this file, stuff like title of the whole site, used theme etc. can be set.

Example:

baseURL = 'https://blog.martinloesch.net/'
languageCode = 'en-us'
copyright = "Copyright &copy; 2024 - Martin Lösch"
canonifyurls = true
title = "Martin's IMHO AFAIK"
theme = 'hugo-kiera'

paginate = 10

summaryLength = 30
enableEmoji = true
pygmentsCodeFences = true

# Note: to disable a social network icon delete or comment out the corresponding line
[author]
    name = "Martin Lösch"
    github = "dukemarty"
    gitlab = "dukemarty"
    #linkedin = "username"
    #facebook = "username"
    #twitter = "ds_says"
    #instagram = "username"
    #stackoverflow = "username"
    #youtube = "user/username" # or channel/channelname
    #devto = "username"


# color: 324A65

[params]
    tagline = "IMHO: I don't claim the universal truth / AFAIK: I write to the best of my knowledge"
    description = "Kiera: A Hugo theme for creative and technical writing."
    images = [""] #This is used for opengraph/twitter cards.
    customCSS = ["css/colors.css"]  #Optional Customised CSS
    favicon = "/images/favicon.ico"
    site_logo = "/images/hackingbear1-sitelogo.png"
    #utterancesRepo = "username/repository"
    #utterancesIssueTerm = "pathname"
    #homepageLength = 10
    #commentAutoload = true  #This mean reader don't need click, disqus comment autoload
    #mathjax = true #Enable display of mathematics using mathjax (LaTeX syntax)
    #katex = true #Enable display of mathematics using katex (Faster LaTeX rendering)
    #google_fonts = ["Staatliches"] # Adds additional google fonts
    #disableDarkModeCSS = false # disables css style for users using dark-mode

# uncomment to enable the Tags link on the main toolbar
 [[menu.main]]
   identifier = "tags"
   name = "Tags"
   url = "/tags"
   weight = 80

# uncomment to enable the Categories link on the main toolbar
 [[menu.main]]
   identifier = "categories"
   name = "Categories"
   url = "/categories"
   weight = 70

Themes

Themes can be found in the central theme repository. Different themes provide different hooks for customizing them.

Some thoughts (reminders for myself mostly):

Ananke seems limited regarding colors
Kiera seems nice (exhibit A: this blog) and is quite customizable
Terminal seems as if i should like it
Docsy is often used for technical documentation, have seen it used for exactly this even at my workplace

Basically two ways to add a new theme are promoted. First, to check out the theme as a git submodule. Thescond way is to just download the theme and put it in ``. Personally, i prefer the second way better, having always been uncomfortable with git submodules,

Adding content

Content is basically assigend to different categories based on the folder it is in. All files are placed somewhere in the content folder. If a subfolder contains a file named _index.md, the folder get’s it’s own overview site, which e.g. can be referenced in the menu. The basic command for adding content is

> hugo new content [...]

Static sites

Place general, static sites directly in the content folder, like this:

> hugo new content content/about.md

Posts

For (blog) posts, the default is to use a subfolder post, like this:

> hugo new content content/posts/my-first-post.md

Testing and using a site

To test the site, the local server can be started with the serve command, by default the site is then served at localhost:1313. As long as the server is running, the site is continuously re-created.

> hugo serve

To also show all site marked as DRAFT, the additional -D argument can be used:

> hugo serve -D

Content

The most convenient way is to provide Markdown files as content. There are no deeper secrets for the “normal” content of the site. But additionally, different attributes for the site can be set in the files front matter.

Syntactically, there are three different variants allowed and supported, which differ basically in the way how the section is separated from the normal content, and in the format of the provided values.

Additional material

justfile to simplify hugo usage

To not have to remember the correct command line arguments, and to not have to add the hugo directory to the path, is use a simple justfile in the root folder of all my website projects:

# use cmd.exe instead of sh:
set windows-shell := ["cmd.exe", "/c"]


hugo := 'D:\SYS\ProgramsCopyInstalled\hugo_extended_0.134.1_windows-amd64\hugo.exe'

[private]
@default:
    just --list


[doc("Run hugo, all arguments are looped through")]
[no-cd]
@hugo *args='':
    {{hugo}} {{args}}


[doc("Run hugo serve, all arguments are looped through")]
[no-cd]
@serve *args='':
    {{hugo}} serve {{args}}

[doc("Run hugo serve -D, all arguments are looped through")]
[no-cd]
@devel *args='':
    {{hugo}} serve -D {{args}}

#[positional-arguments]
[doc("Run hugo, all arguments are looped through")]
[no-cd]
@publish *args='':
    {{hugo}} {{args}}

Martin’s IMHO AFAIK