Hugo on Firebase Part 1

PUBLISHED ON APR 28, 2018

I’m really happy to finally have a great new blog that is cheap and that I have complete control over.

In the past I’ve used the Wordpress free tier, which was pretty good as a blogging platform but didn’t give me the granularity and frankly the web development practice that I was looking for. I’ve also used a Jekyll site on Github Pages which worked pretty well but the time it would take for my posts to go live was more than I liked, and Jekyll is a fine blogging platform but was a little confusing when you try to go into more granular code, not to mention you weren’t really sure what your blog page was going to look like until it was built and published.

Hugo was introduced to me by BrokenSpokeBloke and less than a couple days after he walked me through some of its basic features, nicacton.com is now up and running.

All that being said, there were a few initial hurdles that I had to get over and a lot of documentation that I had to read in order to really understand what was going on with my new Hugo blog and my Firebase hosting. Aravind Putrevu gives an admirable effort on his Medium post but I wanted to make sure people could get started with a full Hugo site on Firebase using a guide that was not as quick, far more detailed, and completely idiot-proof. Keep in mind, I’m a newbie at nearly all of this too so take what I’m saying with a grain of salt. I introduce, the “slow-start guide” to Hugo and Firebase.

Hugo

What is/isn’t Hugo?

I want to address a few things as to what Hugo is and isn’t before anyone decides to get started with it.

Hugo is a static-site development framework. What does that mean? Well, from what I can gather there’s a few things to consider:

  • Hugo is not your site. Hugo is a tool what you use to organize and build your site!
  • Hugo builds quickly. To be fair, I’m fairly new to the web development game so I don’t know what “slowly” looks like, but I’ve been using Hugo for a few days now and I don’t think it’s ever built my site in more than a half-second.
  • Because Hugo is open-source, anyone who understands what it’s doing can play with their site however they like. If you don’t like how Hugo built your site, you can even go into the HTML for a specific page and hard-encode your fixes, but it would probably be faster and better for you to fix it in the theme.

With all that in mind, lets get started on installing/using it.

Installation

If you have a mac, you’re in luck because installation is a snap with brew.

$ brew install hugo

# Verify your install works, you should see a similar output
$ hugo version
Hugo Static Site Generator v0.40.1 darwin/amd64 BuildDate: 

While this guide will be for Mac systems, Windows/Linux can likely follow along but you’ll need to follow this guide for installation.

Instead of the quickstart that Hugo offers, which I think only scratches the surface, lets go deeper.

New Site

You use the following command to start a new site:

$ hugo new site <project-name>

What just happened? All this command really does is make a new folder called <project-name> and and fills it with files and folders that will help you make the structure of your hugo site.

<project-name>
├── archetypes
│   └── default.md
├── config.toml
├── content
├── data
├── layouts
├── static
└── themes

Again, this is not your site. This is the framework Hugo uses to build your site.

Themes

The strength of the Hugo project is probably their themes. There are tons of themes available for you to use. For the purposes of this tutorial, we’ll randomly select Beautiful Hugo for this tutorial but hopefully you should be able to apply what you’ve learned to any theme.

If you have git tools installed, you can pull many themes directly from Github. These should be pulled into the themes folder:

$ cd <project-name>/themes
$ git clone https://github.com/halogenica/beautifulhugo.git beautifulhugo

There are several steps that the Hugo site recommends you take at this point, I recommend you skip all those steps and just do this. Inside most themes is an example site that will help get you started. First thing you should do is move or copy the config file from that site to act as a good basis.

$ mv themes/beautifulhugo/exampleSite/config.toml config.toml

The config.toml is effectively a nice collection of parameters to fill out that will build out your site.

baseurl = "https://username.github.io"
DefaultContentLanguage = "en"
#DefaultContentLanguage = "ja"
title = "Beautiful Hugo"
theme = "beautifulhugo"
metaDataFormat = "yaml"
pygmentsStyle = "trac"
pygmentsUseClasses = true
pygmentsCodeFences = true
pygmentsCodefencesGuessSyntax = true
#pygmentsUseClassic = true
#pygmentOptions = "linenos=inline"
#disqusShortname = "XXX"
#googleAnalytics = "XXX"
...

You can fill these in as you go, many are not incredibly important for future hosting, any that become important I’ll point out later.

If you’re more comfortable with HTML/CSS and want to make some hard-coded changes to the look and feel of your site, be sure to implement them in the files in the theme repository in the themes.

Pages/Posts

At this point, you’re really ready to start writing your blog. Luckily, hugo makes this really easy as well. Lets say in your theme there is a blog folder that your posts would go in. Making a new post in there is as easy as:

$ hugo new blog/<name-of-your-post>.md

This will create a new Markdown file in there.

Note: For those totally unfamiliar, Markdown is effectively a writing syntax that a lot of developers and design tools are using. A lot of tools have parsers which turn Markdown writing that is human read-able and understandable into HTML, which is read-able by a browser. You can learn about Markdown Syntax on this helpful Github Page.

From here, you can use your Markdown editor of choice to open up the markdown file you made and start writing a blog post. My personal favorite editor is Typora, a fairly obscure offering but one of the few that offers your Markdown in a WYSIWYG way.

At the top you may notice some lines like this

---
title: "Hugo on Firebase Part 1"
date: 2018-04-28T12:22:28-04:00
draft: true
---

These lines are read by Hugo when generating your website and are inserted when you use the previous Hugo command. You would replace each field with what you want: title with the name of the blog and date with the date and time it’s published. draft is a little more important for Hugo, which I’ll explain in a second. There’s a lot more than Hugo can do with this tiny little section, most of which can be read about here.

Hugo Server

Here is the interesting part. Inside the root folder of your blog, use the following command:

$ hugo server -D

You can then go to localhost:1313 in your browser and you should see your blog. But what does the -D mean? Well, as we saw in the previous section there was was a part in the header of the blog that said draft: true. Well that means that you’ve declared the blog post to be a draft and that it’s not necessarily ready for you to deploy to your blog. The -D tells this command to run in draft-mode. If you change the true to a false then Hugo will know that’s it’s ready to be built into a web-page for your fully deployed blog. At that point you can use the above command without the -D.

The other cool part about Hugo is that when you make changes to your page files and your theme html/css, and configurations then your small server will live-reload to your web server so you changes will be produced in near real-time!

Next Time

Get started working on your blog, next post I will detail how to prepare it for deployment for free using Firebase web-hosting!

comments powered by Disqus