NOTE: Details about markdown syntax are here.

Table of Contents

  1. Hugo Overview
    1. Basic Hugo commands
    2. Themes
    3. Archetypes
    1. Templates
    1. Partial Templates
    2. Hugo Variables
    3. Hugo Functions
    1. Data
    2. Shortcodes
    3. Themes
  2. Images
    1. Basic Insertion
    2. Fancybox
    3. Page Bundles
  3. Code Notes
    1. Links
    2. My Shortcodes
    3. target=”_blank”
    4. Enable html in markdown
    5. Emojis
  4. Deploy

Hugo Overview

Basic Hugo commands

  • <>

###Content Creation

New Page

hugo new
hugo new folder/
– to use archetype: hugo new folder/folder2/ -k name_of_type

New List Pages

Hugo will automatically create a list page at root level but not in lower levels so use
hugo new folder/ to create a list page.
– works for sub-directory pages: hugo new folder/folder2/

Running the server

Run server

This opens a testing server at <http://localhost:1313>
hugo server
hugo server -D (shows drafts)

Build site

hugo -D (shows drafts)

  • this creates a “public” folder with your built site
  • remember to delete before next build

New Site

hugo new site NewSiteName

Check your version

hugo version
brew upgrade hugo
– find executable which hugo

Check config

To view your siteโ€™s current configuration, which includes a lot of default settings, run the following command from the directory:

hugo config | more


  • Themeless repo <>
  • Bare White Theme <>
  • create your own i.e. astart-theme


Are templates for default pages, frontmatter etc. (see next section)
– /archetypes/

### Sample Format

title: “{{ replace .Name “-” ” ” | title }}”
date: {{ .Date }}
draft: true

author: [“Bob”,”Ted”,”Alice”]

  • Remember to delete in top level directory when using a theme’s archetypes
  • Can add custom defaults: author: "Author Name", dotColor: etc.
  • can be used to add comments (i.e. shortcodes)
  • Can use lists (arrays) [“option1”, “option2”]
  • Use custom archetypes by naming them same as directory (DirName).
  • E.g. /archetypes/ will affect all files in/content/DirName/


  • sets parameters for individual pages
  • created by Archetypes. Can be modified individually.
  • in YAML, TOML or json
  • can add custom content & variables
  • myVar: "MyValue"
  • image: "MyPostImage"

YAML delineated by:

title: “This is a title”
date: 2020-01-01T:11:12:19-04:00

draft: true

TOML delineated by:

title = “This is my title”
date: 2020-01-01T:11:12:19-04:00
draft = False

Standard Taxonomies (tags and categories)

Hugo automatically generates list pages for standard taxonomies.
– They are placed in frontmatter:

title: “This is a title”
tags: [“Coding”, “Python”, “Web Development”]

categories: [“Computers”]

Custom Taxonomies

You can add custom taxonomies i.e. moods: ["happy","upbeat","sad", "morose"] to frontmatter
– they don’t automatically generate list page
– must be added to config.toml (When adding custom taxonomies, you need to put in the default taxonomies too, if you want to keep them.)
– note singular vs plural construction

tag = "tags"
category = "categories"
mood = "moods"`


parent: art
weight: 100


  • <>
  • found in:
  • /themes/theme-name/layouts/_default/ list.html, single.html
  • /layouts/_default/ list.html, single.html
  • can create basic templates for specific pages e.g. index.html, 404.html etc.


Can be use in shortcodes, layouts and partials

Basic Templates

List templates

  • /layouts/_default/list.html
  • /themes/theme-name/layouts/list.html

Single templates

  • /layouts/_default/single.html
  • /themes/theme-name/layouts/single.html

Homepage template

  • /layouts/index.html
  • /themes/theme-name/layouts/index.html

Section Templates

Create folder in /layouts/ named after section in /content/
/layouts/DirName/single.html affects files in /content/DirName/single.html
– can be list.html, single.html and index.html templates
– overrides default templates

Base (baseof) Templates

Are an over-arching template for organizing entire Hugo website.
– Can be used to define Header -> Main Content – > Sidebar -> Footer structure
– sections are called Blocks

Create a new file /layouts/_default/baseof.html
– use a basic html layout
– insert blocks where appropriate

{{block “main” . }}



{{block “footer” . }}
Default base of footer

In Layout Pages

  • remove html from single.html and list.html etc. templates
  • to call in layout template add:

{{ define “main” }}
This is content

  • you can override Block in single.html, list.html

{{ define “footer” }}
Override default footer

Partial templates

  • Used to create smaller elements
  • header, footer etc.
  • place in /layouts/partials/MyPartial.html
  • use in template {{partial "mypartial" . }}
  • “.” refers to scope

Can pass custom dictionary etc. as scope
{{partial "header" (dict "MyTitle" "Custom Title" "MyDate" "Custom Date") }} in template
– then add {{.MyTitle}} or {{.MyDate}} in header.html (partial) to call custom info

Hugo Variables

  • can’t be used in content files โ€” only in templates
  • displays content: {{.Content}}
  • url: {{.URL}} url
  • title: {{.Title}}
  • visit <>

Custom Frontmatter Variables

  • access in template files
  • in frontmatter of content md file
  • color: "blue"
  • {{.Params.color}}
  • can be used in html (`


