Introduction#
HUGO is a static site generator, a tool that allows us to pre-compile our website into static HTML, CSS and JS. The main benefit of an ssg is speed. A Static site takes a lot less time to load than a site that uses databases.
For more information on HUGO read my other post Hugo Static Site Generator
Prerequisites#
- Git
Installing HUGO#
The HUGO binary is used to initialize our site then create posts etc… Below are the steps for MacOS and Arch based Linux distros.
MacOS#
- Install homebrew
brew install hugo
Arch#
sudo pacman -S hugo
Confirm Installation#
hugo version
Create your site#
This assumes choices for you, i.e the theme used.
The settings in this guide will mimic the base config of my site
hugo new site -f yml <your-sitename>
cd <your-sitename>
git init
git submodule add --depth=1 https://github.com/adityatelange/hugo-PaperMod.git themes/PaperMod
echo "theme: 'PaperMod'" >> config.yml
Create Content#
We will now begin adding new content to our website. Lets create our first post.
Lets start by creating a template for our posts.
vim archetypes/posts.md
Paste the following base template
---
title: { { replace .TranslationBaseName "-" " " | title } }
date: { { .Date } }
author: "<author>"
draft: true
weight:
tags: [""]
description: ""
canonicalURL: "{{ .Page | absURL }}"
cover:
image: "<image path/url>" # image path/url
alt: "<alt text>" # alt text
caption: "<text>" # display caption under cover
relative: false # when using page bundles set this to true
---
## **Introduction**
## **Conclusion**
If the posts folder does not exist, create it
mkdir content/posts
Create and edit a post
pick an editor of your choice. I use NVIM BTW
hugo new posts/<post-name>.md
vim content/posts/<post-name>.md
Start the server#
Now that we have created our site, installed a theme and created a post lets start the server.
hugo server -D
The -D flag tells hugo server to build drafts. (notice how we have a draft: option in our posts template.) Of course once you have finished a post you set draft to false like so draft: false
➜ hugo server -D
Start building sites …
hugo v0.109.0+extended darwin/arm64 BuildDate=unknown
| EN
-------------------+-----
Pages | 10
Paginator pages | 0
Non-page files | 0
Static files | 0
Processed images | 0
Aliases | 2
Sitemaps | 1
Cleaned | 0
Built in 12 ms
Watching for changes in /home/ahmza/prj/ahmza/{archetypes,assets,content,data,layouts,static,themes}
Watching for config changes in /home/ahmza/prj/ahmza/config.yml
Environment: "development"
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
Notice the second line to the bottom. Web Server… This line gives you a localhost URL that you can use in your browser to view your site locally.
Configure Site#
Open the config.yml file in a text editor.
vim config.yml
Important changes you need to make
- baseURL - External URL. In my case. https://blog.ahmza.com
- title - Title of your site.
Here is my config.yml with bits redacted so you can fill them in
baseURL: "<your sites URL>"
title: <your site title>
paginate: 5
theme: PaperMod
enableRobotsTXT: true
buildDrafts: false
buildFuture: false
buildExpired: false
enableEmoji: true
googleAnalytics: <Google Analytics Tag>
minify:
disableXML: true
minifyOutput: true
outputs:
home:
- HTML
- RSS
- JSON
params:
env: production # to enable google analytics, opengraph, twitter-cards and schema.
title: <title>
description: "<description>"
keywords: [Blog, Portfolio, PaperMod]
author: <author>
images: ["<link or path of image for opengraph, twitter-cards>"] #Change this
DateFormat: "January 2, 2006"
defaultTheme: auto # dark, light
disableThemeToggle: false
ShowReadingTime: true
ShowShareButtons: false
ShowPostNavLinks: false
ShowBreadCrumbs: true
ShowCodeCopyButtons: true
ShowWordCount: true
ShowRssButtonInSectionTermList: true
UseHugoToc: false
disableSpecial1stPost: false
disableScrollToTop: false
hideFooter: false
comments: false
hidemeta: false
hideSummary: false
showtoc: true
tocopen: false
assets:
# disableHLJS: true # to disable highlight.js
# disableFingerprinting: true
favicon: "/img/favicon.png"
favicon16x16: "/img/favicon.png"
favicon32x32: "/img/favicon.png"
apple_touch_icon: "/img/favicon.png"
safari_pinned_tab: "/img/favicon.png"
label:
text: "<Home>"
icon: /img/favicon.png
iconHeight: 35
# profile-mode
profileMode:
enabled: true # needs to be explicitly set
title: "Welcome \U0001F44B"
subtitle: "<subtitle>"
imageUrl: "/img/favicon.png"
imageWidth: 120
imageHeight: 120
imageTitle: "my image"
buttons:
- name: posts
url: posts
- name: archive
url: archives
- name: tags
url: tags
# home-info mode
homeInfoParams:
Title: "Welcome \U0001F44B"
Content: "subtitle"
socialIcons:
- name: LinkedIn
url: "https://linkedin.com/in/"
- name: gitlab
url: "https://gitlab.com/"
cover:
hidden: false # hide everywhere but not in structured data
hiddenInList: false # hide on list pages and home
hiddenInSingle: false # hide on single page
editPost:
URL: "https://gitlab.com/<user>/<repo>/-/blob/main/content"
Text: "Suggest Changes" # edit text
appendFilePath: true # to append file path to Edit link
# for search
# https://fusejs.io/api/options.html
fuseOpts:
isCaseSensitive: false
shouldSort: true
location: 0
distance: 1000
threshold: 0.4
minMatchCharLength: 0
keys: ["title", "permalink", "summary", "content"]
menu:
main:
- identifier: posts
name: posts
url: /posts/
weight: 1
- identifier: archive
name: archive
url: /archives/
weight: 10
- identifier: tags
name: tags
url: /tags/
weight: 20
- identifier: search
name: search
url: /search/
weight: 30
# Read: https://github.com/adityatelange/hugo-PaperMod/wiki/FAQs#using-hugos-syntax-highlighter-chroma
pygmentsUseClasses: true
markup:
highlight:
noClasses: false
codeFences: true
guessSyntax: true
# lineNos: true
Run the server again#
Run the server and check out your hard work. Change settings make posts etc. Have fun !!
hugo server -D
Publish your site#
Once you are happy with your site, you may want to publish it to the internet.
In the next post Publishing your HUGO site I will cover a basic method of publishing your site as well as a more complicated but automated workflow that I use.
Conclusion#
Through this post you have learned to create your own HUGO site as well as create and edit posts. We also learned about
- archetypes
- Mark posts as drafts
- The HUGO built in server
- webp + webm (still need to add this)
- shortcodes (still need to add this)