quick start of Hugo

quicker than the official doc

Hugo | Documentation

Presented by Creative Squad, Marco Huang

Introduction: why do we even want Hugo?

  • It is very fast to generate a static site
  • It has tons of essential features for your site
  • Straightforward to set up and easier to preview jekyll vs hugo blog
  • Custom is available and easy to implement

Introduction: how fast?

Compile time

folder structure

My Project Overview Documentation:

.
└── content //<- We manage the content we want to publish here in markdown
    └── posts 
        ├── mypost.md   // <- https://example.com/posts/mypost/
        ├── happy
        |   └── ness.md  // <- https://example.com/posts/happy/ness/
        ├── sad
        |   └── index.md  // <- https://example.com/posts/sad/
        └── secondpost.md  // <- https://example.com/posts/secondpost/
└── config.toml // <- site configuration 
└── layouts //<- We design the html template here to render the content
    ├── 404.html   // 404 page design 
    └── index.html  // home page design 
    └── _default 
        ├── single.html   // single page rendering 
        └── list.html  // list page design to render taxonomy pages   
└── themes //<- We import the themes here

Working process

Quick start steps (press space): Documentation

Install Hugo: brew install hugo
Start your site: hugo new site hello-world
Pick your favorite theme
Configure the config.toml file
 Design the html template
 Enjoy creating your content
 Preview your content locally: hugo server -D -p1314

Hello World Demo

- Create a site: hugo new site hello-world && cd hello-world
- Add a theme: git init && git submodule add https://github.com/budparr/gohugo-theme-ananke.git themes/ananke
- Edit config.toml: theme = "ananke"
- Create a new post: hugo new hello-world.md
- Edit post: echo "## Hello World" >> content/hello-world.md
- Bring up local server: hugo server -D -p1314 
- View your content locally in localhost:1314/hello-world/

What is behind the scene

  1. By default, we don’t have any rendering html define in “/layouts”
  2. There is a lookup order how Hugo tries to compile
  3. Hugo interleaves the search in your layout and themes/ananke/layout
  4. In this case, it is in themes/ananke/layout/page/single.html

Let’s take a look at the theme layout single.html

It is built by Hugo Variable, more specifically Page Variable and HTML Element.

<header>
  <p class="f6 b helvetica tracked">
    {{ humanize .Section | upper  }}
  </p>
  <h1 class="f1">
    {{ .Title }} Wow 
  </h1>
</header>
<div class="nested-copy-line-height lh-copy f4 nested-links nested-img mid-gray">
  {{ .Content }}
</div>

Let’s go back to the content

  1. What’s inside the content/hello-world.md
  2. Front Matter defines parameters
  3. The Actual Content: ## Hello World follows markdown style
--- <- This part is front matter 
title: "Hello World"
date: 2020-03-15T16:09:35-04:00
draft: true
--- <- This is the rear of front matter 
## Hello World  <- Start of content

Another Same Content

  1. To get more understanding, we can create another hello page
  2. mkdir content/another-hello-world && cp content/hello-world.md content/another-hello-world/index.md
  3. I personally think this is a more idiomatic way to manage resource
  4. Download any picture online and save under the folder and echo “![Figure](hello_world.png) >> content/another-hello-world/index.md”

Next: Front Matter

  • Almost in every content file
  • Some built in properties such as draft
  • Have you noticed the value true there?
  • Why is it still shown up? Because the option we specify hugo server -D
  • Get rid of the option and we are going to get the 404 page instead
  • This is part of content management, publish control!

Shortcodes

  1. Shortcodes are pre-defined htmls that can be used.
  2. e.g. {{< youtube Eu4zSaKOY4A >}} Let’s include that in our new hello world page

Customized Shortcodes

  1. There are lots of built-in shortcodes in Hugo
  2. We can also customize a new shortcode for our own site
  3. What if we want other video embedded instead of Youtube, such as bilibili
  4. Create the shortcode template in layouts/shortcodes/bilibili.html
{{- $aid := .Get "aid" | default (.Get 0) -}}
{{- $class := .Get "class" | default (.Get 1) }}
<div {{ with $class }}class="{{ . }}"{{ else }}style="position: relative; padding-bottom: 56.25%; height: 0; overflow: hidden;"{{ end }}>
  <iframe src="https://player.bilibili.com/player.html?aid={{ $aid }}&amp;cid={{ with .Get "cid" }}{{ . }}{{ end }}&amp;page=1" {{ if not $class }}style="position: absolute; top: 0; left: 0; width: 100%; height: 100%; border:0;" {{ end }}allowfullscreen title="Bilibili Video"></iframe>
</div>

Deploy

  1. Okay, now we are ready
  2. Try to compile your site by just typing: hugo or hugo -D to allow draft as well
  3. A /public folders will contain the static site ready for deploy
  4. Hugo provides a lot of deploy options

Deploy with GitHub Page, Project Page

  1. Change config, baseURL="https://USERNAME.github.io/PROJECT_NAME/”
  2. Add publishDir, publishDir="docs”. Now hugo will put the compiled site files in docs in stead of public
  3. Git push the docs folders to GitHub Repo as well
  4. My Example repo
  5. Configure GitHub Page in GitHub Settings -> GitHub Pages -> master branch /docs folder
  6. View the site

Questions?

Bonus Slides

  1. Normally you can find example provided by the theme including configurations and content they support in /themes/ananke/exampleSite
  2. This applies to all other theme

Bonus Slides

  1. I find the most powerful theme is call Academic
  2. Even this talk slides is powered by reveal.js used by Academic theme

Bonus Slides

  1. This talk gives the concepts to interact with Hugo for quickstart purpose
  2. You can actually one click to do this: https://sourcethemes.com/academic/docs/install/#install-with-web-browser