Hugo - Layout

   
   
 hugo  
 ssg  
Article Series

This article series contain few sections.

Related Article Series

Download Tutorial Source.

Where to Discuss?

Local Group

Table of Content

Preface

This article is intended for beginner.

Goal: Show Minimalist Layout in Hugo

Source Code

You can download the source code of this article here.

Related Article

I had wrote about Minimal Hugo and you can read here:

The content of this article is, almost copy paste from the previous one. Except that it is prepared for different repository, for Bulma theme later. So watch out for differences.

Content and Theme’s Layout

In this guidance, there are two context:

  • content refer to root directory, and

  • layout refer to themes directory.

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-bulma/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

Config: Theme

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

baseURL      = "http://example/"
languageCode = "en-us"
title        = "Hugo's Letter to Bulma"
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 baseof.html.

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

Theme: Homepage

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

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

{{ .Content }}

<p>Yours sincerely.</p>
{{ end }}

Partial: HTML Head

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

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

Server Output: HTML Source

And the result is:

<html><head>
	<meta name="generator" content="Hugo 0.42.1" />
  <title>Hugo&#39;s Letter to Bulma</title>
</head>
<body>

  <div id="content">
<p>Dear Bulma,</p>

<p>There are so many things to say,
    to Bulma, Chici, and that Android 18.
    Hugo don't want to live in regrets.
    But Hugo have to go. So Hugo wrote this.</p>


<p>Yours sincerely.</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 living memory.</i></p>
  • layouts/partials/footer
<p><i>Always, still, forever.</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>Hugo&#39;s Letter to Bulma</title>
</head>
<body><p><i>My living memory.</i></p>
<div id="content">
<p>There are so many things to say,
    to Bulma, Chici, and that Android 18.
    Hugo don't want to live in regrets.
    But Hugo have to go. So Hugo wrote this.</p>


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

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.

and also open the result in:

  • http://localhost:1313/duty/

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 were two lazy men, a sleepy boy, two long haired women,
a husky with attitude, and two shotguns.
After three weeks, we finally configure herbstluftwm.

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.

Open the preview in:

  • http://localhost:1313/letters/winter

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

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 herbtsluftwm.

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 ?

Before we continue, consider have a break, and look at this cute kitten. Relax for a while, make another cup of coffe, and resume our tutorial.

adorable kitten

We are going to use CSS in theme, with Bulma official CSS. Consider continue reading [ Hugo - Bulma - CSS Introduction ].

Thank you for reading.