Building Your Hugo Site Locally (PART 2)
…continued from https://atomic-temporary-5081318.wpcomstaging.com/2020/12/22/getting-started-with-hugo-part-1/ which is part of the series summarized at https://atomic-temporary-5081318.wpcomstaging.com/2020/12/21/building-a-hugo-web-site-hosting-on-google-cloud-win-10-the-big-steps/
Now that you have Hugo set up on your machine, it’s in the Windows PATH, and you’ve verified it by checking hugo version, it’s time to build your first web site on localhost (your own machine).
Step 1 – Open git bash and go to your Hugo directory (for me, cd /d/Hugo).
Step 2 – Let’s pull down a theme from https://themes.gohugo.io/vanilla-bootstrap-hugo-theme/ and look at its exampleSite it provides. The theme we will work with is Vanilla Bootstrap, because this is the one that datalorax initially inspired me with. Go to that URL, and the next few steps will (sort of) mirror steps you see there.
Step 3 – Create a new space for a hugo site. We will call it mytestsite:
hugo new site mytestsiteStep 4 – That creates a new directory under your Hugo directory called mytestsite. Switch into it, do a git init, and then pull the theme into your new hugo site directory like this:
cd mytestsite
git init
git submodule add https://github.com/zwbetz-gh/vanilla-bootstrap-hugo-theme.git themes/vanilla-bootstrap-hugo-themeThis is going to create a whole new subdirectory structure. For me it looks like this: /d/Hugo/mytestsite/themes/vanilla-bootstrap-hugo-theme/
Step 5 – Switch into the home directory of the exampleSite and edit config.yaml with your favorite text editor. I use nano. You want to change the baseURL to say http://localhost:1313. Save config.yaml when you’re done.
cd /d/Hugo/mytestsite/themes/vanilla-bootstrap-hugo-theme/exampleSite
$ cat config.yaml
baseURL: https://example.com
languageCode: en-us
title: Vanilla
theme: vanilla-bootstrap-hugo-theme
googleAnalytics: UA-123456789-1
...more stuff...Step 6 – Now go into the theme itself and add draft: false to tell it that none of the pages should be thought of as a “draft” – and thus be invisible when you build your first site. If you forget this step, building the Hugo site will produce a lovely single HTML page with only opening and closing PRE tags.
cd /d/Hugo/mytestsite/themes/vanilla-bootstrap-hugo-theme/archetypes
$ cat /d/Hugo/mytestsite/themes/vanilla-bootstrap-hugo-theme/archetypes/default.md
---
title: "{{ replace .Name "-" " " | title }}"
date: {{ .Date }}
draft: false
---
Step 7 – Now it’s time to go back to the exampleSite directory, make one tiny more change to a file! and build your exampleSite. The change to make is to edit _index.md so that you see draft: false for the same reason as in Step 6:
cd ../exampleSite
$ cat _index.md
---
title: Home
draft: true
# CHANGE THIS TO FALSE!! then re-save the _index.md file
---
Homepage content goes here.
Now you’re ready to build:
$ hugo server --themesDir ../..
Start building sites …
| EN
-------------------+-----
Pages | 57
Paginator pages | 0
Non-page files | 3
Static files | 5
Processed images | 3
Aliases | 0
Sitemaps | 1
Cleaned | 0
Built in 43 ms
Watching for changes in D:\Hugo\mytestsite\themes\vanilla-bootstrap-hugo-theme\{archetypes,exampleSite,layouts,static}
Watching for config changes in D:\Hugo\mytestsite\themes\vanilla-bootstrap-hugo-theme\exampleSite\config.yaml
Environment: "development"
Serving pages from memory
Running in Fast Render Mode. For full rebuilds on change: hugo server --disableFastRender
Web Server is available at http://localhost:1313/ (bind address 127.0.0.1)
Press Ctrl+C to stop
Step 8 – Now, pull up a browser and point it to http://localhost:1313 and you’ll see what you just created!
Step 8 – Now it’s time to build your OWN site. (You can see at this point why I was dismayed… there is not enough instant gratification in setting up the exampleSite. Also, because of documentation issues, it took about a day to get it to work.) It’s your turn to have an easier time than I did. Let’s use the Set up your own new web site using the Showcase theme (which I selected because it looked simple and… what could possibly go wrong with that one? hahaha). First we need to launch their exampleSite, just like for the other theme:
cd /d/Hugo
hugo new site myrealsite
cd myrealsite
git init
git submodule add https://github.com/apvarun/showcase-hugo-theme.git themes/showcaseThis will create a complete directory structure for you:
$ ls -sapl
total 14
4 drwxr-xr-x 1 User 197121 0 Dec 23 08:04 ./
4 drwxr-xr-x 1 User 197121 0 Dec 23 08:04 ../
4 drwxr-xr-x 1 User 197121 0 Dec 23 08:04 .git/
1 -rw-r--r-- 1 User 197121 112 Dec 23 08:04 .gitmodules
0 drwxr-xr-x 1 User 197121 0 Dec 23 08:04 archetypes/
1 -rw-r--r-- 1 User 197121 82 Dec 23 08:04 config.toml
0 drwxr-xr-x 1 User 197121 0 Dec 23 08:04 content/
0 drwxr-xr-x 1 User 197121 0 Dec 23 08:04 data/
0 drwxr-xr-x 1 User 197121 0 Dec 23 08:04 layouts/
0 drwxr-xr-x 1 User 197121 0 Dec 23 08:04 static/
0 drwxr-xr-x 1 User 197121 0 Dec 23 08:04 themes/
Here’s where many of the docs say “just hugo server -D and then see your site in the browser and localhost!!” and it is a lie. This lie is probably due to a new Hugo learner reading the docs incorrectly, but the experts are not aware that we will naturally do that because we don’t have the directory and file structure memorized yet. All you can see right now is the theme designer’s exampleSite, and only if you do exactly the following while you are sitting in /d/Hugo/myrealsite:
cd themes/showcase/exampleSite/
hugo server --themesDir ../..Now open a browser and point it to http://localhost:1313 for some (almost) instant gratification.
Step 9 – Now let’s edit your site… cd /d/Hugo/myrealsite again. It’s time to make that showcase theme your own! (Don’t try to just hugo server when you’re sitting in /d/Hugo/myrealsite… it won’t work. You’ll get the blank page with PRE tags.) Let’s make some changes, too, for educational reasons: 1) Instead of 4 blocks on the main screen, let’s do 6… 2) let’s put in your own images and words over the images, then 3) let’s either add a custom message or remove useless whitespace, and 4) let’s make the social media icons in the bottom right bigger, so old people like me can see them.
It’s time to switch the baseURL on config.toml – but what they don’t tell you is that THIS IS THE WRONG config.toml. (They say “copy the file to your root directory” – what file? What’s my root? You get the picture.) You have to go retrieve the one in exampleSite and edit THAT one if you want ANY OBJECT AT ALL to show on your web page. (Again, this makes sense after you’ve been immersed in Hugo for a while, but did not make sense at first.) Do this:
rm config.toml
cp themes/showcase/exampleSite/config.toml ./Step 10 – Now edit the real config.toml file with your favorite text editor. I use nano. You want to change the baseURL to say http://localhost:1313. Save config.toml when you’re done. (Some themes have toml files, and some have yaml files. Both provide site configuration. The choice of which one seems to be up to the theme designer.)
baseURL = "https://example.com"
# Make this http://localhost:1313 for now
languageCode = "en-us"
title = "Showcase Theme"
Paginate = 1000
googleAnalytics = ""
theme = "showcase"
disableKinds = ["taxonomy", "taxonomyTerm", "RSS"]
[params]
author = "showcase"
# This becomes the text in UPPER & LOWER LEFT of web page
description = "Minimal, one page, theme for showcasing your work"
message = ""
# This will be printed right above your six image blocks
hideAutoMenu = false
# Don't change this or your entire menu in upper right will vanish
[[menu.main]]
name = "External"
# This becomes the MENU OPTION at the FARTHEST top right of page
url = "https://example.com"
# This is the URL that the menu option above will link to
[social]
facebook = "https://facebook.com"
# Change these URLs to your personal social pages
twitter = "https://twitter.com"
# You can delete, but not add...
instagram = "https://instagram.com"
# I tried adding "github" but then found out later
linkedin = "https://linkedin.com"
# only these 4 options are hardcoded into the theme :(The only changes I’ll make are baseURL to localhost, author to my blog’s name, and message to a secret message you’ll see later.
Step 11 – cd into /d/Hugo/myrealsite/archetypes and edit default.md exactly like you did in Step 7 above. That way, it won’t automatically think every new page you create is supposed to be hidden.
Step 12 – Now you should be able to see your (very minimalist) site. Get back into the root directory with cd /d/Hugo/myrealsite and type hugo server, then pop open a browser and go to http://localhost:1313. Voila! Sort of!
Step 13 – If you want to put blocks of images on the page (but of course!), you’ll need to copy over some more files from inside the themes directory that are not attached to exampleSite:
rm -rf layouts
cp -r themes/showcase/layouts/ layoutsNow you’ve got the skeleton for a web site in your /d/Hugo/myrealsite. Here’s where you need to know what all the pieces in /layouts mean:
$ ls -sapl
total 12
0 drwxr-xr-x 1 User 197121 0 Dec 23 08:52 ./
4 drwxr-xr-x 1 User 197121 0 Dec 23 08:52 ../
# "template file which matches Hugo
0 drwxr-xr-x 1 User 197121 0 Dec 23 08:52 _default/
# <-- Layouts Lookup Rules" go here
4 -rw-r--r-- 1 User 197121 1140 Dec 23 08:52 404.html
# You need this to deploy to GCS
4 -rw-r--r-- 1 User 197121 1673 Dec 23 08:52 index.html
# The actual HTML for your main page
0 drwxr-xr-x 1 User 197121 0 Dec 23 08:52 partials/
# header, footer, logo, custom messageYou realize that all these files are important when you try to build a site using hugo server without them. You get messages like:
Start building sites …
WARN 2020/12/23 08:59:25 found no layout file for "HTML" for kind "section": You should create a template file which matches Hugo Layouts Lookup Rules for this combination.
WARN 2020/12/23 08:59:25 found no layout file for "HTML" for kind "section": You should create a template file which matches Hugo Layouts Lookup Rules for this combination.
WARN 2020/12/23 08:59:25 found no layout file for "HTML" for kind "section": You should create a template file which matches Hugo Layouts Lookup Rules for this combination.
If you see ANY of these errors, they are telling you to go find new files and put them into /layouts/_default — but you won’t find those magical files in the theme anywhere. Here are the links to example files from https://github.com/gohugoio/hugo/issues/6636 – you can go there to click through directly. It’s about halfway down the page:
Step 14 – Now that you have the skeleton, it’s time to start adding content! (If you hugo server now, you’ll get a mostly blank page just like last time, because it’s looking for directories and files in /content and you don’t have them yet. We will fix that.) I’m going to choose three very specific directory names to illustrate Quirk #1. We’re also going to pull in totally random images that you have on your machine now that you’ve installed two themes: vanilla bootstrap and showcase. We put them in /static (the place where static files like css usually go) not because it’s a best practice, but because it’s the only practice I know (so far) that works. We change the name on the second file so it doesn’t overwrite.
cd /d/Hugo/myrealsite/content
mkdir books
mkdir code
mkdir services
cp /d/Hugo/themes/showcase/images/screenshot.png /d/Hugo/myrealsite/static
cp /d/Hugo/themes/vanilla-bootstrap-hugo-theme/images/screenshot.png /d/Hugo/myrealsite/static/screenshot2.pngStep 15 – Now we need to put markup files in those directories too, so the web site has something to display. We want to create one markdown page per card we want to see on the front page: so, two will go in each directory:
cd /d/Hugo/myrealsite/content
cp /d/Hugo/myrealsite/themes/showcase/exampleSite/content/projects/startup.md books/book1.md
cp /d/Hugo/myrealsite/themes/showcase/exampleSite/content/projects/startup.md books/book2.md
cp /d/Hugo/myrealsite/themes/showcase/exampleSite/content/projects/startup.md code/code1.md
cp /d/Hugo/myrealsite/themes/showcase/exampleSite/content/projects/startup.md code/code2.md
cp /d/Hugo/myrealsite/themes/showcase/exampleSite/content/projects/startup.md services/services1.md
cp /d/Hugo/myrealsite/themes/showcase/exampleSite/content/projects/startup.md services/services2.md
Step 16 – Go into EACH one of those files and customize it. DO NOT make the date in the future, or the file will not render on your web site. Here’s what the changes correspond to on the page:
---
title:
Big Words Over Image
date: 2020-06-15
subtitle: Small Words Under Image
link: https://atomic-temporary-5081318.wpcomstaging.com
image: ./filename-of-image-in-your-static-directory.jpg # png will also work
---
Go ahead and edit all six markdown files if you want, but if you are getting tired (right?) you’ll be able to see enough of what you need if you just edit two of them. I made the two files in /books look like this:
$ cat book1.md
---
title: Book 1
date: 2020-06-01
subtitle: The first book
link: https://google.com
image: ./screenshot.png
---
$ cat book2.md
---
title: Book 2
date: 2020-06-01
subtitle: The second book
link: https://yahoo.com/
image: ./screenshot2.png
---
Step 17 – Because our images are mostly white, we’ll also have to edit /d/Hugo/myrealsite/layouts/index.html to force the words that are superimposed over the images to be black, otherwise they will not appear against the light image:
<h2
class="text-black px-2 py-1 tracking-widest text-2xl leading-tight
font-extrabold font-bree text-center w-full h-full flex justify-center items-center absolute t$
>
{{ .Title }}
</h2>
<p
class="text-black px-2 py-1 tracking-widest text-md leading-tight
font-light w-full text-center absolute bottom-0 left-0"
>
{{ .Params.Subtitle }}
</p>
Step 18 – I also promised that I’d show you how to make the twitterbird (and other social logos at the far bottom right) bigger. Do this for EACH social logo you want to embiggen:
cd /d/Hugo/myrealsite/layouts/partials
nano footer.html
# then when you're in there... see those 5's? make them 10's:
{{ end }} {{ if .Site.Social.twitter }}
<a class="ml-3 text-gray-500" href="{{ .Site.Social.twitter }}">
<svg
fill="currentColor"
stroke-linecap="round"
stroke-linejoin="round"
stroke-width="2"
class="w-5 h-5"
viewBox="0 0 24 24"
>
<path
d="M23 3a10.9 10.9 0 01-3.14 1.53 4.48 4.48 0 00-7.86 3v1A10.66 10.66 0 013 4s-4 9$
></path>
</svg>
</a>
{{ end }} {{ if .Site.Social.instagram }}
Step 19 – It’s finally time to build your own first Hugo site:
cd /d/Hugo/myrealsite
hugo serverNow head back to http://localhost:1313 — and by now, you should have enough background to fix those broken images and other error messages that you see. I’ll leave those as an exercise for the reader.
Step 20 – Now it’s time to push your site to a GCS bucket on Google Cloud. I know you’re exhausted, but this part will be relatively easy compared to what you just slogged through. In the meantime, check out the quirks I found in this theme as you celebrate your first victory.
- Quirk #1: The subdirectories under
/contentturn into groups on your home page, each of which gets a menu option in the upper right corner. If the directory name you chose does not end in an S, the theme will automatically pluralize the word on the menu. For example, if you wanted a subdirectory called/codeto create blocks on your home page, the little blue box in the upper right corner will say “Code” while the menu option says “Codes”. This is why on http://nicoleradziwill.com you see a menu item Repos that links to my blog and a github repo. I know a blog is not actually a repo, but technically it’s a repository of posts, so I used that technicality to rationalize my design choice instead of hunting for where this very much unmagical pluralization happens. - Quirk #2: I was not able to add more than one menu option in
[[menu.main]]– even following documentation from many sources. I feel like there may be some quirk or hardcoding in this theme that limits you to one extra menu item beyond the list of subdirectories in /content, which automatically get posted to the menu. - Quirk #3: If you specify
message=""in theconfig.tomland are disappointed that it leaves a huge padding of whitespace on your web page, you can take it out! I’ll spare you the agony of trying to figure out where. Go to/d/Hugo/layouts/, editindex.html, and remove line 5 that says{{- partial "custom-message.html" . -}}— this is Hugo’s very nice templating language, and if you stick with Hugo, you’ll learn how to build web pages that contain standard objects and special variables that describe the site, which is how you end up with a scalable, maintainable site. It is nice, it just takes a lot of elbow grease to be able to experience the nice.