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_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:
- Rename the .exe file to
- 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.exefile to this path:
- 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.
- 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
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:
(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:
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
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 newis the main command to tell Hugo that we want to create our new project directory.
siteis the sub-command of
hugo new, telling Hugo to build the core files.
cblwis 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:
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:
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.
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:
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:
.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
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
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:
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
And finally, we can populate the real core directory for our upcoming shrine. We only use one command to do this:
Let’s enter the
hugo command in our line and we should have this result:
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:
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
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!