Real Hugo Quickstart Guide for the Novice

When I started my road down Hugo, I was quite frustrated - the Hugo guides were difficult to follow and left out lots of details (basic facts, really) that a novice user would need to know. I mean, their Quickstart guide starts with macOS and the Install page is quite a mess. I’m not an expert on Hugo - rather this is me trying to document my findings and hopefully help someone out. So, here’s a real Hugo Quickstart Guide for the Novice.

My assumptions:

• You’re running Windows 10
• You have already acquired your own hosting (UW Students - it’s $2 / term at CS Club!)
• You have a nice text editor - eg. Notepad++.

What can Hugo (that executable residing on your computer) do?

1. Generating a framework for you to fill for your static site
2. Creating blank template posts that you can edit with your text editor
3. Starting a ‘preview server’ of sorts, so you can build the current version before sending it live
4. ‘Publishing’ your website - this creates a fully published version ready to upload

The other expecations you should have:

• Your posts will not be in a WYSIWYG (not Word), but will rather be written in a formatting language called Markdown. If you use Reddit you’ll already be halfway there! You will use your nice text editor to edit your posts and insert pictures.
• You will most likely use an FTP client such as WinSCP to upload your site afer it’s published through Hugo.
• You will also learn some very, very basic use of PowerShell to navigate directories.

Getting Hugo ready to go!

1. Set up the folder you want Hugo to be located. E.g. If you want it to reside in C:\Hugo, then also set up C:\Hugo\bin and C:\Hugo\Sites. For the purposes of this guide, I will assume your directory is C:\Hugo

2. Download Hugo from here. At the bottom of the first post will be both the 32-bit and 64-bit Windows versions in a .zip file. If you’re not sure if you have 32 or 64-bit, consult this guide.

3. Extract the contents of the .zip you downloaded to the \bin folder (eg. C:\Hugo\bin) such that the contents of the \bin folder are hugo.exe, LICENSE.md and README.md.

4. You can delete the original .zip file now.

5. Next, we set up Hugo so it can be accessed from Windows PowerShell - follow the instructions here. But these steps are a bit confusing even though I did it on two Windows 10 laptops at the same time so here’s some notes:

   • You may not find ‘Advanced System Settings’ on the left as indicated, use the search bar instead.
   • PATH is not in all caps, double left-click ‘Path’ anyway.
   • On some versions of Windows 10, double left click on Path will show a box titled ‘Edit User Variable’ where all the fields already have a value. In the ‘Variable Value’ box, add your \bin folder to the end, separated by a semi-colon (e.g. %USERPROFILE%\AppData\Local\Microsoft\WindowsApps was already in the box, the end result would be %USERPROFILE%\AppData\Local\Microsoft\WindowsApps;C:\Hugo\bin;).
   • In most other cases, everything will be displayed as a table, and you can click on the next blank row and type the directory (e.g. C:\Hugo\bin) directory you want to add.

Building a new Hugo Website

1. In Windows Explorer, navigate to C:\Hugo\Sites.

2. SHIFT + right click to open up a context menu, select ‘Open PowerShell window here’ or ‘Open command window here’ depending on which version of Windows you use.

3. Type Hugo new site test.com and hit Enter.

4. If it says ‘Congratulations! […]’ then you’ve done it right! In Windows Explorer, you will note that test.com has been added as a folder with the framework of a Hugo site built within.

5. Download a Theme. Beware that some themes are intended for blogs, and others for creating personal single page profiles. You can try the Red Lounge theme, which is the only one I got working easily out of the box. To download, go to the theme page, click Download, then on the GitHub page, hit Clone or download, then Download ZIP

6. Save the theme to test.com\themes and rename the folder to a simple name (e.g. Travelify). ensure that the next directory contains all the subfolders (i.e. test.com\themes\Travelify\archetypes).

7. Next, you should read the README.md that accompanies the theme you chose, so you can configure it correctly. The Red Lounge theme will ask you to add a number of fields to your config.toml saved directly in your test.com folder. Go ahead and add it to your config.toml, and also adding an image to \static\img (you will have to create the \img directory).

   [params]
   	sidebartitle = "Test.com"
   	sidebartagline = "Is super awesome"
   	sidebarphoto = "/img/photo.png"
   

8. Navigate to \test.com by typing cd test.com (There’s a quick primer on Command Line / Powershell a the bottom of this article!).

9. Add a new post by typing hugo new posts\my-first-post.md. This creates a .md markdown file as so: C:\Hugo\Sites\posts\my-first-post.md. Note that my-first-post.md is organized within the posts category.

10. You can now edit the new .md file, by opening it up in your favourite text editor. The area within the ++++ contains information and attributes that Hugo uses when it builds your site. Feel free to edit the title line (keeping everything within " double apostrophes). The content of your post goes underneath. For now, let’s use the following snippet of code below and paste it after the +++++

    # This is my first post.
    Hello World! Click [here](https://github.com/adam-p/markdown-here) to see some tips on using Markdown to **format** *your* posts!
    

11. You’re ready to see your first site come to life (as a preview). Back in your Command line / PowerShell, navigate to \test.com and type Hugo server -D, it will allow you to preview your website at http://localhost:1313 in your web browser.

12. Open up the .md post in your favourite text editor again, and add the following to the bottom of your post, then save it.

    I'm learning so ~~so~~ much!
         
    ![Example Image of Hummingbirds](http://www.gettyimages.ca/gi-resources/images/Homepage/Hero/UK/CMS_Creative_164657191_Kingfisher.jpg)
    

13. Return to http://localhost:1313 and you’ll see that the page has already been updated the moment you saved your newly updated .md file! Hugo builds as you write save!

14. I almost ended the guide here, but it’s time to publish your filler site! Press CTRL+C while in the PowerShell / command line window to stop the preview server, and then type hugo. Hugo will generate your new site into \public which you can then go and copy all the files into your live site, being sure to clear the target directory first!

15. And now, you’re well on the way to building your own website. Go explore some more themes and go through the README.md of the theme you’re using. :)

Quick Primer on Navigation Through Command Line / PowerShell

• dir (e.g. directory) lists the contents of the current folder you’re in.
• cd (e.g. change directory) allows you to change the directory you’re in
  • cd .. allows you to go up one level (e.g. from C:\Hugo\bin to C:\Hugo).
  • While typing the name of a target, you can hit TAB and it will autofill the rest of the name. (e.g. If you’re in C:\Hugo and you type cd Si then hit TAB, it will now read cd Sites