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.
-
- themes/tutor-01
- gitlab.com/…/themes/tutor-01
$ 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
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
.
-
- themes/tutor-01/layouts/_default/baseof.html
- gitlab.com/…/layouts/_default/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.
-
- themes/tutor-01/layouts/index.html
- gitlab.com/…/layouts/index.html
{{ 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
.
-
- themes/tutor-01/layouts/partials/head.html
- gitlab.com/…/layouts/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'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>
2: Refactor
We can refactor a common layout into these three artefacts.:
-
- layouts/index.html
- gitlab.com/…/layouts/index.html
-
- layouts/partials/header
- gitlab.com/…/layouts/partials/header.html
-
- layouts/partials/footer
- gitlab.com/…/layouts/partials/footer.html
Homepage
- layouts/index.html
{{ define "main" }}
{{ .Content }}
{{ end }}
Partial: Header
- layouts/partials/header
<p><i>My living memory.</i></p>
Partial: Footer
- layouts/partials/footer
<p><i>Always, still, forever.</i></p>
Server Output: HTML Source
The result is similar:
$ curl localhost:1313 | less
<html><head>
<meta name="generator" content="Hugo 0.42.1" />
<title>Hugo'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:
-
- themes/tutor-01/layouts/partials/head
- gitlab.com/…/layouts/partials/head.html
-
- themes/tutor-01/layouts/_default/single
- gitlab.com/…/layouts/_default/single.html
-
- content/duty.md
- gitlab.com/…/content/duty.html
-
- content/letters/hello.html
- gitlab.com/…/content/letters/hello.html
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/
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/
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
Real Directory
Consider examine the tree.
$ tree content
content
├── _index.html
├── duty.md
└── letters
├── hello.html
└── winter.md
Section List
By using list.html
,
you can access http://localhost:1313/letters/.
-
- themes/tutor-01/layouts/_default/list.html
- gitlab.com/…/layouts/_default/list.html
{{ 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.
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
-
- content/letters/hello.html
- gitlab.com/…/content/letters/hello.html
+++
title = "Hello There"
tags = ["wishful", "story"]
categories = ["love"]
+++
<p>I wish you are okay over there.
I just need to say hello.</p>
and
-
- content/letters/winter.md
- gitlab.com/…/content/letters/winter.md
+++
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:
Taxonomy Item: Category
Now we can access:
Taxonomy Item: Tags
We can add any taxonomy terms as well.
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.
-
- themes/tutor-01/layouts/post/single.html
- gitlab.com/…/layouts/post/single.html
{{ 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.
Permalink
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:
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
I also use Jekyll style file naming, sorting by date, to make the article easier to find.
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.
We are going to use CSS in theme, with Bulma official CSS. Consider continue reading [ Hugo - Bulma - CSS Introduction ].
Thank you for reading.