Preparation (Part 2) – Tool Prep: Hugo

I like to get everything that I need ready to go, which includes the tools and techniques that I plan to use for this site. Some people prefer working on the content first before they decide which tools and techniques they will be using when the site building begins. Others prefer working on the design layout first before they can even work with the content. I personally would like to have everything ready so I wouldn’t have to worry about it later.

Our main tools that would help us build this site are the following:

When I say that I want to have everything ready, this includes the download and installation of our copies of both software in our system, all ready to go. There may be a time where an update to both tools may be required in the long run while I’m working on the site’s content, and in that case, updating the current tools is quite easy.

I will be providing step-by-step instructions so you can all follow along. First, let’s start with setting up Hugo. But before I begin, I will assume the following:

  • You are a hobbyist web designer/developer looking for something new to incorporate with your site-building skills.
  • You have never heard of Hugo or just the words static site generator altogether.
  • You’re unfamiliar with Markdown and stuff like TOML, YAML, or JSON.
  • Like me, you are a Windows user. There are installation instructions for both Mac and Linux on the site’s excellent documentation.

I’m starting with the setup of Hugo first because it has quite a lot of steps that you may be unfamiliar with. This means that there are also a few things that you will need to get Hugo up and running on your system. We’re not touching our web server just yet, so don’t worry about how you’re going to upload a site built with Hugo.

If you are familiar with Jekyll or any other static site generator, Hugo is quite similar. But if you aren’t familiar with any of all that, then follow along.

#1 – Download Hugo

The first step is broken into small steps:

  • Head over to the Hugo website. You’ll see the shiny Download button there that will lead you to its GitHub repository.
  • Not familiar with GitHub? Keep following:
    • The GitHub link provided will lead you to its Code section of the repository. Scroll down and you will see the stable files available for you to download.
    • As of this writing, the latest stable version of Hugo is v. 0.15.
    • If you are a Windows user (like me), you will be looking for any one of the two zip files: hugo_0.15_windows_386_32-bit-only.zip and hugo_0.15_windows_amd64.zip. Download any one of the two files appropriate to your version of Windows. If you’re unsure which type of Windows your computer is using, do the following:
      • For Windows Vista – Windows 7: Start > right-click Computer > Properties
      • For Windows XP: Start > right-click My Computer > Properties
      • If you see x64 Edition listed in your Properties, then your Windows runs 64-bit. If not, your Windows is running 32-bit.
      • Windows 8 and above are both 64-bit.
    • If you are a Mac OSX user, you will have to open up your command line console and use Homebrew. More information at the Hugo documentation.
    • Save it somewhere on your hard drive where you can easily remember the location.

#2 – Install Hugo

  • Unzip the file you just downloaded from their GitHub repo.
  • Open the folder of the unzipped file and you will see three files: an executable file of some sort (.exe for Windows) that starts with hugo and two Markdown (.md) files: LICENSE.md and README.md.
  • Rename the .exe file to hugo.exe.
  • The Hugo documentation provides extra steps on creating some directory folders where you can store your Hugo-related files including the files that Hugo generates for you. Hugo relies a lot on your Windows PATH settings, so the files can go anywhere. Because I’m currently taking a Hugo class at Udemy, mine is a little different:
    • I like to name my directories per project name, rather than per tool with the project names as subdirectories of that particular tool. Therefore, I copied/pasted my hugo.exe file to this path: C:\WINDOWS\System32.
    • The beauty of Hugo is that you can place the .exe file anywhere within your system (C:\), as long as it’s easy for you to find it. Either way, your system will find that .exe file when you start executing it using the command line/console. I’ll cover this part very soon.
    • Mac OSX and Linux users have their own separate setup, so be sure to check the Hugo documentation carefully.

Congratulations! You now have Hugo installed in your system. You’re only going to do this step once. If you plan to have more than one site project in which you would like to use Hugo to build these sites, you won’t have to repeat these first two steps. Alright, let’s proceed!

#3 – Set up the CBLW site project folder with Hugo

This portion is screenshot-heavy, so please, do follow these instructions carefully. On this third step, you will need to open your command line (cmd) if you’re using Windows or your console if you are using Mac OS and Linux. For Windows 8/10, just search for it (or ask Cortana if you have Windows 10) and type in cmd (Command Prompt) to access the console.

