Hugo - Layout

   
   
 hugo  
 ssg  
Article Series

This article series contain few sections.

Supplementary Article for Windows User.

Clone Tutorial Source.

Where to Discuss?

Local Group

Table of Content

Preface

This article is intended for beginner.

Goal: Show Minimalist Layout in Hugo

In this guidance, there are two context:

  • content refer to root directory, and

  • layout refer to themes directory.

Markdown

Hugo content can use either html or markdown. You can read about Markdown format here:

Source Code

You can download the source code of this article here.

1: Minimal Theme

In order to make a step by step guidance, we need to move the layout to theme. Of cource you can use site layout instead of theme layout. It is just easier to maintain for this tutorial case.

New Theme

Consider make our very first new theme.

$ hugo new theme tutor-01
Creating theme at /media/Works/sites/tutor-hugo/themes/tutor-01

This will generate skeleton of your theme.

$ tree themes
themes
└── tutor-01
   ├── archetypes
   │  └── default.md
   ├── layouts
   │  ├── 404.html
   │  ├── _default
   │  │  ├── baseof.html
   │  │  ├── list.html
   │  │  └── single.html
   │  ├── index.html
   │  └── partials
   │     ├── footer.html
   │     └── header.html
   ├── LICENSE
   ├── static
   │  ├── css
   │  └── js
   └── theme.toml

Hugo: New Theme

Source: gitlab.com/…/themes/tutor-01 .

Config: Theme

Consider changing config.toml, to include newly created theme.

baseURL      = "http://example.org/"
languageCode = "en-us"
title        = "Letters to my Beloved"
theme        = "tutor-01"

As the config changed, the server should be restarted.

Default: Baseof Template

All html files are empty, with zero based size, except /layouts/_default/baseof.html.

<html>
    {{- partial "head.html" . -}}
    <body>
        {{- partial "header.html" . -}}
        <div id="content">
        {{- block "main" . }}{{- end }}
        </div>
        {{- partial "footer.html" . -}}
    </body>
</html>

Source: gitlab.com/…/layouts/_default/baseof.html

Theme: Homepage

Consider change our layout, in themes/tutor-01/, in layouts/index.html with block definition.

{{ define "main" }}
<p>Dear love,</p>

{{ .Content }}

<p>Sincerely yours.</p>
{{ end }}

Source: gitlab.com/…/layouts/index.html

Partial: HTML Head

We are not done yet, in themes/tutor-01/, we need to make partials/head.html.

<head>
  <title>{{ .Site.Title }}</title>
</head>

Source: gitlab.com/…/layouts/partials/head.html

Server Output: HTML Source

And the result is:

<html>
<head>
  <meta name="generator" content="Hugo 0.42.1" />
  <title>Letters to my Beloved</title>
</head>
<body><div id="content">
<p>Dear love,</p>

<p>There are so many things to say.
  I don't want to live in regrets.
  So I wrote this for my love.</p>


<p>Sincerely yours.</p>

        </div><script data-no-instant>document.write('<script src="/livereload.js?port=1313&mindelay=10"></' + 'script>')</script></body>
</html>

Hugo: _default/baseof

2: Refactor

We can refactor a common layout into these three artefacts.:

Homepage

  • layouts/index.html
{{ define "main" }}
{{ .Content }}
{{ end }}

Partial: Header

  • layouts/partials/header
<p><i>My one, and only dream,</i></p>
  • layouts/partials/footer
<p><i>Wishful thinking.</i></p>

Server Output: HTML Source

The result is similar:

Hugo: Browser Homepage

$ curl localhost:1313 | less
<html>
<head>
   <meta name="generator" content="Hugo 0.42.1" />
  <title>Letters to my Beloved</title>
</head>
<body><p><i>My one, and only dream,</i></p>
<div id="content">
<p>There are so many things to say.
  I don't want to live in regrets.
  So I wrote this for my love.</p>


        </div><p><i>Wishful thinking.</i></p>
<script data-no-instant>document.write('<script src="/livereload.js?port=1313&mindelay=10"></' + 'script>')</script></body>
</html>

Hugo: curl Example: Reuse

Now you can reuse parts as below.

3: Reuse

Now we can reuse single page. We need these four artefacts:

Partial: Head

  • themes/tutor-01/layouts/partials/head
<head>
  <title>{{ .Page.Title | default .Site.Title }}</title>
</head>

You should see different title header at the top of browser later on.

Default: Single

  • themes/tutor-01/layouts/_default/single
{{ define "main" }}
<blockquote>I pour the <b>journal</b> as daily letter.</blockquote>

{{ .Content }}
{{ end }}

