Learn and Discover Open Source with Daily Genuine Experience. From Coding, Front End, Back End, Database, and Static Site Generator.
 
 
ssg  


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.

Table of Content

Here, I present a Hugo Tutorial, step by step, for beginners.

  • Preface: Table of Content

  • 1: Source Structure

  • 2: Generated Structure

  • 3: Minimal Homepage

  • What is Next ?


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.

Hugo: Install

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: 

Hugo: Version

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.

Hugo: New Site

The result of that command above is a newly created directory and files as below.

$ tree

.
├── archetypes
│  └── default.md
├── config.toml
├── content
├── data
├── layouts
├── static
└── themes

Hugo: New Site Tree

4. See what is in there

All these directories and files are empty, except these two artefacts: config.toml, and archetypes/default.md.

baseURL = "http://example.org/"
languageCode = "en-us"
title = "My New Hugo Site"

Hugo: Config

As a beginner, you only need to care about config.toml. But there are other file, as well as below.

---
title: "{{ replace .TranslationBaseName "-" " " | title }}"
date: {{ .Date }}
draft: true
---

Hugo: archetypes

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

Hugo: generate public

Default XML

The command above will generate, static site.

$ exa public --tree
public
├── categories
│  └── index.xml
├── index.xml
├── sitemap.xml
└── tags
   └── index.xml

Hugo: tree public

It has no index.html yet. Because we have not define them yet. Hugo, as default, generate a few .xml files.

Hugo: index.xml

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

Hugo: hugo server

Check the Site

Now, the Hugo server is running. But no content yet. You can check the site using curl

$ curl http://localhost:1313/

<pre>
</pre>

Hugo: localhost:1313


3: Minimal Homepage

In order to have a working index.html you need this two artefacts.

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

Hugo: Page 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

Hugo: Tree to compare directory

.

Server Output: HTML Source

Check also the source with curl. And compare with above figure.

Hugo: curl on terminal

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.