I’m not very fond of the Windows default command line/cmd or its Power Shell, so I’ve downloaded a console emulator for Windows called CMDer to have a cleaner, easier screen (like Mac OS’s and Linux consoles). If you like, you can download CMDer from its official site.

When you first open your console, you should see something like this:

cmder1

(ignore the “sleeping anime girl” background. CMDer’s window is transparent. That’s actually my desktop wallpaper you’re seeing.)

Because I create my directories based on the project name, I store all of them on my external hard drive (G:). I’ve already got a directory for anything related to the series Card Captor Sakura, so I will be storing my Hugo-generated site in that folder. The console command to change directories is cd. To change your drives, just simply type the drive letter with the colon in it.

Be sure to check your Windows Explorer for your list of directories so you will know where to go when you change locations in your console. Here’s mine:

cmder2

According to the screenshot above, the console is now reading the files in the Card Captor Sakura folder.

Before we proceed any further. Let’s test to be sure that Hugo is working for us. To do that, type in hugo help and press the Enter key. If you get the results like the one at the code block below, Hugo is working properly and now ready to use.

hugo is the main command, used to build your Hugo site.

Hugo is a Fast and Flexible Static Site Generator
built with love by spf13 and friends in Go.

Complete documentation is available at http://gohugo.io/.

Usage:
hugo [flags]
hugo [command]

Available Commands:
server A high performance webserver
version Print the version number of Hugo
config Print the site configuration
check Check content in the source directory
benchmark Benchmark hugo by building a site a number of times.
convert Convert your content to different formats
new Create new content for your site
list Listing out various types of content
undraft Undraft changes the content's draft status from 'True' to 'False'
import Import your site from others.
gen A collection of several useful generators.

Flags:
-b, --baseURL="": hostname (and path) to the root, e.g. http://spf13.com/
-D, --buildDrafts[=false]: include content marked as draft
-F, --buildFuture[=false]: include content with publishdate in the future
--cacheDir="": filesystem path to cache directory. Defaults: $TMPDIR/hugo_cache/
--canonifyURLs[=false]: if true, all relative URLs will be canonicalized using baseURL
--config="": config file (default is path/config.yaml|json|toml)
-d, --destination="": filesystem path to write files to
--disableRSS[=false]: Do not build RSS files
--disableSitemap[=false]: Do not build Sitemap file
--editor="": edit new content with this editor, if provided
--ignoreCache[=false]: Ignores the cache directory for reading but still writes to it
--log[=false]: Enable Logging
--logFile="": Log File path (if set, logging enabled automatically)
--noTimes[=false]: Don't sync modification time of files
--pluralizeListTitles[=true]: Pluralize titles in lists using inflect
--preserveTaxonomyNames[=false]: Preserve taxonomy names as written ("Gérard Depardieu" vs "gerard-depardieu")
-s, --source="": filesystem path to read files relative from
--stepAnalysis[=false]: display memory and timing of different steps of the program
-t, --theme="": theme to use (located in /themes/THEMENAME/)
--uglyURLs[=false]: if true, use /filename.html instead of /filename/
-v, --verbose[=false]: verbose output
--verboseLog[=false]: verbose logging
-w, --watch[=false]: watch filesystem for changes and recreate as needed

Use "hugo [command] --help" for more information about a command.

In case you haven’t noticed yet, the text in the above code block is actually a list of basic commands that you can use with Hugo, so for your own reference, just copy/paste the above and save it somewhere as a text file.

I already created my project folder for CBLW (using a different name) on my external hard drive, but for the sake of this tutorial, I will be creating a new one (and then delete it later when I’m finished with this portion). So for the sake of this example, I will be creating my new project folder for CBLW. All of my contents and my other files such as images and graphics that I plan to use for the shrine will be stored in that folder. I will call this directory cblw.

In this case, I am not going to use Windows Explorer to create the cblw directory manually like what we normally do when we organize our files. Hugo will create the cblw directory for me instead.

Let’s look at that help code block above to see how we’re going to do it. At the last statement, we can also get help on any command by using that particular console command line. According to the help code block above, the command to create a new Hugo site project is new. Therefore, we are going to enter in hugo new --help for some helpful info on how we can use this command line.

The result should be the following:

