Hugo 101 :: (optional) Steal His Look

I like making sure other people can get exactly the same access to all the tools I use. If anything you see me do today looks interesting, feel free to ask me how I did it! Or you can grab all the tools I will use at once by following these simple steps.

1. Install VirtualBox
2. Download Ubuntu
3. Create an Ubuntu virtual machine - great official instructions!
   • “Virtual machine” = a computer that runs inside your computer like a normal program
4. Run the 3 scripts at https://github.com/hiAndrewQuinn/shell-bling-ubuntu

Hugo 101 :: these slides live at https://andrew-quinn.me/hugo-101-slidy.html

• a more normal html version @ https://andrew-quinn.me/hugo-101/

Hugo 101 :: what i hope you leave with

• (optional) some shell bling
• how to use hugo…
  • … to make a website!
  • … to get that website online!
  • … to build and tinker around with other people’s websites!
    • … like fireship.io! (github link!)
    • … like utilitarianism.net! (github link!)
    • … like digital.gov! (github link!)
• confidence! websites aren’t hard!

Hugo 101 :: what i need from you

• Keep that terminal OPEN and HAVE FAITH. Hugo is a command line-based tool, we’re going to use it a lot. We might even use multiple at once
  • If you get lost, feel free to ask for help! We’re all friends here.
  • If you’re shy, try asking ChatGPT for help. ChatGPT is stupid good at helping you out with shell commands:
    1. Describe what you are trying to do
    2. Copy and paste what you did into the shell
    3. Ask it for a better version

Minimum viable terminal programs:

• PowerShell on Windows (pre-installed);
• Usually just pre-installed as “Terminal” elsewhere.

Recommended terminal programs:

• Windows Terminal on Windows;
• Kitty and the Fish shell elsewhere. (Installed w/ Shell Bling Ubuntu out of the box!)

Hugo 101 :: about me

• hey i’m andrew
  • https://andrew-quinn.me/
    • frontpaged hacker news last year! twice even!!
  • https://twitter.com/zephyr_on_call
• northwestern grad 2020 - bs in ee + minor in math
• current: project sw lead @ teleste =« before: cloud admin @ nomentia =« before: hosting eng @ epic

Hugo 101 :: What is Hugo?

https://gohugo.io/ | https://github.com/gohugoio/hugo

• A static site generator.
  • site = web-site!
  • static = no comments!! (or so you would think…)
  • generator = because writing HTML by hand kinda sucks!!!
• Written in the Go programming language.
  • Created by Google!
  • Designed to be fast and simple above all else.
  • Also designed for teamwork. (So I’m told!)
• UNBELIEVABLY POWERFUL … if you can get past the learning curve. Hence why we’re here!

Hugo 101 :: Installing Hugo

• On Windows: Open PowerShell and run winget install Hugo.Hugo.Extended.

  • Don’t have winget? Install it with the instructions here, then try it.

• On Mac: Open the terminal and run brew install hugo.

  • Don’t have brew? Install it with the command here, then try it!

• On FOSS operating systems: Lots of options. Probably already exists in your favorite package manager.

  • If on Ubuntu: sudo snap install hugo > sudo apt install hugo (gives newer version)

• Then check the version: Run hugo version.

  • Should be at least “v0.110.0+extended”. But higher is better :)

Much more complex instructions @ Installation | Hugo!

Hugo 101 :: Minimum Viable Hugo [1/9]

⚠️: Most of the shorter commands work in PowerShell too. ChatGPT comes in really handy here.

• Did you keep that shell OPEN? 🔍

• Create a new folder called ’example-1'

  • In Windows PowerShell: New-Item -ItemType Directory -Name "example-1"
  • In other shells: mkdir example-1

• Then change directories into it. (Directories == folders.)

  • In Windows PowerShell: Set-Location -Path "example-1"
  • In other shells: cd example-1

• Check you’re in the right place: Run pwd. Does it end with example-1?

  • Check that it’s empty: Run ls (works everywhere). The folder should be empty.

Hugo 101 :: Minimum Viable Hugo [2/9]

• Open https://github.com/Siilikuin/minimum-viable-hugo.
• Run through each command under the Quickstart, in order.
• We will also do the same here!

Hugo 101 :: Minimum Viable Hugo [3/9]

⚠️: Anything which starts with hugo is built into the hugo program itself and should work identically on both PowerShell and other shells.

# Hugo 101 :: Start a new Hugo website!
# Hugo 101 :: The dot '.' means "Start it right here, not in a folder in here."
# Hugo 101 :: The '--force' means "Even if this isn't empty" (although it _should_ be).
hugo new site . --force
# Hugo 101 :: ... oh, and these things are comments.
# Hugo 101 :: You can paste them into the shell harmlessly. In fact I recommend it!

• Check that it worked: Run ls (works everywhere) to see if a bunch of new folders were created.

• If you want to get rid of everything in the folder and start from the beginning:

  • BE CAREFUL. Check you’re in the right place with pwd first.
  • On PowerShell: Remove-Item -Recurse -Force *
  • On other shells: rm -rf * (does NOT work on PowerShell)

Hugo 101 :: Minimum Viable Hugo [4/9]

Hugo always needs a theme before it will make anything show up at all. Let’s give it one!

# Hugo 101 :: Make a new theme, called minimum-viable-hugo.
hugo new theme minimum-viable-hugo

# Hugo 101 :: Tell Hugo we want to use minimum-viable-hugo.
echo "theme = 'minimum-viable-hugo'" >> hugo.toml

hugo.toml is a TEXT FILE that should appear where we are. It tells Hugo all the settings for the whole project. We can open it in any text editor we want, even Notepad if that’s all we have!

