Static Site Generator
Last edited: September 26, 2024 - 4 minutes read
Description
Content
Hugo is a static site generator. It is used to create website content using markdown instead of having to write html. You can read more about hugo on it’s website.
If you are curious about how hugo was used in the implementation of this website you can also check out my github repository.
1. Creating the website
After you have installed hugo through your package manager of choice, you can create a new hugo site by running in your terminal:
$ hugo new site my-website
This will create a my-website
directory with the following hierarchy:
.
├── archetypes
│ └── default.md
├── config.toml
├── content
├── data
├── layouts
├── public
├── static
└── themes
The most important directories here are content/
, which stores your website’s content as markdown files, and static/
which stores any other assets you wish to have on your website, such as images or files.
2. Creating a theme
Change directory into my-website/
and run:
$ hugo new theme my-theme
This will create a my-theme/
directory inside themes/
with the following hierarchy:
.
├── LICENSE
├── archetypes
│ └── default.md
├── layouts
│ ├── 404.html
│ ├── _default
│ │ ├── baseof.html
│ │ ├── list.html
│ │ └── single.html
│ ├── index.html
│ └── partials
│ ├── footer.html
│ ├── head.html
│ └── header.html
├── static
│ ├── css
│ └── js
└── theme.toml
The theme controls exactly how your website will look and function. Your content will be transformed into html based on the rules you define here.
In hugo, there are two main types of pages:
- Lists
- Singles
which are created depending on the structure of your content/
directory.
Let’s imagine a directory structure like:
.
├── about.md
└── post
├── 1st-post.md
├── 2nd-post.md
└── 3rd-post.md
Here about.md
, and each of the posts inside post/
are all single pages.
post/
itself is a list.
We can control how these pages are displayed by editing the files single.html
and list.html
inside layouts/_default/
.
Let’s do so.
Edit single.html
so that the content is as follows:
{{ define "main" }}
<div>{{ .Content }}</div>
{{ end }}
and list.html
like so:
{{ define "main" }}
<ul>
{{ range.Pages }}
<li><a href="{{ .RelPermalink }}">{{ .Title }}</a></li>
{{ end }}
</ul>
{{ end }}
List pages will now show an unordered list with links to their single pages, and single pages will show their respective content.
Finally lets edit index.html
inside layout/
in order to customize our main page.
<a href="/about">about</a>
<a href="/post">posts</a>
3. Configuring the website
We are done with our simple theme.
Now we need to edit our config.toml
file in order to use the theme we have just created.
Change directory back into my-website/
and run:
$ echo "theme = 'my-theme'" >> config.toml
4. Adding content
You now have a fully functional hugo website and are ready to start posting content. Let’s write the about page and a helloworld post.
$ hugo new about.md
$ hugo new post/helloworld.md
This will create a about.md
file inside content/
and a helloworld.md
file inside content/post/
.
Both files will have content similar to this:
---
title: "About"
date: 2022-07-22T14:24:31+01:00
draft: true
---
Let’s add some markdown to both.
Edit about.md
:
---
title: "About"
date: 2022-07-22T14:24:31+01:00
draft: true
---
This is the about page.
Edit helloworld.md
:
---
title: "Helloworld"
date: 2022-07-22T14:24:31+01:00
draft: true
---
# Helloworld
this is an example.
5. Live preview
We are now ready to see the results using a local server provided by hugo. Run:
$ hugo server -D
where the -D
option is used so drafts are also shown.
A server will be started (likely on localhost:1313). Here is the result:
At this point you can continue editing the all the files mentioned to your liking. Everytime you save your changes the website will automatically reload.
6. Publishing the website
Once you’re satisfied with your changes, you can generate the static website by running:
$ hugo
This will output all the static files you need into public/
.