Create a new content file and automatically set the date and title.
It will guess which kind of file to create based on the path provided.

You can also specify the kind with `-k KIND`.

If archetypes are provided in your theme or site, they will be used.

Usage:
  hugo new [path] [flags]
  hugo new [command]

Available Commands:
  site        Create a new site (skeleton)
  theme       Create a new theme

Flags:
  -f, --format="toml": frontmatter format
  -k, --kind="": Content type to create

Global Flags:
  -b, --baseURL="": hostname (and path) to the root, e.g. http://spf13.com/
  -D, --buildDrafts[=false]: include content marked as draft
  -F, --buildFuture[=false]: include content with publishdate in the future
      --cacheDir="": filesystem path to cache directory. Defaults: $TMPDIR/hugo_cache/
      --canonifyURLs[=false]: if true, all relative URLs will be canonicalized using baseURL
      --config="": config file (default is path/config.yaml|json|toml)
  -d, --destination="": filesystem path to write files to
      --disableRSS[=false]: Do not build RSS files
      --disableSitemap[=false]: Do not build Sitemap file
      --editor="": edit new content with this editor, if provided
      --ignoreCache[=false]: Ignores the cache directory for reading but still writes to it
      --log[=false]: Enable Logging
      --logFile="": Log File path (if set, logging enabled automatically)
      --pluralizeListTitles[=true]: Pluralize titles in lists using inflect
      --preserveTaxonomyNames[=false]: Preserve taxonomy names as written ("Gérard Depardieu" vs "gerard-depardieu")
  -s, --source="": filesystem path to read files relative from
      --stepAnalysis[=false]: display memory and timing of different steps of the program
  -t, --theme="": theme to use (located in /themes/THEMENAME/)
      --uglyURLs[=false]: if true, use /filename.html instead of /filename/
  -v, --verbose[=false]: verbose output
      --verboseLog[=false]: verbose logging

Use "hugo new [command] --help" for more information about a command.

According to the help code block above, there are two ways to build a new Hugo site project (see Usage) and that there are two available commands: site and theme. Because we don’t have a theme to use yet (will cover this one much later), right now we just want the files that we need to build the skeleton.

We will enter the command line hugo new site cblw. Let’s break the command down in a few parts to understand a bit more:

  • hugo new is the main command to tell Hugo that we want to create our new project directory.
  • site is the sub-command of hugo new, telling Hugo to build the core files.
  • cblw is the new directory name for our project name. All of the Hugo core files and all of our content files will all be stored there.

When you enter this command line, you shouldn’t get any other weird response, like the screenshot below:

cmder3

How do we know if the cblw directory is already there?

There are two ways to check. Since you’re already at your console, type the command ls to show all the contents of the current directory you’re in right now. This is the result that I got in this code block:

2014desktop.jpg                    sakura_syaoran_eyelid.jpg         stuff24.odt
Cardcaptor.Sakura.full.884285.jpg  sakura_syaoran_sleeping.jpg       stuff25.odt
Sakura_Syaoran_picture.jpg         sakura_syaoran_stuffedanimal.jpg  stuff25b.odt
Syaorans_sisters2.jpg              sakura_syaoran_touya.jpg          stuff26.odt
The Astral Towers.scriv/           sakura_syaoran_touyaavatar.jpg    stuff27.odt
The Empyrean Wars.scriv/           sampleprojects.scriv/             stuff3.odt
Thumbs.db                          stuff1.odt                        stuff4.odt
adri_blog_avvy.jpg                 stuff10.odt                       stuff5.odt
astral1.odt                        stuff11.odt                       stuff6.odt
astraltowers_prologue.odt          stuff12.odt                       stuff7.odt
card-captor-sakura-92515.jpg       stuff12b.odt                      stuff8.odt
cblw/                              stuff13.odt                       stuff9.odt
ccs1143873607605.jpg               stuff14.odt                       stuff_prologue.odt
desktop2013.jpg                    stuff15.odt                       stuffed animal.scriv/
desktop2013b.jpg                   stuff16.odt                       stuffedanimal_blogbanner.jpg
empyrean_previewprologue.odt       stuff16b.odt                      stuffedanimal_blogbanner.psd
epilogue.odt                       stuff17.odt                       stuffedanimal_blogbanner2.jpg
favicon.ico                        stuff17b.odt                      stuffedanimal_ffnetcover.jpg
ffnet_error.png                    stuff18.odt                       stuffedanimal_ffnetcover.psd
ffnet_error2.jpg                   stuff19.odt                       troop pegalion Backup.scriv/
kinoli shrine/                     stuff2.odt                        troop pegalion.scriv/
pegalion1.odt                      stuff20.odt                       trooppegalion_ffnetcover.jpg
pegalion2.odt                      stuff21.odt                       trooppegalion_ffnetcover.psd
pegalion_prologue.odt              stuff22.odt                       tumblr_m7bf7n6SAQ1qkkje7o1_400.jpg
sakura syaoran shrine/             stuff23.odt                       update_Feb032014.odt
sakura_syaoran_birthdaykiss.jpg    stuff23b.odt                      wp-monalisa_updateerror.png

