Preface
This article is intended for beginner.
Goal: Show Minimal Homepage in Hugo
When you are done with install, this is what to do.
Source Code
You can download the source code of this article here.
Here, I present a Hugo Tutorial, step by step, for beginners.
0: Install Hugo
Yeps, array start from zero.
Installing Hugo is easy. No dependency issue, as go compile it with static linking. Most distro has Hugo package. This should not be hard for most people. Just follow the official documentation:
Do not worry about screenshot below. This is just illustration, in my linux box. You can also use Hugo with Windows.
After install, let’s get the guidance started.
1: Source Structure
It only takes a few steps.
1. First
After install, make sure that, Hugo run from CLI.
$ hugo version
Hugo Static Site Generator v0.42.1-4172A835E544B867F292579019D0597439E596BA linux/amd64 BuildDate:
2. Second
Make a directory for your project.
$ mkdir tutor-hugo
$ cd tutor-hugo
3. Other Step
Make a skeleton for your project.
$ hugo new site .
Congratulations! Your new Hugo site is created in /media/Works/sites/tutor-hugo.
The result of that command above is a newly created directory and files as below.
.
├── archetypes
│ └── default.md
├── config.toml
├── content
├── data
├── layouts
├── static
└── themes
4. See what is in there
All these directories and files are empty, except these two artefacts: config.toml, and archetypes/default.md.
-
- config.toml
- gitlab.com/…/config.toml
baseURL = "http://example.org/"
languageCode = "en-us"
title = "My New Hugo Site"
As a beginner, you only need to care about config.toml. But there are other file, as well as below.
-
- archetypes/default.md
- gitlab.com/…/archetypes/default.md
---
title: "{{ replace .TranslationBaseName "-" " " | title }}"
date: {{ .Date }}
draft: true
---
I rarely use archetypes.
2: Generated Structure
Hugo use in memory mapping, in contrast with Jekyll, that use _site directory for server. Jekyll have to copy images for each change, it has performance impact, if you have a lot of images. Hugo use some kind of memory mapping, thus no performance impact.
Public Directory
Sometimes, you need to debug. As an SSG, Hugo can dump the generated output to a directory. Hugo use public directory as default.
$ hugo
| EN
+------------------+----+
Pages | 3
Paginator pages | 0
Non-page files | 0
Static files | 0
Processed images | 0
Aliases | 0
Sitemaps | 1
Cleaned | 0
Total in 16 ms
Default XML
The command above will generate, static site.
$ exa public --tree
public
├── categories
│ └── index.xml
├── index.xml
├── sitemap.xml
└── tags
└── index.xml
It has no index.html yet. Because we have not define them yet. Hugo, as default, generate a few .xml files.
High Performance Server
On daily basis you issue hugo server, instead of just hugo command.
$ hugo server
| EN
+------------------+----+
Pages | 3
Paginator pages | 0
Non-page files | 0
Static files | 0
Processed images | 0
Aliases | 0
Sitemaps | 1
Cleaned | 0
Total in 6 ms
Watching for changes in /media/Works/sites/tutor-hugo/{content,data,layouts,static}
Watching for config changes in /media/Works/sites/tutor-hugo/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
Check the Site
Now, the Hugo server is running. But no content yet. You can check the site using curl
<pre>
</pre>
3: Minimal Homepage
In order to have a working index.html you need this two artefacts.
-
- content/_index.html
- gitlab.com/…/content/_index.html
-
layout/index.html
Content
Consider this is, as our very first content.
$ cat content/_index.html
<p>There are so many things to say.
I don't want to live in regrets.
So I wrote this for my love.</p>
Or alternatively:
$ cat content/_index.md
There are so many things to say.
I don't want to live in regrets.
So I wrote this for my love.
You can choose either of these two above format. But you can not have both index.
Layout
Here we have our very first Go html/template/code> tag.
$ cat layouts/index.html
<p>Dear love,</p>
{{ .Content }}
<p>Sincerely yours.</p>
Sorry for my english, It is just an example.
Server Output: Browser
Now check on browser
Compare Source And Generated
You can examine how this works, by comparing the source directory, and generated directory.
$ exa --tree
.
├── archetypes
│ └── default.md
├── config.toml
├── content
│ └── _index.html
├── data
├── layouts
│ └── index.html
├── public
│ ├── categories
│ │ └── index.xml
│ ├── index.html
│ ├── index.xml
│ ├── sitemap.xml
│ └── tags
│ └── index.xml
├── static
└── themes
.
Server Output: HTML Source
Check also the source with curl. And compare with above figure.
Remove Temporary Example
Now we are safely to remove layouts/index.html in root. We need to remove to avoid conflict with the next part, the layout inside theme. We are going to use make all layouts in theme.
$ rm layouts/index.html
What is Next ?
Consider continue reading [ Hugo Layout ].
Thank you for reading.