Tag Archives: web

Turn on your Domain Name for a Hugo Site on Google Cloud (PART 4)

You’ve got your Hugo site built, and in a public GCS bucket, and you can see it by going to the URL at https://storage.googleapis.com/www.yourdomainname.yourtld — now how can you make http://yourdomainname.yourtld work directly? This post assumes that you’ve already purchased a domain from http://domains.google and you have a Hugo site (or any other web site) set up in a GCS bucket.

Step 1 – Get into the domain administrator panel. Go to http://domains.google and click “My Domains” in the top right of the window.

Step 2 – Find the domain that you want to map to this bucket and click “Manage” on the rightmost side of that line.

Step 3 – Click “Edit DNS Settings” OR “Use custom name servers for your domain” – they both go to the same page.

Step 4 – Scroll down to “Custom Resource Records”:

  • In the textbox that says @, type www
  • In the dropdown, select CNAME
  • Keep 1H in the next textbox
  • In the last textbox, type c.storage.googleapis.com. (that last dot is important, too)
  • Click Add

Step 5 – Add a Synthetic Record so your “naked domain” (no www) will work. In the “Synthetic Records” section, put an @ in the first box, put http://www.yourdomainname.yourtld in the rightmost box, and click “Forward Path” in the middle group of radio buttons. Click Add and this should make the magic happen.

Step 6 – Wait. They’ll say it takes up to 48 hours for DNS to propagate… it usually takes a lot less. Even though you set up the CNAME to trigger from www, Google Domains automatically catches www and no subdomain, so you should be able to go to http://yourdomainname.yourtld. Check your custom URL after an hour or two! If the site isn’t available by the next day, though, there may be a problem in your GCS bucket or your setup.

Good luck! And remember to check out the “I want to get off Squarespace” project that motivated these posts… http://nicoleradziwill.com

Pushing Your Hugo Site to a GCS Bucket (PART 3)

By now, you’ve build a gorgeous Hugo site that you admire at http://localhost:1313 that no one but you can see. This post aims to help you fix that, by taking the first deployment step: putting your Hugo site into a GCS bucket. This assumes that you also have git bash installed with the Google Cloud SDK (gsutil), and that you’re familiar enough with http://console.cloud.google.com that you can log in and double check your settings. This also assumes that you’ve purchased a domain name that you administer through http://domains.google. Now! to begin.

Step 1 – Build your Hugo site. Even though you can view it on localhost, the static site hasn’t been built yet.

cd /d/Hugo/myrealsite

That’s it! The GO engine behind Hugo just created a ton of static web pages on your behalf, and popped them into the /public directory. Go into that directory and ls -spla just to make sure stuff is there.

Step 2 – Use gsutil to set up your new bucket and tell Google Cloud that it will be a web site. You should still be sitting in /d/Hugo/myrealsite. Note: The domain name MUST have www in the beginning, even if you want to direct people to yourdomainname.yourtld.

gsutil mb gs://www.yourdomainname.yourtld
gsutil web set -m index.html -e 404.html gs://www.yourdomainname.yourtld

Step 3 – Make everything in that bucket public so people on the internet have the permissions to get to your page. This part was a little tricky for me, because I’m not sure exactly which command made it work, but I can tell you how to double check. Start by doing one (or both) of these:

gsutil defacl ch -u allUsers:R gs://www.yourdomainname.yourtld
gsutil iam ch allUsers:objectViewer gs://www.yourdomainname.yourtld

When you go into http://console.cloud.google.com, head to Storage -> Browser. Find the line item that has your http://www.yourdomainname.yourtld name that you just created. In the “Public Access” column, there should be a little orange warning icon and the words “Public to Internet”. If you don’t see that, then Google around for more advice on “how to make the contents of your GCS bucket public to the internet”.

While you’re in there, check to make sure the bucket is set up to serve a web page. On the far far right side of that same line, you’ll see three vertical dots. Click on them, and go into “Edit Website Configuration”. The top textbox should say index.html and the bottom should say 404.html. If they don’t, make them say that, and then click Save.

Step 4 – Populate your GCS bucket with your built Hugo site in /public (not the raw files you edited). Make sure you’re still sitting in /d/Hugo/myrealsite and then do this:

gsutil rsync -R public gs://www.yourdomainname.yourtld

Step 5 – You now have a Hugo web site on Google Cloud! Test it out by pointing a browser to https://storage.googleapis.com/www.yourdomainname.yourtld/index.html (being sure to put your actual domain name in there) — if you get a permission error or an XML dump, go back to Step 3 because something went wrong there.

Now it’s time to link your bought domain name with your publicly visible Hugo web site!

Building Your Hugo Site Locally (PART 2)

…continued from https://qualityandinnovation.com/2020/12/22/getting-started-with-hugo-part-1/ which is part of the series summarized at https://qualityandinnovation.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 mytestsite

Step 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-theme

This 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
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/showcase

This 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"]

  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

  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

  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 11cd 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/ layouts

Now 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 message

You 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.png

Step 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:

 Big Words Over Image
date: 2020-06-15
subtitle: Small Words Under Image
link: https://qualityandinnovation.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:

            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 }}
            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 }}

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 }}">
          class="w-5 h-5"

          viewBox="0 0 24 24"
            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$
      {{ end }} {{ if .Site.Social.instagram }}

Step 19 – It’s finally time to build your own first Hugo site:

cd /d/Hugo/myrealsite
hugo server

Now 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 /content turn 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 /code to 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 the config.toml and 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/, edit index.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.

Getting Started with Hugo (PART 1)

Hugo is a static web site generator. What that means is: it provides you with lots of templates, variables that you may want to see reappear throughout your site (and when changed once, update everywhere – like author name), and an engine that turns those templates into a lightning fast web site. That way, you can focus on the content rather than the presentation.

With Hugo, you will definitely be focusing on both though. But there’s a payoff: your website will be gorgeous, and even other people will notice (pretty much immediately) that it’s blazing fast. These steps assume that you have git bash installed, and that you’re working on Windows 10.

Step 1 – Open git bash and create a directory for all your Hugo adventures. Mine is on my D drive, but yours might be on C:

mkdir /d/Hugo

Step 2Download the Hugo executable to your machine, and put it in that directory you just created. Then, unzip all the contents into that same directory.

Step 3 – Add your new Hugo directory to the Windows PATH. Type env in the search bar at the bottom left of your screen and hit enter. On the window that pops up, click the Environment Variables button. In the bottom window, find the row that starts with Path and click it. Next, click Edit, then New. At the bottom of the list, add D:\Hugo (but put the directory YOU created on your machine! And be very careful about the direction of the slash).

Step 4 – Open git bash and type hugo version, then hit Enter. If you see a message like this one, Hugo is ready to go!

User@DESKTOP-4H0EUDG MINGW64 /d/Hugo (master)
$ hugo version
Hugo Static Site Generator v0.79.1-EDB9248D windows/amd64 BuildDate: 2020-12-19T15:44:19Z

…to be continued in next post