Hugo is a popular static site generator written in the Go programming language. It is a tool that builds websites from your content files defined as simple text files (usually Markdown, but also Emacs Org Mode or AsciiDoc). The you run hugo build, and it generates a folder of plain HTML, CSS and JavaScript files ready to be hosted on the internet.

Installing Hugo

In macOS, you can install Hugo using Homebrew.

1
2

brew update
brew install hugo

Creating a new site

You can use the following command to start a new Hugo site project:

1
2

hugo new site my-site
cd my-site

Creating the first post

You can create a new post manually or using Hugo CLI.

• Manually: You just need to create a new .md file inside content folder. Later, manually write the front matter which is a special syntax to tell hugo some information/metadata about the post.
• Using the Hugo CLI: Alternativelly, you can create a new post using the CLI, use the following command: hugo new content content/posts/post-1.md.

Grouping posts

To create a section or collectino of posts, you can just create a new folder inside content. For example, lets create 3 posts and group them inside the posts folder:

1
2
3

hugo new content content/posts/post1.md
hugo new content content/posts/post2.md
hugo new content content/posts/post3.md

Post ordering

Hugo’s default fallback order for content lists is first by weight, then by date if weights are equal or zero. Setting a weight overrides the date priority for explicit placement, while unweighted posts fall back to date sorting.

Using markdown to create content

Hugo has Markdown support out of the box. By default, Hugo uses the Goldmark Markdown processor which is fully CommonMark compliant.

Reference:

• https://www.markdownguide.org/tools/hugo/
• https://github.com/yuin/goldmark

Serving Locally

You can run hugo locally with a simple hugo server command. Use --buildDrafts flag to include posts with draft: true in the front matter.

1

hugo server --buildDrafts

Hugo Machinery

Matching content to template

Hugo scans content/ directory and turns each file or folder into a page. Each file inside content/ has a kind value that Hugo engine assigns automatically.

A file called _index.md means “this is a list page,” while a regular file like index.md or post1.md is an individual page (kind is page) that matches the single.html template.

You can overwrite the kind of a markdown file by setting layout "recipe" in front matter, Hugo tries layouts/posts/recipe.html and layouts/recipe.html before the defaults.

Hugo checks your project’s layouts/ folder before the theme’s layouts/ folder for each candidate.

If the file lives at content/posts/hello.md. Hugo takes the first folder under content/ and calls it the section. Unless you override it, the section name becomes the page’s type. If the file were content/blog/hello.md, the type would be blog, and Hugo would look in layouts/blog/ instead. You can override this with type: “article” in front matter. Then Hugo would look in layouts/article/, even though the file is in posts/.

The template filename comes from the page’s kind, and Hugo has a fixed vocabulary for this:

• single.html is for a kind of page, meaning one individual piece of content (hello.md).
• list.html is for kinds that are collections: sections, taxonomies, terms. It displays a list of other pages.
• home.html / index.html is for the home page.

Hugo decides hello.md is a page because it’s a regular content file, not an _index.md. A page renders with single.html because that is the rule Hugo hard-codes: one page, one template, named “single.” There’s nothing more to it than convention.

When you download a theme, like PaperMod, it ships with a complete set of templates, including the home layout, list layout, single-page layout, and so on. Its partials are then called by those layouts.

Taxonomy

A taxonomy in Hugo is a way to classify and group your content.

The taxonomy.html template renders the page that lists all terms of a taxonomy, such as /tags/ or /categories/.

You define the taxonomies inside hugo config file. Then hugo will render the taxonomy for each entry of the config.

If you have no taxonomy.html, Hugo falls back to list.html, which often works if it loops over .Pages.

Template language syntax

.RelPermalink

.RelPermalink returns the page’s relative URL: the path without the domain. It’s what you normally use for internal links.

• .RelPermalink: /posts/my-post/
• .Permalink: https://example.com/posts/my-post/

.Pages

If the same list.html gets used for several kinds of pages, and .Pages means something different in each.

So you need different template files like list.html, taxonomy.html, single.html.

Layouts

Layout is the directory where all the Hugo templates will be stored. You have root/layout and root/themes/PaperMod/layouts. The first has higher priority that the second, this allow you to override themes default template files.

Templates

Templates are the files that decide what the HTML looks like. Hugo takes your content and pours it into a template.

Templates use variables, functions, and methods to transform your content, resources, and data into a published page. Hugo engine will populate those variables, so that your templates files can use to build the HTML page.

For example:

1
2

<h1>{ { .Title }}</h1>
<div>{ { .Content }}</div>

Hugo replaces { { .Title }} and { { .Content }} with the actual title and body from your Markdown file.

Engine under the hood

Hugo uses Go’s text/template and html/template packages.

Multiple output formats

While HTML templates are the most common, you can create templates for any output format including CSV, JSON, RSS, and plain text.

Reference:

• https://gohugo.io/templates/introduction/
• https://gohugo.io/templates/types/

Shortcodes

Shortcodes are templates that you call explicitly from inside content, for things Markdown has no syntax for.

A Hugo Shortcode is a type of template that you can invoke from the content markup file.

Some shortcodes are built-in. For example the figure shortcode, which allow you to insert images from markdown.

Shortcodes lives under layouts/_shortcodes directory.

Reference:

• https://gohugo.io/templates/shortcode/

Partials

Partials are reusable template fragments called from other templates, never from content. It is the Hugo way of allowing you to modularize templates files. It is a piece of a layout (HTML) that lives in its own file. Later, you can import the partial from the layout itself. This allow you to expand the capabilities of the site generator, like for example, adding support to LaTeX syntax. If you analyse the PaperMod theme, you will see that it imports several partials.

Variables

When Hugo’s parser meets some link inside your markdown, it extracts the pieces and hands them to your template as variables: .Text, .Destination. Title, .Page. This happens for several other objects inside your content file.

Render hooks

Render hooks override how Hugo turns standard Markdown into HTML. You don’t change your content at all.

You add a template such as layouts/_markup/render-link.html, and every Markdown link, image, heading, code block or blockquote in the site then goes through it.

The name render-link.html is a fixed convention. Hugo has a set list of hook names, one per Markdown element:

• render-link.html
• render-image.html
• render-heading.html
• render-codeblock.html
• render-blockquote.html
• render-table.html

Use them when you want to change the output of syntax you’re already writing, for example adding target="_blank" to external links, wrapping images in

1
2
3

hugo --cleanDestinationDir
hugo server --disableFastRender
rm -rf ./public && hugo server  --panicOnWarning --ignoreCache --disableFastRender --cleanDestinationDir

1

git clone https://github.com/adityatelange/hugo-PaperMod themes/PaperMod --depth=1

1

theme: ["PaperMod"]

1
2

params:
  custom_css: ["custom.css"]

1
2
3

{{ range .Site.Params.custom_css -}}
    <link rel="stylesheet" href="{{ . | absURL }}">
{{- end }}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

# hugo.yaml
params:
  assets:
    disableHLJS: true

markup:
  highlight:
    codeFences: true
    guessSyntax: true
    lineNos: true
    noClasses: false
    style: github

1

hugo gen chromastyles --style=monokailight > themes/PaperMod/assets/css/includes/chroma-styles.css