Create a FREE Blog - Hugo Static Websites

Recently I learnt about the existance of HUGO, a general-purpose website framework that will help you build static websites.

If this is the first time you hear about Static Websites - don’t be afraid.

A Static Website a Web that is composed of: html, css and js components. That’s it! No Databases to worry about - Making it easy (and secure) to create your first site.

The HUGO Site
The Drawio Source Code at Github
- License: Apache v2 ❤️

Let me show you the HUGO logo - our new friend:

What do I need to have my HUGO Website?

Dont worry about coding: I am not a Web Developer, not even a developer. Just be patience and dont be scared of the code.
- Find a HUGO Theme that you like: HUGO Themes
Install HUGO in your laptop.
Decide where your Website will be alive - aka where to deploy
Your Domain: Get your own or use free domains.
- You can buy one in many providers: Cloudflare, Porkbun, GoDaddy, NameCheap… (you can always migrate it later on)

Getting Started: How to install HUGO

In Windows

Simply download the latest version from their repository:

https://github.com/gohugoio/hugo/releases
Code in a folder where the hugo.exe is available

In ubuntu

You can use the version available in snap (it might no be the very latest):

sudo snap install hugo #https://snapcraft.io/hugo
snap install hugo --channel=extended

Alternatively, you can download a specific HUGO version like we did for windows with:

apt-get update -y

#https://github.com/gohugoio/hugo/releases 
#choose and adapt the link below to the desired version
wget https://github.com/gohugoio/hugo/releases/download/v0.87.0/hugo_0.87.0_Linux-64bit.deb

sudo dpkg -i hugo_0.87.0_Linux-64bit.deb #extract and install
#apt-get install -f #if dependency errors

Remember that the themes required some minimal version of HUGO to function properly.

Check HUGO version with:

hugo version

Choose a Theme for your Project

You are ready to create your HUGO site, but how to start? First things first. Make sure that you like some of the available templates:

Where to find F/OSS Hugo Themes:
- HUGO Themes
- HUGO Themes at JAMStack

You can check that the theme that you like is responsive - Use its demo link at https://pagespeed.web.dev/

Hugo Themes I Love

Using HUGO Themes

How to Create a new HUGO site

In a folder where HUGO application has acces to, simple execute:

hugo new site <your project name>
#hugo new site your_project_name

To generate the initial files that we will configure. This depends slightly from theme to theme, so for starters make sure to choose one with a good documentation.

I can recommend PaperMod with its great Wiki it helped me a lot to discover more about HUGO and actually made this post possible.

Downloading a HUGO Theme

Once you have decided on your theme, you have to clone the repository, don’t be afraid, this is just to download to the HUGO folder the files that its creator shared with the world:

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

Now, it is time to see HUGO in action, we have to tell it that we are interested to use the theme that we just downloaded. For that, we have to modify the theme config file.

There are two flavours of config files: .yaml and .toml, basically we are providing inputs parameters to HUGO about our site.

If you are more conformatable with .yml files, rather than .toml:

.\hugo new site <your project name> -f yml

For PaperMod, the very basic config file in yaml version looks like:

baseURL= "/" #important, you will change that
ageCode = "en-us"
title = "Your Hugo Site Title"
theme= "PaperMod" #the name of your desired theme, you have just downloaded it

Another way to download your desired theme is by:

cd <project name>
git init
git submodule add https://github.com/kaiiiz/hugo-theme-monochrome.git themes/hugo-theme-monochrome

HUGO Sample Sites

Try the sample site (if there is one in the repository). From personal experience, I would recommend to start by choosing a theme that has one of these sample sites, as you can start by adapting the initial look of the site that caught your attention in its demo.

cd ./your_project_name/themes/your_desired_theme/exampleSite
.\hugo server --themesDir ../..

Modify the HUGO Theme

Have you been tinkering already with the demo site? Add your own content!

Start by creating a post:

./hugo new posts/first.md

As you can see, HUGO supports markdown to write your site.

Make sure to read your theme documentation and set proper configuration for each post. In PaperMod theme, you can start by using:

title: ""
date: 2022-04-03T23:20:21+01:00
draft: false
tags: ["tag1","tag2"]  
description: ''
summary: ''
url: ''

Check that everything works locally. HUGO can open a development server that compiles modifies in real time the changes as you save them:

hugo server

You will see the changes getting applied on the go in: http://127.0.0.1:1313/

Generate your HUGO Site

Finally, generate the public files that you will deploy to your server

hugo

You will be able to check that the /public folder contains all the static files that form your website.

Got my HUGO site locally - What now?

At this point we have an awsome HUGO site. It would be a shame that the rest of the world cant enjoy what you have created.

For that matter, I will be writting how to deploy a HUGO site in the upcoming posts. I can tell you already that there are many ways to publish your site:

Deploying your HUGO Static Website for FREE

