blog-ahmza-com/content/posts/setup-a-hugo-site/index.md

---
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)