I see it! It’s there at Line 12. (Yes, these are all the contents in my Card Captor Sakura directory. Those are images and my fanfic files, by the way…)

If you don’t trust your console (why ever not?), you can also check it using your Windows Explorer:

winexp_ccs

There it is, circled in red.

#4 – Check the contents of the CBLW directory to be sure that Hugo really did generate the core files there

It should. Go ahead and open the folder. You can use your console and enter your directory by using the cd [directory name here], or again, if you don’t trust your console, you can open your directory using Windows Explorer.

For the sake of those who fear the console’s black screen of death, I’ll go ahead and use Windows Explorer.

winexp_cblw

You should see five folders and one file, config.toml. Those five folders should be empty, but the most important at this point is that you have the config.toml in there.

Let’s check out what’s inside!

#5 – Open and set up the config.toml file

We have just opened the heart and soul of Hugo. Here, we will do some basic configuration for our site with config.toml. Open the file using your favorite text editor or IDE (I use Brackets). You should see the following below:

configtoml

There is actually a whole lot more to configuring this file than what you see right now. Static site generators call these top few lines as the front matter. Hugo supports three file formats for its front matter.toml, .yaml, and the (slightly?) more popular .json. Hugo’s default front matter is .toml (Tom’s Obvious Minimal Language), but if you’re familiar with other static site generators, namely Jekyll, you can use .yaml (YAML Ain’t Markup Language). If you’re some kind of a Javascript master, there’s .json (Javascript Object Notation).

If you want to give yourself a head start instead of waiting (impatiently) for me, you can check out Hugo’s front matter documentation for more information and the front matter formats Hugo supports. But, I’m more familiar with Hugo’s defaults, and just to make things a lot easier, I’m using the default .toml instead.

I’ll cover more of Hugo’s front matter in a much later time when I finally get all my contents and my layout wireframe all planned out and ready to go, but for the time being, let’s plug in the default parameters with our own custom info, like so:

configtoml2

Finally, we are now going to the final step for this tool prep!

#6 – Populate the real core directory!

Here we are, the final step! And yes, we go back to the evil command line console once again. But this is very simple now. Before you get to this step, be sure you configure your front matter file first, or otherwise, you’ll be getting a lot of errors if you skip that particular step.

First, let’s get inside our new directory folder. In this case, the cblw folder, using the cd command.

cmder4

And finally, we can populate the real core directory for our upcoming shrine. We only use one command to do this: hugo.

Let’s enter the hugo command in our line and we should have this result:

cmder5

Sure, the results may not mean anything to you (yet), but when you do check the contents of your directory again (using the ls command or Windows Explorer), you’ll see something new there:

winexp_cblw2

We get a sixth empty folder: public. While we build our site using Hugo’s core files, Hugo will automatically generate all the results from our building to the public folder. We add our own files using the other folders except for the public folder. Once we are all finished and ready to upload our site to our web server, we will be uploading all the generated files from the public folder.

Next…?

On the next part of our Prep series of this LBP, we will begin building our design layout using Materialize. But for this, I want to have all of my content ready to go so I would finally have an idea on how the CBLW shrine is going to look like. If I fail to build a good custom theme using Materialize, Hugo has been generous by providing us amateurs with a collection of starter themes. The best thing about it is that many of these starter themes were built using Materialize.

I will let you know when I’m ready, so for the time being, thank you for joining and I hope you enjoy this portion of my first LBP. Come back soon!