ahmza/blog-ahmza-com
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
a1be94a4126e3c47ee1f9ef9d682fb9c50700ee4
blog-ahmza-com/content/posts/setup-a-hugo-site.md
T

327 lines
8.2 KiB
Markdown
Raw Blame History

---
title: Setup a HUGO Site
date: 2022-12-31T22:03:52Z
author: "ahmza"
draft: false
weight:
tags: ["blog","website","web development","HUGO"]
description: "Always wanted to setup a static website. Look no further !! In this post we go over the basics of setting up a HUGO site"
canonicalURL: "https://blog.ahmza.com/Page%28/posts/setting-up-a-hugo-site.md%29"
cover:
image: "/img/hugo/feature.webp" # image path/url
alt: "HUGO Logo" # alt text
caption: "The HUGO logo" # display caption under cover
relative: false # when using page bundles set this to true
---
## **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](https://blog.ahmza.com/posts/hugo-static-site-generator/)
## **Prerequisites**
- Git
## **Installing HUGO**
[Official steps](https://gohugo.io/installation/)
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](https://brew.sh/)
``` bash
brew install hugo
```
### Arch
``` bash
sudo pacman -S hugo
```
### Confirm Installation
``` bash
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
``` bash
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.
``` bash
vim archetypes/posts.md
```
Paste the following base template
``` markdown
---
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
``` bash
mkdir content/posts
```
Create and edit a post
``` bash
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.
``` bash
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.
``` bash
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
``` yaml
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
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 !!
``` bash
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](https://blog.ahmza.com/posts/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)
Reference in New Issue View Git Blame Copy Permalink