Set up a Hugo website with Firebase hosting

When I was looking for alternatives for static website generators and hosting services for the first time, I came across Hugo and Firebase. I had no idea for either of two but I decided to try them out. After many trials, errors, and Googling, I kind of learned my way around Hugo, and Firebase hosting was simple enough. In case I need to go through the same process for another website after a while, I wanted to take notes and explain the process (mainly to myself), though some parts will be brief and others will be more detailed.

Get the trivial stuff done first

These are the steps that should be self-explanatory or easier to figure out, so I’m keeping them pretty short.

Create a Firebase account if you don’t have one

This is obviously needed, so go on and create a Firebase account.

Create a project in Firebase

Log in to Firebase, click the “Add project” button, name your project, select your preference on activating Google Analytics on your project (website), do the things, and have your project created.

Install Firebase tools

To deploy the website, we will need to use Firebase CLI. There is more than one way to do it. I prefer to install it via npm, but it doesn’t matter, the point is to be able to use the firebase command in the terminal. Assuming you have npm installed, you can use the following command to install Firebase CLI via npm:

npm install -g firebase-tools

Then you can check if it’s installed by using firebase or simply firebase --version.

Install Hugo

Hugo is the static site generator I chose to use. Again, there are several ways to install it depending on your preference and operating system, but the point is to be able to actually use it through the hugo command. In my case, I installed Hugo with brew:

brew install hugo

Then you can check if it’s installed by using hugo version.

Creating the website

With the trivials out of the way, we can begin building the website and putting content. To create a website from scratch, go to your desired directory and run the following Hugo command:

hugo new site my-website

This will create a folder named my-website and inside that folder, you will find:

ibrahim.akalin @ my-website % ls -la
total 8
drwxr-xr-x  11 ibrahim.akalin  wheel  352 Jan 2 20:09 .
drwxr-xr-x   3 ibrahim.akalin  wheel   96 Jan 2 20:09 ..
drwxr-xr-x   3 ibrahim.akalin  wheel   96 Jan 2 20:09 archetypes
drwxr-xr-x   2 ibrahim.akalin  wheel   64 Jan 2 20:09 assets
drwxr-xr-x   2 ibrahim.akalin  wheel   64 Jan 2 20:09 content
drwxr-xr-x   2 ibrahim.akalin  wheel   64 Jan 2 20:09 data
-rw-r--r--   1 ibrahim.akalin  wheel   83 Jan 2 20:09 hugo.toml
drwxr-xr-x   2 ibrahim.akalin  wheel   64 Jan 2 20:09 i18n
drwxr-xr-x   2 ibrahim.akalin  wheel   64 Jan 2 20:09 layouts
drwxr-xr-x   2 ibrahim.akalin  wheel   64 Jan 2 20:09 static
drwxr-xr-x   2 ibrahim.akalin  wheel   64 Jan 2 20:09 themes

If you intend to use Hugo for a long time, it’s good practice to learn what each of these folders are for and how they are used. However, I’ll only shortly explain content, layouts, static, and themes.

content is the folder we will put pages into. The main page, posts, and other pages will be put in this folder.

layouts is the folder we will put page templates into. These templates consist of html files and they are the skeletons of the pages of the website. Along with css files, they will determine how the pages look.

static is the folder we will put various files that will be used on the website. These usually include files like images, fonts, js, css, etc.

themes is the folder where we will put the themes that will be used in the website. It’s possible to put more than one theme in here. Themes are the essential components to customize the look of the website but parts of the theme can be overwritten by the templates inside the layouts folder.

Config file

Notice that we also have a file called hugo.toml. After freshly creating a new site, this file looks like:

baseURL = 'https://example.org/'
languageCode = 'en-us'
title = 'My New Hugo Site'

I prefer YAML over TOML which Hugo also supports. So I deleted the hugo.toml file and created a new configuration file called config.yaml. Ultimately they are the same, it’s just a matter of preference. config.yaml will look like this:

baseURL: 'https://example.org/'
languageCode: 'en-us'
title: 'My New Hugo Site'

