Setup a HUGO Site

Introduction

Hugo is a static site generator, a tool that allows us to pre-compile our website into static HTML, CSS and JS. The main benefit of using such methods is speed. A Static site takes a lot less time to load than a site that uses databases.

For more information on HUGO read my other post Hugo Static Site Generator

Prerequisites

Installing HUGO

Official steps

The HUGO binary is what we will use throughout the creation of our project to initially setup our site then create posts etc… This step will vary depending on your operating system and distribution. I will show the steps for MacOS and Arch based Linux distros.

MacOS

Install homebrew

brew install hugo

Arch

sudo pacman -S hugo

Confirm Installation

hugo version

Create your site

This assumes a few steps for you, i.e the theme used. The settings in this guide will mimic the base config of my site

hugo new site -f yml <your-sitename>
cd <your-sitename>
git init
git submodule add --depth=1 https://github.com/adityatelange/hugo-PaperMod.git themes/PaperMod
echo "theme: 'PaperMod'" >> config.yml

Create Content

We will now begin adding new content to our website. Lets create our first post.

Lets start by creating a template for our posts.

vim archetypes/posts.md

Paste the following base template

---
title: {{ replace .TranslationBaseName "-" " " | title }}
date: {{ .Date }}
author: "<author>"
draft: true
weight: 

tags: [""]
description: ""
canonicalURL: "{{ .Page | absURL }}"

cover:
    image: "<image path/url>" # image path/url
    alt: "<alt text>" # alt text
    caption: "<text>" # display caption under cover
    relative: false # when using page bundles set this to true

---

## **Introduction**

## **Conclusion**

If the posts folder does not exist, create it

mkdir content/posts

Create and edit a post

hugo new posts/<post-name>.md
vim content/posts/<post-name>.md

Start the server

Now that we have created our site, installed a theme and created a post lets start the server.

hugo server -D

The -D flag tells hugo server to build drafts. (notice how we have a draft: option in our posts template.) Of course once you have finished a post you set draft to false like so draft: false

You will be shown something like the following:

➜  hugo server -D
Start building sites …
hugo v0.109.0+extended darwin/arm64 BuildDate=unknown

                   | EN
-------------------+-----
  Pages            | 10
  Paginator pages  |  0
  Non-page files   |  0
  Static files     |  0
  Processed images |  0
  Aliases          |  2
  Sitemaps         |  1
  Cleaned          |  0

Built in 12 ms
Watching for changes in /home/ahmza/prj/ahmza/{archetypes,assets,content,data,layouts,static,themes}
Watching for config changes in /home/ahmza/prj/ahmza/config.yml
Environment: "development"
Serving pages from memory
Running in Fast Render Mode. For full rebuilds on change: hugo server --disableFastRender
Web Server is available at http://localhost:1313/ (bind address 127.0.0.1)
Press Ctrl+C to stop

Notice the second line to the bottom. Web Server… This line gives you a localhost url that you can use in your browser to view your site locally.

Configure Site

Open the config.yml file in a text editor.

vim config.yml

Important changes you need to make

baseURL - this is the URL your site will be accessed externally. In my case. https://blog.ahmza.com
title - is the title of your page.

Here is my config.yml with bits redacted so you can fill them in

baseURL: "<your sites URL>"
title: <your site title>
paginate: 5
theme: PaperMod

enableRobotsTXT: true
buildDrafts: false
buildFuture: false
buildExpired: false
enableEmoji: true

googleAnalytics: <Google Analytics Tag>

minify:
  disableXML: true
  minifyOutput: true

outputs:
  home:
    - HTML
    - RSS
    - JSON

params:
  env: production # to enable google analytics, opengraph, twitter-cards and schema.
  title: <title>
  description: "<description>"
  keywords: [Blog, Portfolio, PaperMod]
  author: <author>
  images: ["<link or path of image for opengraph, twitter-cards>"] #Change this
  DateFormat: "January 2, 2006"
  defaultTheme: auto # dark, light
  disableThemeToggle: false

  ShowReadingTime: true
  ShowShareButtons: false
  ShowPostNavLinks: false
  ShowBreadCrumbs: true
  ShowCodeCopyButtons: true
  ShowWordCount: true
  ShowRssButtonInSectionTermList: true
  UseHugoToc: false
  disableSpecial1stPost: false
  disableScrollToTop: false
  hideFooter: false
  comments: false
  hidemeta: false
  hideSummary: false
  showtoc: true
  tocopen: false

  assets:
    # disableHLJS: true # to disable highlight.js
    # disableFingerprinting: true
    favicon: "/img/favicon.png"
    favicon16x16: "/img/favicon.png"
    favicon32x32: "/img/favicon.png"
    apple_touch_icon: "/img/favicon.png"
    safari_pinned_tab: "/img/favicon.png"

  label:
    text: "<Home>"
    icon: /img/favicon.png
    iconHeight: 35

  # profile-mode
  profileMode:
    enabled: true # needs to be explicitly set
    title: "Welcome \U0001F44B"
    subtitle: "<subtitle>"
    imageUrl: "/img/favicon.png"
    imageWidth: 120
    imageHeight: 120
    imageTitle: "my image"
    buttons:
      - name: posts
        url: posts
      - name: archive
        url: archives
      - name: tags
        url: tags

  # home-info mode
  homeInfoParams:
    Title: "Welcome \U0001F44B"
    Content: "subtitle"

  socialIcons:
    - name: LinkedIn
      url: "https://linkedin.com/in/"
    - name: gitlab
      url: "https://gitlab.com/"

  cover:
    hidden: false # hide everywhere but not in structured data
    hiddenInList: false # hide on list pages and home
    hiddenInSingle: false # hide on single page

  editPost:
    URL: "https://gitlab.com/<user>/<repo>/-/blob/main/content"
    Text: "Suggest Changes" # edit text
    appendFilePath: true # to append file path to Edit link

  # for search
  # https://fusejs.io/api/options.html
  fuseOpts:
    isCaseSensitive: false
    shouldSort: true
    location: 0
    distance: 1000
    threshold: 0.4
    minMatchCharLength: 0
    keys: ["title", "permalink", "summary", "content"]

menu:
  main:
    - identifier: posts
      name: posts
      url: /posts/
      weight: 1
    - identifier: archive
      name: archive
      url: /archives/
      weight: 10
    - identifier: tags
      name: tags
      url: /tags/
      weight: 20
    - identifier: search
      name: search
      url: /search/
      weight: 30
# Read: https://github.com/adityatelange/hugo-PaperMod/wiki/FAQs#using-hugos-syntax-highlighter-chroma
pygmentsUseClasses: true
markup:
  highlight:
    noClasses: false
    codeFences: true
    guessSyntax: true
    # lineNos: true

Run the server again

Run the server and check out your hard work. Change settings make posts etc. Have fun !!

hugo server -D

Publish your site

Once you are happy with your site, you may want to publish it to the internet.

In the next post Publishing your HUGO site I will cover a basic method of publishing your site as well as a more complicated but automated workflow that I use.

Conclusion

Through this post you have learned to create your own HUGO site as well as create and edit posts. We also learned about

archetypes
Mark posts as drafts (expand on this
The hugo built in server (still need to add this))
webp + webm (still need to add this)
shortcodes (still need to add this)

Introduction#

Prerequisites#

Installing HUGO#

MacOS#

Arch#

Confirm Installation#

Create your site#

Create Content#

Start the server#

Configure Site#

Run the server again#

Publish your site#

Conclusion#