Example Content: Hello

You can put the post in any directory.

  • content/letters/hello.html
+++
title = "Hello There"
+++
  <p>I wish you are okay over there.
     I just need to say hello.</p>

and open it later in

  • http://localhost:1313/letters/hello/

Hugo: Browser Example: Hello

Example Content: Duty

You can use markdown format as well

  • content/duty.md
+++
title = "My Apology"
+++
We still have duty calls to be done.
I can't go home anytime soon.

Hugo: Browser Example: Duty

4: Section

We can make a list of each section easily.

Example Content: Winter

I also put other content in letters directory.

  • content/letters/winter.md
+++
title = "Surviving White Winter"
+++

It was a frozen winter in cold war era.
We are two men, a boy, two women, a husky, and two shotguns.
After three weeks, we finally configure dzen2.

But we lost our beloved husky before we finally made it.
Now, every january, we remember our husky,
that helped all of us to survive.

Hugo: Browser Example: Winter

Real Directory

Consider examine the tree.

$ tree content

content
├── _index.html
├── duty.md
└── letters
   ├── hello.html
   └── winter.md

Hugo: Tree Content

.

Section List

By using /layouts/_default/list.html, you can access http://localhost:1313/letters/.

{{ define "main" }}
  <h1>{{ .Section }}</h1>

  {{ .Content }}

  <ul>
    {{ range .Data.Pages }}
    <li>
      <a href="{{ .URL }}">{{ .Title }}</a>
    </li>
    {{ end }}
  </ul>
{{ end }}

Note that, this list only show the list of letters folder.

Hugo: Browser List

Source: gitlab.com/…/layouts/_default/list.html

5: Taxonomy

Hugo has amazing taxonomy that almost tears my eye. Earlier we have list of section. Now we can setup categories and tags easily.

Prepare Config

We need to configure the config.toml.

baseURL      = "http://example.org/"
languageCode = "en-us"
title        = "Letters to my Beloved"
theme        = "tutor-01"

[taxonomies]
  category = "categories"
  tag = "tags"

As we change the config.toml, we must also restart the server.

Apply in Frontmatter

And add taxonomies into

+++
title  = "Hello There"
tags   = ["wishful", "story"]
categories = ["love"]
+++
  <p>I wish you are okay over there.
     I just need to say hello.</p>

and

+++
title  = "Surviving White Winter"
tags   = ["duty", "story"]
categories = ["love"]
+++

It was a frozen winter in cold war era.
We are two men, a boy, two women, a husky, and two shotguns.
After three weeks, we finally configure dzen2.

But we lost our beloved husky before we finally made it.
Now, every january, we remember our husky,
that helped all of us to survive.

Taxonomy Terms: Category

We can check taxonomy terms:

Hugo: Browser Taxonomy

Taxonomy Item: Category

Now we can access:

Hugo: Browser Taxonomy

Taxonomy Item: Tags

We can add any taxonomy terms as well.

Hugo: Browser Taxonomy

6: Custom Page

We can make custom pages other than the default one. For example, we make a custom post, with slug and date.

Custom Page: Single

For this to achieve, we need to make this one artefact.

{{ define "main" }}
<b>{{ .Date.Format "2006, 02 January" }}</b>

<p>Dear Angel,</p>

{{ .Content }}

<p>With deep love in my heart.</p>
{{ end }}

Example Content: Everyday

Consider make this one post as an example

  • content/posts/everyday.md
+++
type   = "post"
title  = "Everyday I Ask"
date   = 2015-10-03T08:08:15+07:00
slug   = "daily-wish"
tags   = ["wishful", "story"]
categories = ["love"]
+++

You know, some people makes mistakes,
and have to bear the consequences, for the rest of their life.
I made, one good decision when I was far younger than you are.
Later I know it was the right decision.
But I also have to bear the consquences, for the rest of my life.

> I wish you a good family, and happiness.

And also make new permalink format in config.toml. Restart Hugo server, as the config changing.

Consider this URL to get the new permalink.

Using above list, you will get:

Hugo: Browser Custom Page

Real Life Blog

Let’s get organized.

Real blog may contain hundreds of articles. We can put articles in separate sections. this way, we can maintain article easily.

content
├── _index.html
├── backend
├── code
├── design
├── frontend
├── pages
└── ssg

Hugo: Section Tree

I also use Jekyll style file naming, sorting by date, to make the article easier to find.

Hugo: File Naming

.

What is Next ?

There are, some interesting topic for Hugo, such as Layout using Semantic HTML5 tag. Consider continue reading [ Hugo Bootstrap - Layout ].

Thank you for reading.