Pre-Setup

Choose a Hugo theme

Hugo is a framework for building websites. You can pick an already created theme at https://themes.gohugo.io/ for your blog. There are examples and they include demos. The ones that are the most helpful have an example site you can see when it is downloaded, where they showcase how to configure their theme. Some of the themes will tell you how to install the theme to your Hugo project. I had difficulty with the first theme I used, the documentation was lacking and so was my knowledge on Hugo so I moved on to a different one with more documentation. I chose the Diary theme.

Create a Firebase account

Firebase is a free hosting service Google provides. You will need to enable Firebase on your Google account to be able to use the Firebase Tools to deploy your Hugo website. A Firebase account can be created from the Firebase Console.

Setup

Installing Scoop and Hugo

Scoop is a command line installer that can be used in Windows Powershell. We will use Scoop to install Hugo. There are other ones that can be used but I found this one to be the easiest and it looks like the most lightweight.

From the Windows Search Bar type Powershell and open it.
In Powershell, you have to change your execution policy to allow scripts to be run in it. We need this to install Scoop and again later when we try to run Hugo. To allow scripts run the following command:
```
Set-ExecutionPolicy RemoteSigned -scope CurrentUser
```
To install Scoop:
```
iwr -useb get.scoop.sh | iex
```
Now to install Hugo you use the command:
```
scoop install hugo
```

Installing npm and Firebase Tools

Npm (Node Package Manager) is needed to install the Firebase Tools. To get npm you need to install NodeJS.

With Powershell and Scoop we can install the NodeJS LTS (long term support) which also installs npm:
```
scoop install nodejs-lts
```
Now we can use npm to install Firebase Tools:
```
npm install -g firebase-tools
```

Creation

Create a new Hugo site

Create the folder where you want your website to exist.
We need to open Powershell at this folder. One way to do this is to open the new folder and go to File -> Open Windows Powershell.
Tell Hugo to initialize a new site for you, this will create the folder structure and required files:
```
hugo new site your-blog-name
```
Next change your directory to that folder so we can work from there:
```
cd /path/to/your-blog-name
```

Add your theme

To add the theme to your site project this can be done one of two ways:

From tThe theme’s main page on Hugo you can find specific steps for putting your theme into your site project. These generally include using git to install it as a submodule into the themes folder. To follow those instruction you can install Git using Scoop from Powershell with:

scoop install git

–OR–

Download the theme from the Hugo theme’s page and move it to your themes directory in your project. Later, before you deploy to Firebase make sure to remove any unnecessary files including things from the example site.

Configuration

Edit the configuration file

Opening the new site directory that Hugo created, you will see the config.toml file. If you open this file you will see some options, I will go over some of what I have for my theme but depending on the theme you choose there will be other options for your site:

baseURL = "https://your-blog.web.app" # the url provided by Firebase once that is chosen later
languageCode = "en-us" # the base language
title = "Your Blog" # The title of the blog
theme = "diary" # The name of the theme in your themes directory that will be used for your blog
copyright = "2021 Your Blog" # this adds a copyright section for my blog's theme
# googleAnalytics = "XXXXXXX" # replace Xs with google analytics code to see the stats of your blog

# Default markup settings for code snippets etc...
[markup]
    [markup.highlight]
    codeFences = true
    guessSyntax = false
    hl_Lines = ""
    lineNoStart = 1
    lineNos = false
    lineNumbersInTable = true
    noClasses = true
    style = "perldoc"
    tabWidth = 4

# Parameters used by theme
[params]
subtitle = "Your blog's subtitle"

# What can be used for each page that can allow it to be classified under
[taxonomies]
    category = "categories"

# Menu options for the theme
[[menu.main]]
url = "/categories" # Path to menu option, if these aren't taxonomies, then they are folder values or specific pages
name = "Categories" # Menu/Page title
weight = 1 # Menu priority from top

[[menu.main]]
url = "/posts"
name = "All Posts"
weight = 2

Your theme’s description page from https://themes.gohugo.io/ should explain the parameters to use in config.toml. If your theme came with an example site, there should be an example config.toml file that you can see to get an even better idea of how it works.

Running your blog locally

To test your configuration changes on your local machine in Powershell cd to your blogs root directory then run:
```
hugo server -w -D
```
- -w is to watch file changes on your system so changes can be reflected instantly on your site.
- -D is to build with the drafts of your page.
Using your preferred browser, go to http://localhost:1313/ to view your blog. After any changes hitting ctrl+s will save your file and refresh your blog in your browser automatically.

First blog post

Generate a new blog post

In Powershell, if you are still running your blog locally, hit ctrl+c to end it and then from your blog’s root directory run:
```
hugo new posts/name-of-your-blog-post.md
```
This will create a directory called posts and a markdown file that will be used to generate your post.
Opening the new markdown (md) file in your favorite editor to start your blog post.

Writing the post with markdown

At the top of the file you will find some Hugo parameters for the post such as title and date created. This could depend on your theme again and how they handle taxonomies. For example filling it out mine for the Diary theme it would look like:

---
title: "Your Blog Posts Title"                                      // Title for your post
description: "Your blog posts descriptions"                         // Description for your post
date: 2021-05-29T21:48:27-04:00                                     // Date your post was generated
categories: "A category for your blog"                              // A broad taxonomy used by the Diary theme to categorize your blog post, the theme only supports one, this is defined in the config.toml
tags: ["A tag for your blog post 1", "A tag for your blog post 2"]  // More specific taxonomy, used by the Diary theme to tag posts that contain a subject, supports multiple, this is defined in config.toml
featured_image: "/images/your_blog_post_image.jpg"                  // Used by the Diary theme to display an image found in that directory at the top of the post and a smaller version on the front page
draft: true                                                         // Denotes this article as a draft, change this to false for your post to be part of the deployed website
---

This tutorial will not go into any detail about writing in markdown. I found this guide which has a lot of basic usages for Hugo markdown.
You can test out how your posts look by running your site locally again and going to http://localhost:1313/posts/name-of-your-blog-post/.

Deployment

Choosing your blog’s URL address

Login to the Firebase Console and click Create a new Project.
From here you can create the name of your project. The name will be used as part of the website address. If it is not unique enough for Firebase it will add some random numbers to it. It should result in something like: https://your-blog-name-12345.web.app.
Continue the steps, Google Analytics is useful for information for tracking your popular pages on your site, I still had to set this up even though I had accepted these.

Initializing your blog with Firebase

Back in Powershell run:
```
firebase init
```
You will need to provide the following information:
1. For the "which features" question: go down to "Hosting: Configure and deploy Firebase hosting sites" select with space and hit enter.
2. For project setup select "Use an existing project" and click enter.
3. For "which public directory do you want to use", enter public (default should be public).
4. When it asks to "Configure single page app" select no.
5. When it asks about "Git push and deploy", I suggest saying no.hugo
This should generate some new files in your project necessary for uploading to Firebase including a .gitignore file which will be useful if you decide to put your website’s code on to GitHub.

Deploying your blog

First make sure all the blog pages you want to be deployed have draft set to false.
In config.toml change baseUrl to your chosen blog name:
```
baseURL = "https://your-blog.web.app"
```
This is important for links in website, otherwise they could get broken.
In Powershell at the root directory for the project run:
```
hugo
```
This creates a public folder and generates all of the necessary files like converting the markdown files to html. If you are planning on using Git make sure to include this folder in your .gitignore as it is just generated files.
Now run:
```
firebase deploy
```
The hosting URL is the URL to your website.

Author: Beam

Last modified on 2021-05-29