Notes on Hugo for Beginners (and Me), Part 1, Creating a New Post

4 Jan 2022 4-minute read Al Eardley
Community
Hugo

I’m happy I have moved everything to Hugo but I learned a lot on the journey and I need to remember what I have done so I can change things in the future and share my experiences.

Creating a new post

Possibly the most important element to remember: what do I type to create a new post?

hugo new posts/2022/2022-01-04-notes-on-hugo -k post-bundle

The elements of the statement are as follows

  • “hugo” starts the service
  • “new” indicates a new post is to be created
  • “posts/2022/” is the path within the content directory where the new post would be created
  • “2022-01-04-notes-on-hugo” is name of the post and will be the folder where the files will be stored
  • “-k post-bundle” indicates the “kind” of archetype to be used. In this case, the contents of the “archetypes/post-bundle” folder will be used as the template

Default and Bundles

The “archetypes” folder stoers the default “.md” file and template bundles of files. The content of “default.md” is used as the content for any new “.md” file created when a bundle is not used. When a bundle is used, all of the files in the archtetype bunlde are copied to the new post folder.

My post bundle is made up of the following:

  • \files\sample.txt - an empty text file that is there so that the folder is copied
  • \images\sample.png - as test image that is there so that the folder is copied
  • \tables\table.html - a sample html file that is there so that the folder is copied and that contains sample HTML to create a table with approporiate classes
  • index.md - the main markdown file used to write the content fot the blog post

index.md

This is the location where the bulk of the work goes on when writing a post.

Metadata

Each post page from the post-budle starts with some metadata (referred to “Front Matter” in Hugo). There is a choice of languages to use to define it. I have chosen to use YAML as it uses colons, like JSON and CSS, and square brackets to contain arrays.

The Front Matter I use for posts is as follows:

title: "Notes on Hugo for Beginners (and Me)"
date: 2022-01-04
author: "Al Eardley"
description: ""
categories: ["Community"]
tags: ["Hugo"]
series: []
disableComments: true
toc: true

All of the Front Matter is accessible through .Params.name. This allows all of these values to be used when laying out a post and to be used when grouping content based on categories, tags and series.

If the post is not part of a series then the Front Matter is removed. If it is a short post that doesn’t need a table of contents, then the toc setting is changed to false.

Hugo Shortcodes

To help me, I have some code samples that I am likely to use in new blog posts.

A link to a reference page such as https://gohugo.io/content-management/cross-references/ would be written as

[https://gohugo.io/content-management/cross-references/](https://gohugo.io/content-management/cross-references/)

A relational link would be rendered as

[about]({{< ref "/about" >}})

or

[Move to Hugo]({{< ref "/posts/2022/2022-01-01-move-to-hugo" >}})

is rendered as Move to Hugo)

Include HTML files

One short-coming of markdown is the lack of control over the classes used to style complex HTML such as tables. To overcome this, I created a shortcode to include an HTML file. I chose to use the tables folder to store HTML as the only scenario that I have needed it is for tables to ensure that they are properly layed out.

I found the pattern for the shortcode at https://xa1.at/hugo-include-html/

{{< include-html "tables/table01.html" >}}

Attachments

Several of my posts include associated files that can be downloaded so I created a shortcode to allow the contents of the files folder to be listed:

There are a lot of samples out there if you search for hugo shortcode "attachments.html". Once you have your shortcode, it is easy to reference and to adapt it, if needed.

{{< attachments >}}

Summary

In the next part in this series, I will explain the structure of the files and folders, and explain how they fit together to generate the navigation, the posts and the groups of taxonomy terms.

References

Thanks to https://liatas.com/posts/escaping-hugo-shortcodes/ for providing a solution to escaping the Hugo shortcodes so they could be explained.

Posts in this Series

Comment on this post: