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 using such methods 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 what we will use throughout the creation of our project to initially setup our site then create posts etc… This step will vary depending on your operating system and distribution. I will show 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 a few steps 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
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
You will be shown something like the following:
➜ 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 - this is the URL your site will be accessed externally. In my case. https://blog.ahmza.com
- title - is the title of your page.
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 (expand on this
- The hugo built in server (still need to add this))
- webp + webm (still need to add this)
- shortcodes (still need to add this)