Custom Variables

  • define {{ $myVarName := "A String"}}
  • call {{$myVarName}}

Hugo Functions

  • can only used in layout folder (templates etc. like variables)
  • <>
  • {{function_name param1, param2}}
  • {{truncate 10 “This is a really, really really long string”}}
  • {{add 1 5}} gives 6
  • {{singularize “dogs”}} gives dog

Loop through pages and adds title:

{{range .Pages}}




  • eq equals
  • lt less than
  • le less than or equals
  • gt greater than
  • ge greater than or equals
  • ne not equals

{{if eq $var1 $var2}} or {{if not (eq $var1 $var2)}}

{{if and (lt $var1 $var2) (lt $var1 $var3)}}

Else/Else if
{{else if eq $var1 $var2}}

{{$title := .Title}}
{{range .Site.Pages}}




  • Use in layouts folder (templates)
  • place datafile in /data/
  • json, YAML, toml

{{range .Site.Data.boatlist}}
{{.Name}} โ€” ${{.Price}}


Hugo Shortcodes

{{&lt; shortcode_name param1 &gt;}}

  • Youtube Shortcode: {{}}
  • Instagram Shortcode: {{&lt; instagram_simple BGvuInzyFAe hidecaption &gt;}}
  • Twitter: {{&lt; tweet 1085870671291310081 &gt;}}
  • Vimeo Simple : {{&lt; vimeo_simple 48912912 &gt;}}
  • <>

Custom Shortcodes

see My Shortcodes
– partials for using in content markdown files
– in /layouts/shortcodes/myshortcodename.html
– call with {{&lt; myshortcodename &gt;}}
– can have double tags:
{{&lt; myshortcodename &gt;}}
This is test in the shortcode tags
{{&lt; /myshortcodename &gt;}}
– call with {{.Inner}}
– `


- won't render markdown unless in{{% /myshortcodename %}}` (doesnt’t work?)

Can pass in Variables
{{&lt; myshortcodename color="blue"&gt;}}
– in shortcode file: `

This is the Shortcode text

– use tick marks instead of single quotes for embedded quotes

Positional parameter

  • `

This is the Shortcode text

– grabs first parameter (parameter number 0)


Download theme to /themes/ and

Install a theme

$ cd themes
$ git clone URL_TO_THEME

  • add theme = "themename" to config.toml
  • run hugo -t ThemeName


Basic Insertion

Place images in /static
– markdown: ![image alt text](/my_image.png)
– html: “
– figure shortcode: {{&lt; figure src="/media/spf13.jpg" title="Steve Francia" &gt;}}
– lots of parameters like target, caption, class etc. <>


Image links for the above shortcodes use Fancybox3 as a lightbox <>

Page Bundles

Allow you to bundle resources in one area.
– consists of folder, a file named, and resources (i.e images etc)

Code Notes


[The details can be found here]({{< relref “about-the-book” >}})
– allows internal links

My Shortcodes


{{< link “See more here” “posts/some-title” >}}
– creates permalink shortcode relative to baseurl.
– modified from <>
– takes 2 unnamed parameters
– First parameter is the link text “See more here”
– Second parameter is the relative URL “posts/some-title”


