NOTE: Details about markdown syntax are here.

Hugo Overview
- Frontmatter
- Standard Taxonomies
1. Templates
- Conditionals
1. Data
2. Shortcodes
3. Themes
Images
Code Notes
Deploy

Hugo Overview

Basic Hugo commands

<https://gohugo.io/commands/hugo/>

###Content Creation

New Page

hugo new filename.md
or
hugo new folder/filename.md
– to use archetype: hugo new folder/folder2/filename.md -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/_index.md to create a list page.
– works for sub-directory pages: hugo new folder/folder2/_index.md

Running the server

Run server

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

Build site

hugo
or
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

Themes

Themeless repo <https://github.com/infiniteink/themeless-gitless-intro-hugo/archive/master.zip>
Bare White Theme <https://github.com/niklasfasching/whitespace>
create your own i.e. astart-theme

Archetypes

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

### Sample Format

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

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

Remember to delete default.md 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/DirName.md will affect all files in/content/DirName/FileName.md

Frontmatter

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

[taxonomies]
tag = "tags"
category = "categories"
mood = "moods"`

Menus

menu:
[“main”,”secondary”]:
parent: art
weight: 100

Templates

<https://gohugo.io/templates/>
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.

Commenting

Can be use in shortcodes, layouts and partials
{{/*
Go HTML
multi-line
comment
*/}}

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 “footer” . }}
Default base of footer
{{end}}

In Layout Pages

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

{{ define “main” }}
This is content
{{end}}

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

{{ define “footer” }}
Override default footer
{{end}}

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 <https://gohugo.io/variables>

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)
<https://gohugo.io/functions/>
{{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}}
`

{{end}}`

Conditionals

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)}}
Then…
{{end}}

And/Or
– {{if and (lt $var1 $var2) (lt $var1 $var3)}}

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

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

{{end}}`

Data

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

{{range .Site.Data.boatlist}}
{{.Name}} — ${{.Price}}
{{end}}

Shortcodes

Hugo Shortcodes

{{< shortcode_name param1 >}}

Youtube Shortcode: {{}}
Instagram Shortcode: {{< instagram_simple BGvuInzyFAe hidecaption >}}
Twitter: {{< tweet 1085870671291310081 >}}
Vimeo Simple : {{< vimeo_simple 48912912 >}}
<https://gohugo.io/content-management/shortcodes/#use-hugos-built-in-shortcodes>

Custom Shortcodes

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

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

Can pass in Variables
– {{< myshortcodename color="blue">}}
– 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)

Themes

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

Images

Basic Insertion

Place images in /static
– markdown: ![image alt text](/my_image.png)
– html: “
– figure shortcode: {{< figure src="/media/spf13.jpg" title="Steve Francia" >}}
– lots of parameters like target, caption, class etc. <https://gohugo.io/content-management/shortcodes/#figure>

Fancybox

Image links for the above shortcodes use Fancybox3 as a lightbox <http://fancyapps.com/fancybox/3/>

Page Bundles

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

Code Notes

Links

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

My Shortcodes

`link`

{{< link “See more here” “posts/some-title” >}}
– creates permalink shortcode relative to baseurl.
– modified from <https://github.com/jorinvo/hugo-shortcodes/blob/master/shortcodes/link.html>
– takes 2 unnamed parameters
– First parameter is the link text “See more here”
– Second parameter is the relative URL “posts/some-title”

`youtube`

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

`video`

{{< 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`

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 “http://astart.ca”
– resizes linked original to “1200×800”

`singleimagestatic`

{{< 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”

`sample-figurerev`

{{< figurerev src=”/feather.jpg” link=”http://apple.com” 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 <https://github.com/gohugoio/hugo/blob/master/tpl/tplimpl/embedded/templates/shortcodes/figure.html>
displays images from root /assets/images folder with lots of parameters available
UNFINISHED

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

flexbox

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

`foldergallery`

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`

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

`old-foldergallerylist`

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

name is “filename.jpg” must have file ending!
caption
Height Fit size
optional external link “http://astart.ca”

– 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
– {{< ebooklist >}}

target=”_blank”

in config.toml file

Blackfriday

<https://code.luasoftware.com/tutorials/hugo/how-to-create-link-with-target-blanks-in-hugo-markdown/>

[Blackfriday]
plainIDAnchors = true
hrefTargetBlank = true

Goldmark

<https://agrimprasad.com/post/hugo-goldmark-markdown/>

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

<https://jdhao.github.io/2019/12/29/hugo_html_not_shown/>

Goldmark

[markup]
defaultMarkdownHandler = “goldmark”
[markup.goldmark]
[markup.goldmark.renderer]
unsafe = true

Blackfriday

[markup]
defaultMarkdownHandler = “blackfriday”

Emojis

enableEmoji = true to config.toml
<https://www.webfx.com/tools/emoji-cheat-sheet/>

Must be above Optional Parameters section
– 🙂
– :frowning_face_:
– :heart:

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

Deploy

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

Deploy script

#!/bin/sh
USER=user
HOST=domain
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

Table of Contents

Hugo Overview

Basic Hugo commands

New Page

New List Pages

Running the server

Run server

Build site

New Site

Check your version

Check config

Themes

Archetypes

### Sample Format

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

Frontmatter

draft: true

Standard Taxonomies (tags and categories)

categories: [“Computers”]

Custom Taxonomies

Menus

Templates

Commenting

Basic Templates

List templates

Single templates

Homepage template

Section Templates

Base (baseof) Templates

In Layout Pages

Partial templates

Hugo Variables

Custom Frontmatter Variables

Custom Variables

Hugo Functions

Conditionals

Data

Shortcodes

Hugo Shortcodes

Custom Shortcodes

Positional parameter

Themes

Install a theme

Images

Basic Insertion

Fancybox

Page Bundles

Code Notes

Links

My Shortcodes

link

youtube

video

singleimage

singleimagestatic

sample-figurerev

A single permanent image

flexbox

foldergallery

foldergalleryfilter

old-foldergallerylist

JSON boatlist and ebooklist

target=”_blank”

Blackfriday

Goldmark

Enable html in markdown

Goldmark

Blackfriday

Emojis

Deploy

Deploy script

`link`

`youtube`

`video`

`singleimage`

`singleimagestatic`

`sample-figurerev`

`foldergallery`

`foldergalleryfilter`

`old-foldergallerylist`

JSON `boatlist` and `ebooklist`