Create a FREE Blog - Websites with HUGO

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.

Don’t keep reading if you are not interested in:

• Discover the power of HUGO as an open-source tool for building dynamic websites
  • 🔍 A way to avoid blogging platform lock-in
  • 🌐 HUGO pages can replace Medium, Blogger, etc.
  • 🆓 Having a FREE page publicly available Website with a free domain.
• Being the owner of your own website data
  • 📝 Step-by-step guide to creating your first HUGO website almost from scratch.
  • 🎨 Explore different HUGO themes and customize them to suit your style and preferences.

The HUGO Project

• HUGO is an exciting open-source project, offering a powerful toolset for building static websites with speed:
  • Explore the HUGO Site to learn more about its features and capabilities.
  • Access the Hugo Source Code on Github to delve into its inner workings and contribute to its development.
    • License: Apache v2 ✅
  • Wait, static websites? Yes, you’ll love:
    • Lightning-fast performance: ⚡️ HUGO generates static websites quickly, resulting in speedy load times for visitors.
    • Flexible content management: 🧩 Easily manage your content, with HUGO you can write in markdown.
    • Extensive theme library for customization: 🎨 Choose from a wide range of themes to customize the look and feel of your website to suit your needs.

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

What do I need to have my HUGO Website?

1. Don’t worry about coding: Even if you’re not a web developer, don’t be intimidated by the code. Just be patient and take it one step at a time. Start by:

   • Choosing a Hugo theme that you like from Hugo Themes.

2. Install Hugo on your laptop.

3. Decide where your website will live – also known as where to host (deploy) it. Don’t worry, you can also get started for free with free tiers:

   • Firebase
   • Cloudflare Pages
   • GitHub Page
   • If they stop being generous, you can always self-host HUGO with an nginx server. This option gives you full control and is a great choice for those who prefer open-source solutions and be totally in control.

4. Your domain: Choose whether to get your own domain or use a free one.

   • For starters, you can use the free subdomains that Firebase/Cloudflare Pages/Github Pages will give you
   • (Optional): You can buy a domain from various providers such as Cloudflare, Porkbun, GoDaddy, NameCheap, etc. Remember, you can always migrate it later on.

How to install HUGO

HUGO In Windows

Simply download the latest version from their repository:

• HUGO releases on Github
• Code in a folder where the hugo.exe is available

HUGO 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:

wget https://go.dev/dl/go1.22.5.linux-arm64.tar.gz
sudo tar -C /usr/local -xzf go1.22.5.linux-arm64.tar.gz
export PATH=$PATH:/usr/local/go/bin
source ~/.bashrc
go version

apt-get update -y

#https://github.com/gohugoio/hugo/releases 
#choose and adapt the link below to the desired version

#example v0.87
#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

#example v0.108 (Selected architecture x86 - make sure to select the one that works for you!)
wget https://github.com/gohugoio/hugo/releases/tag/v0.108.0/hugo_extended_0.108.0_linux-amd64.deb -O hugo_latest.deb

sudo dpkg -i hugo_latest.deb
#sudo gdebi hugo_latest.deb #also with deps
#apt-get install -f #if dependency errors

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

Check the installed HUGO version with:

hugo version 

git clone https://github.com/gohugoio/hugo.git
cd hugo
go install

Choosing a HUGO Theme

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 Hugo Themes:
  • HUGO Themes
  • HUGO Themes at JAMStack

Try to use the ones with a F/OSS License, like MIT 📢

Hugo Themes I Love

Websites with HUGO 101

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

If 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 </head>

Same approach will work if you are interested to use Privacy Respectufull Web Analytics.

Paste the given js before head ends.

And remember the Google Analytics is a black box and there are better alternatives

Adding your Favicons

Just use Real Fav Icon Generator 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, for example: 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:

• HUGO Congo
• HUGO Hextra

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

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.

Remember - Shortcodes are designed for use in Markdown content files, not in template files.

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

While creating your HUGO website, you might come across this minor blockers:

  git --version
  git config --global user.name "Your Name"
  git config --global user.email "[email protected]"

git add .gitignore
git commit -m "Update .gitignore to exclude /public"

git rm -r --cached public/
git commit -m "Remove /public from tracking"