Skip to main content
  1. Posts/

Setup a HUGO Site

·969 words·5 mins·
Blog Website Web Development HUGO
ahmza
Author
ahmza
Table of Contents

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 an ssg 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
#

  • Git

Installing HUGO
#

Official steps

The HUGO binary is used to initialize our site then create posts etc… Below are the steps for MacOS and Arch based Linux distros.

MacOS
#

brew install hugo

Arch
#

sudo pacman -S hugo

Confirm Installation
#

hugo version

Create your site
#

This assumes choices 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

pick an editor of your choice. I use NVIM BTW

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

➜  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

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
  • The HUGO built in server
  • webp + webm (still need to add this)
  • shortcodes (still need to add this)