.toml = Tom’s Obvious Minimal Language. Easy to read!

You can see what’s in it with gc hugo.toml (PowerShell) / cat hugo.toml (shell) / bat hugo.toml (Shell Bling Ubuntu).

Hugo 101 :: Minimum Viable Hugo [5/9]

# Hugo 101 :: GOTCHA #1: Your root page is called _index.md.
hugo new _index.md
echo "Lorem ipsum dolor sit amet" >> content/_index.md

.md = Markdown. Because writing HTML by hand sucks.

# Hugo 101 :: An H1 heading in Markdown

## An H2 heading in Markdown

*Italics* and **bold** in Markdown.

![Alt text:A place to an image in Markdown](image-in-markdown.jpg)

We can open _index.md in any text editor we want, and in fact we will!

Hugo 101 :: Minimum Viable Hugo [6/9]

# Hugo 101 :: GOTCHA #1: Your root page is called _index.md.
hugo new _index.md
echo "Lorem ipsum dolor sit amet" >> content/_index.md

Hugo 101 :: Minimum Viable Hugo [7/9]

# Hugo 101 :: GOTCHA #2: Hugo needs to be explicitly told to
# Hugo 101 :: serve content from _index.md.
echo "{{ .Content }}" >> themes/minimum-viable-hugo/layouts/index.html

Hugo 101 :: Minimum Viable Hugo [8/9]

# Hugo 101 :: Serve the site. Don't leave out the -D yet.
hugo server -D

• Then go to localhost:#### in your browser and you should see it - your first Hugo webpage.

Hugo 101 :: Minimum Viable Hugo [9/9]

If you look at content/_index.md, with cat or gc or opening it in a text editor, it will look like

---
title: ""
date: 2023-02-27T18:21:50+02:00
draft: true
---

Lorem ipsum dolor sit amet

Change draft to false. Then you’ll be able to run your site with just

hugo server

Hugo 101 :: Workshop time!!

• You now know enough to start hacking

Time set aside to answer questions, try out some of the ‘advanced’ stuff on Minimum Viable Hugo, just generally let people try things they think would be neat, etc.

Hugo 101 :: CONGRATS THAT’S HUGO 101 YOU MADE IT

• I didn’t really know how to time this workshop!
• So I prepped 2 additional sections, to lesser degrees, depending on how fast we get through this one:
  • HUGO 102: Get It Online
  • HUGO 201: Learning From Others (no slides)

Hugo 102 :: GET IT ONLINE

• Every website you visit has a turned-on computer somewhere in the world whose job is to hold the website at the ready for you.
  • We call this a “server”.
• localhost == using your own computer as the server! Neat!
• But websites are meant to be shared!

Hugo 102 :: Introducing Github

• There are a zillion different ways to get a websites online. Not all are created equal:
  • Some are expensive, some are totally free!
  • Some are super complex, some are dead simple!
• For this tutorial, we are going to host it at Github Pages.
• Which means… you will need a Github account.

Time set aside to set up Github accounts for anyone who needs one.

Hugo 102 :: Setting up git

• Git: “Save As…"’s older brother
  • Everyone in CS uses it
  • Most people (including me) understand like 3 things and just ignore the rest
  • Still ludicrously helpful
• Step 1 is to install Git if you don’t have it already.

Time set aside to install Git for anyone who needs it.

• Check: Open your shell and run git version. If something appears, it’s installed!

Hugo 102 :: Setting up gh [1/2]

• How do we get Git (on our computer) and Github (a website) to work together?
• Many ways - but I like the gh command-line tool.

Time set aside to install cli.github.com.

• Check: Open your shell and run gh version.

Hugo 102 :: Setting up gh [2/2]

• Run gh auth login and follow the instructions.
  • Stick with all the defaults if you’ve never done this before.
    • When you get the “one time code”, you can also go to https://github.com/login/devices on a device you’re already logged into.

Check: Run gh auth status. If it shows your username, you’re golden!

Hugo 102 :: Putting our Hugo website on Github

• Go to your example-1 folder in the terminal.
• Run gh repo create and follow the instructions.

Time set aside to get a new Git repo online.

Hugo 102 :: Building the Github Pages

Time set aside to follow the Procedure at GoHugo.IO.

Hugo 102 :: Changing the Website on the Fly [1/3]

• Great! We now have a single page somewhere reading “Lorem ipsum dolor sit amet”.
• What if we want to not be boring, though?
• Enter: The add - commit - push loop.
  • git add . will add all of your changes.
  • git commit -m "Description of what I did" will commit them all to Git’s “long term memory”.
  • git push will push your changes to GitHub, where
    • Github will notice you changed stuff and
    • rebuild your website on the fly.

I do this exact thing dozens of times a day in the real world. add, commit, push. That’s it. It’s literally how I built this whole presentation!

Hugo 102 :: Changing the Website on the Fly [2/3]

• Open a terminal.
• Run hugo server in another terminal, minimize it, and visit localhost:#### in your web browser to see the content change.
• Add something to your example-1/content/_index.md. Anything!
• Then check localhost:#### again in your web browser.

Hugo 102 :: Changing the Website on the Fly [3/3]

• git status to see the change.
• git add ., git commit -m "just playing around", git push… and then wait.
• The change should appear online in just a few minutes.

Hugo 101 :: Workshop time!!

• You now know enough to start hacking

Time set aside to answer questions, help people who ran into issues, let people try things they think would be neat, etc.

Hugo 102 :: DONE. ONTO 201

Hugo 201 :: Learning From Others

Time set aside to get fireship.io running locally and start tweaking it live in front of people.

Thank you

• Email is [my first name] [at] siilikuin.net