{{< youtube id=”RabX4yNyd6s” width=”600″ class=”youtube” >}}
– takes one named parameter: width=”000″
– defaults to 400 x 225


{{< video src=”Extro-V2.mp4″ poster=”BK-ID-Poster-V2-400×225.png” width=”200″>}}
– links to page Bundle video
– takes 3 named parameters:src=, poster= (default image file) and width=
– width defaults to 400


{{< singleimage “*cats*” “This is a caption” Fill “200×200” >}}

This is a single image shortcode to display images from the Page Bundle.
– 5 unnamed parameters
1. name is “*filename*” without file ending
2. caption
3. Resize, Fill, or Fit
4. Image size Resize uses “000” and Fill or Fit uses”000×000″
5. optional external href “”
– resizes linked original to “1200×800”


{{< singleimagestatic “feather.jpg” “Fit 300×300” Fit “300×300” >}}

This is a single image shortcode to display images from the root /assets/images folder.
– 4 unnnamed parameters
1. name is “filename.jpg” must have file ending!
2. caption
3. Resize, Fill, or Fit
4. Image size Resize uses “000” and Fill or Fit uses”000×000″
– resizes linked original to “1200×800”


{{< figurerev src=”/feather.jpg” link=”” Target=”_blank” title=”Image Title” caption=”Bob, Bob, Bob!” alt=”This is the alt text.” height=”200″ width=”325″ class=”gallery” >}}

  • based on Hugo’s original figure short code <>
  • displays images from root /assets/images folder with lots of parameters available

A single permanent image

[image alt text](/images/BK-ID-headerlogo.png)

A single image from the /static/ folder
– renders exactly as is
– meant for global images


{{< flex box >}}
{{<singleimage “” “” “”>}}
{{< /flexbox>}}
– nested images within a flexbox container


{{< foldergallery “200” >}}

An automatic gallery of photographs from the Page Bundle.
– no way to display captions
– takes size as unnamed parameter: “400”
– resizes linked original to “1200×800”


{{< foldergalleryfilter “200” >}}

Same as above but adds filters
– filters must be set in shortcode at this point
– Grayscale, Sepia, Gaussian Blur


DEPRECATED: Superceded by Using singleimage with ‘flex box’ instead

{{< foldergallerylist “IMG_6535” “This is a loaf of bread” “200” >}}
{{< foldergallerylist “cats” “This is Pete and Em again” “200” >}}

This is a gallery of images stored in the Page Bundle, but called by means of a list, which allows it to have custom sizes and captions.
– For now it needs to have a \

surrounding it to clear the float.

  • 4 unnnamed parameters
  1. name is “filename.jpg” must have file ending!
  2. caption
  3. Height Fit size
  4. optional external link “”

– resizes linked original to “1200×800”

JSON boatlist and ebooklist

Shortcodes to list json data files
boatlist uses two columns
{{booklist "magazines"}} uses one parameter to name database in file
{{&lt; ebooklist &gt;}}


  • in config.toml file



plainIDAnchors = true
hrefTargetBlank = true



The Markdown renderer has changed in the latest Hugo v0.62.0 from Blackfriday to Goldmark which should allow Hugo markdown to be more compatible with other markdown flavours, such as that of GitHub.

In order to open links in new tab with the Goldmark markdown renderer, create a file at layouts/_default/_markup/render-link.html with the following content:

{{ .Text }}

Enable html in markdown



defaultMarkdownHandler = “goldmark”
unsafe = true


defaultMarkdownHandler = “blackfriday”


enableEmoji = true to config.toml

Must be above Optional Parameters section
– ๐Ÿ™‚
– :frowning_face_:
– :heart:

Use {{ emojify :smile: :heart: :frowning_face_: }} in templates


Change to active directory
– /Site Astart ./deploy
– need to change config.toml to add publishDir ="astart/"

Deploy script

DIR=home/macblaze/public_html/ # the directory where your web site files should go

hugo && rsync -avz –exclude=’.DS_Store’ –delete /Users/admin/Documents/Projects/WEB\ PROJECTS/Site\ Astart/astart ${USER}@${HOST}:/${DIR}

exit 0

  • needs full local path
  • local publishDir must match dir on server

Note: ssh configured to go direct to astart/ directory