1. Creating and Deploying Static Sites with Hugo
Brian P. Hogan
@bphogan

2. Hi. I'm Brian!
— Editorial Manager at DigitalOcean
— Programmer (http://github.com/napcs)
— Author (http://bphogan.com/publications)
— Musician (http://soundcloud.com/bphogan)
— Teacher

3. Shameless Plug
Small Sharp Software Tools
https://
smallsharpso!waretools.com

4. Today we'll
— Build a small portfolio site
with Hugo
— Create a layout for the site
— Create a "projects" section
with a page for each
project
— Create supporting pages
("about" and "résumé")
— Build and test the site
— Deploy the site with Docker
and docker-machine

5. Disclosure and Disclaimer
I am using DigitalOcean in this talk. I work for them and
thus my demo servers are free. This presentation will work
for any cloud provider though.
Want $10 of credit? https://m.do.co/c/1239feef68ae
Also we're hiring and we are remote-friendly. https://
do.co/careers

6. Other such disclaimers...
— This is not the only way to
make static sites
— This is based on my
experience. Yours may vary.
— Questions welcome and
encouraged. Happy to argue
a!er if you buy the drinks.
— I go fast, but all notes are
available a!er the session so
you can play on your own.
— We are taunting the demo
gods today with live coding.

7. Static Sites vs Dynamic Sites
— Web servers excel at serving
text files.
— Traditional content systems
(WordPress, Ghost) use
databases for content and
build pages on the fly.
— Caching becomes more
difficult.
— Most content sites don't have
frequent content changes.
— Static sites are easier than
ever to deploy.

8. What is Hugo
— Static Site Generator with a
single binary CLI tool. No
dependencies.
— Uses Go Templates
— Supports Markdown content
— Generates files quickly
— Good development flow

9. Install Hugo
Mac:
$ brew install hugo
Elsewhere:
Download release for your OS at https://github.com/
gohugoio/hugo/releases

10. Part 1: Create a Hugo site
— Generate the site
— Generate your own theme
— Configure the site to use the
theme

11. Running the Generator
$ hugo new site portfolio
Congratulations! Your new Hugo site is created in /Users/brianhogan/presentations/2018_hugo_docker/code/portfolio.
Just a few more steps and you're ready to go:
1. Download a theme into the same-named folder.
Choose a theme from https://themes.gohugo.io/, or
create your own with the "hugo new theme <THEMENAME>" command.
2. Perhaps you want to add some content. You can add single files
with "hugo new <SECTIONNAME>/<FILENAME>.<FORMAT>".
3. Start the built-in live server via "hugo server".
Visit https://gohugo.io/ for quickstart guide and full documentation.

12. The Hugo Site structure
!"" portfolio
#"" archetypes - Content templates
#"" config.toml - Site config file
#"" content - Content (Markdown, etc)
#"" data - JSON/YAML datafiles
#"" layouts - Site-specific layout files
#"" resources - Other resources you need
#"" static - images, css, json, other static assets
!"" themes - Themes to control appearance

13. Configuring Hugo
File: config.toml
baseURL = "http://example.org/"
languageCode = "en-us"
-title = "My New Hugo Site"
+title = "Portfolio"

14. Hugo Themes
— The "layout" and design of
the site
— Many themes available.
— Existing themes have their
own settings which can be
complex
— Not always documented
well.

15. Create Your Own Theme
Generate a theme:
$ hugo new theme basic

16. Generated Theme structure
themes/basic/
!"" LICENSE - License (if you share your theme)
!"" archetypes - Theme-specific content templates
!"" layouts - Layout files
!"" static - Theme-specific static assets (JS, CSS)
#"" theme.toml - Theme-specific configuration

17. Configuring Hugo to Use the Theme
File: config.toml
baseURL = "http://example.org/"
languageCode = "en-us"
title = "Portfolio"
+theme = "basic"

18. Part 1 Demo
— Generate the site
— Generate a theme
— Configure the site to use the theme

19. Part 2: Building the Layout and
Home Page
— Create base layout (header,
footer)
— Create home page layout and
content
— Fire up the server.

20. What's a layout??
— The "wrapper" for content –
all content pages will sit
inside the layout
— Required:
— index.html - Home page
template
— single.html - template for
single content page
— list.html - template for
pages that show a list of
content pages
— Can create layouts for

21. The _default/baseof File
File: themes/basic/layouts/_default/baseof.html
<!DOCTYPE html>
<html>
{{- partial "head.html" . -}}
<body>
{{- partial "header.html" . -}}
<div id="content">
{{- block "main" . }}{{- end }}
</div>
{{- partial "footer.html" . -}}
</body>
</html>

22. Partials
— Pieces of a layout you can
share across pages
— Header
— Footer
— Sidebar
— Reduces duplication
— Provides organization

23. Filling in the head partial
File: themes/basic/layouts/partials/header.html
<head>
<meta charset="utf-8">
<title>{{ .Site.Title }}</title>
</head>

24. Fill in the header partial
File: themes/basic/layouts/partials/header.html
<header>
<h1>{{ .Site.Title }}</h1>
</header>

25. Fill in the footer partial
File: themes/basic/layouts/partials/footer.html
<footer>
<small>Copyright {{now.Format "2006"}} Me.</small>
</footer>

26. Create the Home Page Template
File: themes/basic/layouts/index.html
{{ define "main" }}
<h2>{{ .Title }}</h2>
{{ .Content }}
{{ end }}

27. Creating Home Page Content
The content/_index.md file holds the content for the
home page:
$ hugo new _index.md

28. Add Home Page Content
File: content/_index.md
---
-title: "Welcome"
+title: "Welcome"
date: 2019-04-13T09:52:21-06:00
-draft: true
+draft: false
---
+Welcome to my portfolio site.

29. Run the Development Server
$ hugo server
...
Watching for changes in /Users/brianhogan/dev/hugo_docker/portfolio/{content,data,layouts,static,themes}
Watching for config changes in /Users/brianhogan/dev/hugo_docker/portfolio/config.toml
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

30. Part 2 Demo
— Create base layout (header, footer)
— Create home page layout and content
— Fire up the server.

31. Part 3: Adding More Pages
— Create a single page layout
— Add the content
— Add a navbar

32. Create the single layout for content pages
File: themes/basic/layouts/_default/single.html
{{ define "main" }}
<h2>{{ .Title }}</h2>
{{ .Content}}
{{ end }}

33. The Default archetype
File: archetypes/default.md
---
title: "{{ replace .Name "-" " " | title }}"
date: {{ .Date }}
draft: true
---

34. Create single pages in content/:
$ hugo new about.md
$ hugo new resume.md

35. Edit the Generated Pages
File: content/about.md
---
title: "About"
date: 2019-04-10T16:33:52-05:00
- draft: true
+ draft: false
---
+ This is the about page

36. Add New Pages to Navbar
File: themes/basic/layouts/_default/header.html
<header>
<h1>My Site</h1>
</header>
+ <nav class="navbar">
+ <a href="/">Home</a>
+ <a href="/about">About</a>
+ <a href="/resume">Resume</a>
+ </nav>

37. Part 3 Demo
— Create single page layout
— Create content pages
— Create navbar

38. Part 4: Adding Content
Collections
— Create content templates
(archetypes)
— Generate content from
templates
— Create a layout to display the
content
— Create a layout to display a
list of content

39. Creating a Projects archetype
— Create a file in archetypes called projects.md
— Fill it in with frontmatter and any mainmatter you
want as a template
— Files created in the content/projects folder by the
Hugo generator will use this archetype

40. Define the projects Archetype
File: archetypes/projects.md
---
title: "{{ replace .Name "-" " " | title }}"
draft: false
---
----
Description...
## Tech used
* item
* item
* item

41. Generate content pages using the archetype
hugo new creates new files relative to the content
directory.
$ hugo new projects/awesomesauce.md
$ hugo new projects/jabberwocky.md
projects is in the path, so archetypes/projects.md gets
used!

42. Modify the generated pages
File: content/projects/awesomesauce.md
---
title: "Awesomesauce"
type: project
---
I made Awesomesauce. It's the most amazing project ever!
## Tech Used
* Hugo

43. Create the list layout for content lists
Need this page so things like /projects show a list of all
projects.
File: themes/basic/layouts/_default/list.html
{{ define "main" }}
<h1>{{ .Title }}</h1>
<ul>
{{ range .Pages }}
<li><a href="{{ .URL }}">{{ .Title }}</a></li>
{{ end }}
</ul>
{{ end }}

44. Add a Navbar to the header partial
File: themes/basic/layouts/_default/header.html
<header>
<h1>My Site</h1>
</header>
<nav class="navbar">
<a href="/">Home</a>
<a href="/about">About</a>
<a href="/resume">Resume</a>
+ <a href="/projects">Projects</a>
</nav>

45. Part 4 Demo
— Create new archetype
— Generate and build content pages
— Create a list page layout
— Update the navbar

46. Part 5: Finish Off the Site
— Adjust base template
— Style site with a little CSS

47. Modify the baseof file
<!DOCTYPE html>
<html>
{{- partial "head.html" . -}}
<body>
+ <div class="container">
{{- partial "header.html" . -}}
- <div id="content">
+ <main>
{{- block "main" . }}{{- end }}
- </div>
+ </main>
{{- partial "footer.html" . -}}
+ </container>
</body>
</html>

48. Add some styles
File: themes/basic/static/css/style.css
.container {
margin: 0 auto;
width: 80%;
}
nav, footer {
background-color: #333;
color: #fff;
text-align: center;
}
nav {display: flex; }
nav > a {
flex: 1;
text-align: center;
color: #fff;
}

49. Add CSS link to head partial
File: themes/basic/layouts/_default/head.html
<head>
<meta charset="utf-8">
<title>My Blog</title>
+ <link rel="stylesheet" href="/css/style.css">

50. Build the site
Generates static HTML pages in public
$ hugo
| EN
+------------------+----+
Pages | 14
Paginator pages | 0
Non-page files | 0
Static files | 1
Processed images | 0
Aliases | 0
Sitemaps | 1
Cleaned | 0
Total in 11 ms

51. Part 5 Demo
— Modify the base template
— Add CSS
— Build site

52. Part 6: Deployment
— Traditional method:
— Get a shared host, or VPS /
Cloud server with a web
server
— Upload public folder
contents to the web
server's webroot
— Use Services
— Publish to S3/Cloudflare
— Use Netlify
— Use Containers

53. Docker and Docker Machine
— Container is a bundle of so!ware for your
application
— Docker is a set of tools for managing containers
— Docker Hosts are places where Docker Containers
run
— Docker Machine is a tool for creating and working
with Docker Hosts

54. Provision a Cloud Server with Docker Machine
$ docker-machine create
--driver digitalocean
--digitalocean-access-token $DOTOKEN
mysite-01
— Docker Machine can create VMs or cloud instances.
— DigitalOcean driver requires a DigitalOcean access
token associated with your account.

55. Create a Container Image
$ touch Dockerfile
FROM nginx:latest
EXPOSE 80
COPY ./public /usr/share/nginx/html
$ docker build -t mysite .

56. Deploy the app
$ eval $(docker-machine env mysite-01)
$ docker build -t mysite .
$ docker run -d --name mysite -p 80:80 --restart unless-stopped mysite
— Switch to the remote Docker host
— Rebuild the image on the host
— Run the container using the image, restarting if it
fails, run on port 80

57. View the app
$ docker-machine ip mysite-01
$ curl $(docker-machine ip mysite-01)

58. Deploying changes
— Change your code
— Rebuild the site
— Rebuild the image
— Replace running container

59. Add a new project
$ hugo new projects/linkitivity.md

60. Rebuild and Redeploy
$ hugo
$ eval $(docker-machine env mysite-01)
$ docker build -t mysite .
$ docker stop mysite && docker rm mysite
$ docker run -d --name mysite -p 80:80 --restart unless-stopped mysite

61. Create a deploy script
$ touch deploy && chmod +x deploy
#!/usr/bin/env bash
hugo
eval $(docker-machine env mysite-01)
docker build -t mysite .
docker stop mysite
docker rm mysite
docker run -d --name mysite -p 80:80 --restart unless-stopped mysite
eval $(docker-machine env -u)

62. Demo
— Create image
— Launch container
— Make code change
— Redeploy

63. Further Exploration: Deploy
Automatically
— Deploy via hooks
— post-commit (good for
simple things)
— post-receive (if you run
your own Git repository)
— Webhook (GitHub)
— Deploy via script to server or
CDN
— Deploy via CI/CD pipeline
— Push to Kubernetes cluster
— Offload interactions with

64. Wrapping Up
— Static sites are fast
— Easier than ever to build
— Graphical editors available
for content contributors
— Deployment without a
database

65. Thanks
— Link to slides: https://bphogan.com/presentations/
2019_hugo
— Twitter: @bphogan
— Book: https://smallsharpso!waretools.com
— DO Credit: https://m.do.co/c/1239feef68ae