Totally Free: using Github Pages - you will get a subdomain and space
Free to some point: using Google Firebase, you get a subdomain and a free tier quota for usage and space
Self-Hosting: using hardware you already own

With any of this options, you can add your own domain to have your site, your way.

Adding Google Analytics to a HUGO Site

Iif you are lucky, in the config.yml file of your site, you will need to include the Google Analytics Tracking ID:

googleAnalytics: your-own-UA-or-G-trackingID

That means that the developer of the theme made the life easy for you.

Generally, you can search the theme’s head.tml - for example at: /layouts/partials/head.html

And add the GA script just above the end of

Same approach will work if you are interested to use Privacy Respectufull Web Analytics. Paste the given js before head ends.

Adding your Favicons

Just use The MindsDB Site and place in the the proper folder (where the default icons are on your HUGO Theme).

FAQ

How to Deploy HUGO with GH Pages

You will need to create: ./github/workflows folder.

And then include the following configuration, like: hugo.yml

# Sample workflow for building and deploying a Hugo site to GitHub Pages
name: Deploy Hugo site to Pages

on:
  # Runs on pushes targeting the default branch
  push:
    branches: ["main"]

  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:

# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
  contents: read
  pages: write
  id-token: write

# Allow one concurrent deployment
concurrency:
  group: "pages"
  cancel-in-progress: true

# Default to bash
defaults:
  run:
    shell: bash

jobs:
  # Build job
  build:
    runs-on: ubuntu-latest
    env:
      HUGO_VERSION: 0.108.0
    steps:
      - name: Install Hugo CLI
        run: |
          wget -O ${{ runner.temp }}/hugo.deb https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.deb \
          && sudo dpkg -i ${{ runner.temp }}/hugo.deb          
      - name: Install Dart Sass Embedded
        run: sudo snap install dart-sass-embedded
      - name: Checkout
        uses: actions/checkout@v3
        with:
          submodules: recursive
      - name: Setup Pages
        id: pages
        uses: actions/configure-pages@v2
      - name: Install Node.js dependencies
        run: "[[ -f package-lock.json || -f npm-shrinkwrap.json ]] && npm ci || true"
      - name: Build with Hugo
        env:
          # For maximum backward compatibility with Hugo modules
          HUGO_ENVIRONMENT: production
          HUGO_ENV: production
        run: |
          hugo \
            --minify \
            --baseURL "${{ steps.pages.outputs.base_url }}/"          
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v1
        with:
          path: ./public

  # Deployment job
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v1

What are HUGO Shortcodes?

Shortcodes in Hugo are simple snippets that you can use within your markdown files to execute more complex HTML, JavaScript, or other functionalities.

If you want to get ideas, the mentioned themes below are great source of inspiration:

Create a shortcode for opening links in a new tab

Create the Shortcode File

In your Hugo Theme Site directory, navigate to the layouts/shortcodes folder. If this folder doesn’t exist, create it.

Inside this folder, create a new file named newtab.html.

Add Shortcode Content:

Open newtab.html and add the following content:

<a href="{{ .Get "url" }}" target="_blank" rel="noopener noreferrer">{{ .Get "text" }}</a>
This shortcode creates an HTML link (<a> tag) with the target="_blank" attribute to open in a new tab. The rel="noopener noreferrer" is for security and performance reasons. The URL and link text are passed as parameters.

Use the Shortcode in Your Markdown:

In your markdown files, you can now use this shortcode like so:

The Uptime Kuma Site
The Uptime Kuma Source Code at Github
License: MIT ❤️

Replace your regular markdown links with these shortcode calls and you are done!

What is also great about shortcodes, is that you can take ideas from Other Hugo Themes and try to replicate their work in the one you want to use.

What are F/OSS alternatives to Google Analytics?

Matomo
Umami
Fantom (Lite) Analytics

What are F/OSS alternatives to Firebase?

Self-hosting your Static WebSite
Supabase
PocketBase

GIT 101 for SSG

git –version git config –global user.name “Your Name” git config –global user.email “you@example.com”

What do I need to have my HUGO Website?#

Getting Started: How to install HUGO#

In Windows#

In ubuntu#

Choose a Theme for your Project#

Hugo Themes I Love#

Using HUGO Themes#

How to Create a new HUGO site#

Downloading a HUGO Theme#

HUGO Sample Sites#

Modify the HUGO Theme#

Generate your HUGO Site#

Got my HUGO site locally - What now?#

Deploying your HUGO Static Website for FREE#

Adding Google Analytics to a HUGO Site#

Adding your Favicons#

FAQ#

How to Deploy HUGO with GH Pages#

What are HUGO Shortcodes?#

Create a shortcode for opening links in a new tab#

What are F/OSS alternatives to Google Analytics?#

What are F/OSS alternatives to Firebase?#

GIT 101 for SSG#