Basics of HUGO

2024-09-04

5 minute read

blog , personal , tecnology

Introduction

“Hugo is one of the most popular open-source static site generators. With its amazing speed and flexibility, Hugo makes building websites fun again.”

Installation

Hugo is multi platform, so the installation depends on what SO do you use, in this example I Show how to install in Arch-linux because it’s easy.

1sudo pacman -S hugo

Creating a New Site

Initialize a New Hugo Site

This is the command in order to create a hugo site,

1hugo new site my-website.org

my-website.org: is the name of the directory that hugo is going to create, and where all the files are going to be.

Directory Structure Overview

 1$ tree -d my-website.org
 2
 3my-website.org
 4├── archetypes
 5├── assets
 6├── content
 7├── data
 8├── i18n
 9├── layouts
10├── static
11└── themes

Initialize an empty git repository.

This is very useful because in case of mess, you can easily roll back.

1git init

Creating Content

Creating a New Post

This is the command to create post within HUGO:

1hugo new content content/posts/my-first-post.md

Hugo creates a my-first-post.md in the content/posts/ directory, open it with your editor, you must see this content in the file:

1+++
2title = 'My First Post'
3date = 2024-01-14T07:07:07+01:00
4draft = true
5+++

Notice the draft value in the front matter is true. By default, Hugo does not publish draft content when you build the site. Learn more about draft, future, and expired content.

Add some Markdown to the body of the post, but do not change the draft value.

 1+++
 2title = 'My First Post'
 3date = 2024-01-14T07:07:07+01:00
 4draft = true
 5+++
 6## Introduction
 7
 8This is **bold** text, and this is *emphasized* text.
 9
10Visit the [Hugo](https://gohugo.io) website!

Working with Themes

To install a theme is basically download it from GitHub, you can find more themes here.

Downloading and Installing a Theme

In this guide we are going to use PaperMod theme, so we need to install it througt various ways.

As a submodule (recommended).

1git submodule add --depth=1 https://github.com/adityatelange/hugo-PaperMod.git themes/PaperMod
2git submodule update --init --recursive # needed when you reclone your repo (submodules may not get cloned automatically)

Simply clone.

1git clone https://github.com/adityatelange/hugo-PaperMod themes/PaperMod --depth=1

Keep in mind that if you clone the repository you must delete the .git folder inside the theme, because is going to have conflicts when you try to push your site.

The next ones I never used, but you can go to the HUGO documentation for read more about these.

Expand Method 3 - Download an unzip
Hugo module

Configuring the Theme & see it in action.

Finally set theme as PaperMod in your site config, hugo.toml or config.toml

1theme = "PaperMod"

Once you do this you can verify if the site applied the theme correctly by running the hugo server:

1hugo server

Now, in your browser, open localhost:1313, and you should see your site with the proper theme applied.

Configuration example for PaperMod theme.

This is a basic configuration template for PaperMod theme:

  1baseURL = 'https://example.org/'
  2languageCode = 'en-us'
  3title = 'My New Hugo Site'
  4theme = "PaperMod"
  5
  6copyright = "[PaperMod Contributors](https://github.com/adityatelange/hugo-PaperMod/graphs/contributors)"
  7paginate = 5
  8enableInlineShortcodes = true
  9enableRobotsTXT = true
 10buildDrafts = false
 11buildFuture = false
 12buildExpired = false
 13enableEmoji = true
 14pygmentsUseClasses = true
 15mainsections = [ "posts", "papermod" ]
 16
 17[minify]
 18disableXML = true
 19
 20[languages.en]
 21languageName = "English"
 22weight = 1
 23
 24  [languages.en.taxonomies]
 25  category = "categories"
 26  tag = "tags"
 27  series = "series"
 28
 29[[languages.en.menu.main]]
 30name = "Archive"
 31url = "archives"
 32weight = 5
 33
 34[[languages.en.menu.main]]
 35name = "Posts"
 36url = "posts/"
 37weight = 10
 38
 39[outputs]
 40home = [ "HTML", "RSS", "JSON" ]
 41
 42[params]
 43env = "production"
 44description = "Theme PaperMod - https://github.com/adityatelange/hugo-PaperMod"
 45author = "Theme PaperMod"
 46defaultTheme = "auto"
 47ShowShareButtons = true
 48ShowReadingTime = true
 49displayFullLangName = true
 50ShowPostNavLinks = true
 51ShowBreadCrumbs = true
 52ShowCodeCopyButtons = true
 53ShowRssButtonInSectionTermList = true
 54ShowAllPagesInArchive = true
 55ShowPageNums = true
 56ShowToc = true
 57images = [ "images/papermod-cover.png" ]
 58
 59  [params.profileMode]
 60  enabled = false
 61  title = "PaperMod"
 62  imageUrl = "#"
 63  imageTitle = "my image"
 64
 65    [[params.profileMode.buttons]]
 66    name = "Archives"
 67    url = "archives"
 68
 69    [[params.profileMode.buttons]]
 70    name = "Tags"
 71    url = "tags"
 72
 73  [params.homeInfoParams]
 74  Title = "PaperMod's Demo"
 75  Content = """
 76?? Welcome to demo page of Hugo's theme PaperMod!
 77- **PaperMod**  is designed to be clean and simple but fast and responsive theme with useful feature-set that enhances UX.
 78- Feel free to show your support by giving us a star ?? on GitHub and sharing with your friends and social media .
 79- PaperMod is based on theme [Paper](https://github.com/nanxiaobei/hugo-paper/tree/4330c8b12aa48bfdecbcad6ad66145f679a430b3).
 80"""
 81
 82  [[params.socialIcons]]
 83  name = "github"
 84  title = "View Source on Github"
 85  url = "https://github.com/adityatelange/hugo-PaperMod"
 86
 87  [[params.socialIcons]]
 88  name = "Discord"
 89  title = "Join discord community"
 90  url = "https://discord.gg/ahpmTvhVmp"
 91
 92  [[params.socialIcons]]
 93  name = "X"
 94  title = "Share PaperMod on X/Twitter"
 95  url = "https://x.com/intent/tweet/?text=Checkout%20Hugo%20PaperMod%20%E2%9C%A8%0AA%20fast,%20clean,%20responsive%20Hugo%20theme.&url=https://github.com/adityatelange/hugo-PaperMod&hashtags=Hugo,PaperMod"
 96
 97  [[params.socialIcons]]
 98  name = "KoFi"
 99  title = "Buy me a Ko-Fi :)"
100  url = "https://ko-fi.com/adityatelange"
101
102  [params.assets]
103  disableHLJS = true
104
105[markup.goldmark.renderer]
106unsafe = true
107
108[markup.highlight]
109noClasses = false
110
111[services.instagram]
112disableInlineCSS = true
113
114[services.twitter]
115disableInlineCSS = true

Building the Site

Generating the Static Site

At this point we need to generate the static we site, the most basic command to publish it is just run hugo in the terminal inside the root of the project. So you notice that a public folder is now created, if you look inside, you’ll find all the html files, and everything to deploy as a web page.

Set specific folder to export your site.

If you don’t want to have your publish site in the public folder, you can set another path to export it instead of the public folder by adding this line at top of your hugo.toml configuration file:

1publishDir = "/path/to/export/"
2#example
3publishDir = "~/my-site.org/"

Conclusion

With all the context before, you may be able to start your web site, blog, etc. As you read, is very simple to have a very nice and useful static web-page, the “hard” part is to select the theme.

The next step is to publish your web to a custom server or on github, gitlab, codeberg pages.

Preparing for Deployment.
Deploying to a Web Server or Hosting Service.