Later on, this file will be used to configure things like themes, site menu, markup, etc.

More on themes

First off, there are many themes available out there for Hugo. Hugo is by no means poor of themes, you can always check them out and decide to use one of them. You can visit Hugo Themes page to see what themes are available.

There are different paths to follow here. The one you will choose to go for will depend on your expertise on Hugo, requirements, and preferences.

Theme creators usually prefer to keep their themes in GitHub and it’s a popular method to add these themes to your website as submodules. To do this, you need to first initialize a git repository for your website. Then you can use git submodule add command to add the theme from GitHub. In the my-website folder, run the following:
```
git init
git submodule add <theme_repo_url> themes/<theme_name>
```
This way, you can easily import a theme and pull the updates to it as well. The theme can also be a theme created and maintained by you. Adding the theme as a submodule is a good option if you want to keep the maintenance of the website and the theme separate.
You may want to not use submodules and maintain the website and the theme altogether (or not get updates from GitHub). In this case you can just download the theme, remove the git related stuff like the .git folder or .gitignore file, copy it into themes folder and use it.
If you are in it for the long term, it’s worth developing your themes from scratch, although there will be some learning curve if you are not familiar with front-end development.

The actual website

All the Hugo themes I saw so far come with example websites. At this point, I suggest copying the example website into your root folder, which is my-website. This will probably overwrite folders like content, layouts, and also your config file. From there, you can add/remove/modify whatever you want and start adding content.

Along with the example website’s files, you will copy its config file too. You should take a look at it and customize it according to your needs.

For pages and posts, your Markdown files will have some metadata at the beginning of the file. You can set the info for the post (title, author, date, tags, categories, if it’s a draft or not, etc.) in that part. You can look at some examples to have an idea about how that works.

Generating and deploying the website

Now, let’s run Hugo and generate the prototype website at hand to see if everything is fine. Hugo can run a web server that supports live reloading so that you can see the changes in real-time without needing to refresh the pages. To run the web server, run the following command:

hugo server

This will run the Hugo server, it’s reachable at http://localhost:1313 by default and binds to 127.0.0.1. You can see a lot of options if you run hugo server help, there are some useful ones. For example, if you want to reach the website from another device in the same network, you may want to set the bind address to 0.0.0.0 so that the web server listens on all the network interfaces ¹.

I usually use the following command when I’m making changes to the website:

hugo server -D --disableFastRender --ignoreCache --noHTTPCache --bind=0.0.0.0

Deployment

We have Firebase tools installed but we haven’t initialized it yet. In the root folder of the website, run the following:

firebase init

After that, it’s pretty straightforward. You need to log in to your Firebase account, select the service (which is hosting in our case), and select the project you want to use. When Firebase asks for the public folder, go with the default one, which is public (Hugo also generates site files into the public folder).

After setting up Firebase, we need to just run hugo to generate the website and firebase deploy to upload site files to Firebase. You can just run both commands in a single line:

hugo && firebase deploy

Website on the web

If you go to your Firebase account, check out your project, and visit the hosting page, you should see some links under domains. You can visit those links from anywhere to see your published website.

Important: If you have a domain and want to use it, you need to add it to your Firebase project. You can click the “Add custom domain” button under domains and follow the instructions. You will need to add some DNS records for your domain using your registrar and your website will be ready under your domain.

Possible issues

If you haven’t worked on any of your Firebase projects, you’ll be logged out. Later on, you may run into issues while initializing a new Firebase project or deployment of a current one. It’s possible that you get an error saying “Please make sure the project exists and your account has permission to access it”. In that case, use firebase login --reauth to reauthenticate and then proceed as usual.

Conclusion

I tried to explain the most basic stuff to have a simple Hugo website up and running. I also wanted it to be useful as a note if I want to set up another static website after a long break. Hope you will find it useful.

There is much more to it with Hugo and Firebase. The more functionality and customization you want, the more you need to go through documentation and Googling.

Note that you may not be able to bind to 0.0.0.0 if you don’t have permissions to do so. ↩︎