ahmza
0759020677
imported workspace into obsidian linted files organized yaml frontmatter unified yaml value formats removed yaml front matter no longer needed
351 lines
7.7 KiB
Markdown
351 lines
7.7 KiB
Markdown
---
|
|
title: Setup a HUGO Site
|
|
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
|
|
tags:
|
|
- blog
|
|
- HUGO
|
|
- web
|
|
- development
|
|
- website
|
|
author: ahmza
|
|
date: 2022-12-31
|
|
draft: false
|
|
weight:
|
|
featureimage: feature.webp
|
|
lastmod:
|
|
---
|
|
|
|
## **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](https://blog.ahmza.com/posts/hugo-static-site-generator/)
|
|
|
|
## **Prerequisites**
|
|
|
|
- Git
|
|
|
|
## **Installing HUGO**
|
|
|
|
[Official steps](https://gohugo.io/installation/)
|
|
|
|
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](https://brew.sh/)
|
|
|
|
```bash
|
|
brew install hugo
|
|
```
|
|
|
|
### _Arch_
|
|
|
|
```bash
|
|
sudo pacman -S hugo
|
|
```
|
|
|
|
### Confirm Installation
|
|
|
|
```bash
|
|
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
|
|
|
|
```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
|
|
|
|
> pick an editor of your choice. **I use NVIM BTW**
|
|
|
|
```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_
|
|
|
|
```
|
|
➜ 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 - 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
|
|
|
|
```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
|
|
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 !!
|
|
|
|
```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
|
|
- The _HUGO_ built in server
|
|
- webp + webm (still need to add this)
|
|
- shortcodes (still need to add this)
|