Build a Blog Website Using Hugo and PaperMod

This tutorial is focused on the windows operating system environment. For Linux and Mac users, you can follow the same steps but make sure to use the commands and tools that are suited for your operating system

This tutorial also assumes you have basic terminal knowledge, nothing complex, i will provide all the commands you need in a simple copy-paste fashion

Download Essential Tolls

We need to download 3 things to get started;

Follow the instructions mentioned in the links above to setup and install all the 3 tools. Then verify if the installation is successful.

hugo version
git version
go version

Project Setup

Create website files

Choose a location to setup your website files. For instance, i will use the Documents folder to install the project files.

cd Documents
# replace salaamdevblogs with your website name
hugo new site salaamdevblogs
# you can use a yaml configuration as well, for this tutorial, this is preferred.
hugo new site salaamdevblogs --format yaml
cd salaamdevblogs

Setup a Version Control

Next we will push our project files to GitHub.

Create a New repository on GitHub with the same name as your website name. Sign up if you do not have an account on GitHub
Go back to the terminal and set up your username and email for git

git config --global user.name "Name"
git config --global user.email "[email protected]"

Initialize the repository

git init # initialize the repository
git add . # add all files to the staging area
git commit -m "first commit" # add a message for the new commit
git branch -M main # choose the main branch

push the code to the remote repository. (Optional)

# change the url link below to your repository link
git remote add origin https://github.com/salaamdev/salaamdevblogs.git
git push -u origin main # send the files to github

Downloading a Hugo Theme

Install a theme from the Hugo Themes. My personal recommended themes for blogging are as follows:

For the sake of this tutorial, we will use the PaperMod theme. Follow the instructions mentioned in the theme page to install a theme, the best and recommended way to install themes is through the git submodule. Run the below commands in the terminal.

git submodule add --depth=1 https://github.com/adityatelange/hugo-PaperMod.git themes/PaperMod
git submodule update --init --recursive
git submodule update --remote --merge

Setting up the blog

open the config.yaml or hugo.yaml file in your project folder with your notes editor. Then add the following to the end.

theme: ["PaperMod"]

To run your website, type the following in the terminal

hugo
hugo server -t PaperMod

Then head to http://localhost:1313/ to see your website. At this point you will see a blank page. The rest of this tutorial will focus on setting up the blog elements and different stylings.

Adding new blogs

To add your first blog post, go to your website folder > content folder > create a folder called posts > add .md files here For example, Each blog has properties to add properties such as reading time, author and the date the blog was written, add the following at the top of the .md file

---
title: "My 1st post"
date: 2020-09-15T11:30:03+00:00
# weight: 1
# aliases: ["/first"]
tags: ["first"]
author: "Me"
# author: ["Me", "You"] # multiple authors
showToc: true
TocOpen: false
draft: false
hidemeta: false
comments: false
description: "Desc Text."
canonicalURL: "https://canonical.url/to/page"
disableHLJS: true # to disable highlightjs
disableShare: false
disableHLJS: false
hideSummary: false
searchHidden: true
ShowReadingTime: true
ShowBreadCrumbs: true
ShowPostNavLinks: true
ShowWordCount: true
ShowRssButtonInSectionTermList: true
UseHugoToc: true
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
    hidden: true # only hide on current single page
editPost:
    URL: "https://github.com/<path_to_repo>/content"
    Text: "Suggest Changes" # edit text
    appendFilePath: true # to append file path to Edit link
---

# add a heading here
your content goes here

Try pasting the above content in yourwebsitefolder\content\posts\firstpost.md. Then run the website with the command provided above

Configuring your blog site

Hugo creates a configuration file usually with the name hugo.toml or hugo.yaml. Since we are using the PaperMod theme, then probably the file name wll be a .yaml Open this file with your text editor and paste the following

baseURL: "https://salaam.dev/"
title: SalaamDev
paginate: 5
theme: PaperMod

enableRobotsTXT: true
buildDrafts: false
buildFuture: false
buildExpired: false

minify:
  disableXML: true
  minifyOutput: true

params:
  env: production # to enable google analytics, opengraph, twitter-cards and schema.
  title: SalaamDev
  description: "Quality Tech Blogs and Tutorials"
  keywords: [Blog, Tech, Devops, Cybersecurity, Cloud, Code, Tutorials]
  author: Abdisalam Hassan
  # author: ["Me", "You"] # multiple authors
  images: ["<link or path of image for opengraph, twitter-cards>"]
  DateFormat: "January 2, 2006"
  defaultTheme: auto # dark, light
  disableThemeToggle: false

  ShowReadingTime: true
  ShowShareButtons: true
  ShowPostNavLinks: true
  ShowBreadCrumbs: true
  ShowCodeCopyButtons: false
  ShowWordCount: true
  ShowRssButtonInSectionTermList: true
  UseHugoToc: true
  disableSpecial1stPost: false
  disableScrollToTop: false
  comments: false
  hidemeta: false
  hideSummary: false
  showtoc: false
  tocopen: false

  assets:
    # disableHLJS: true # to disable highlight.js
    # disableFingerprinting: true
    favicon: "<link / abs url>"
    favicon16x16: "<link / abs url>"
    favicon32x32: "<link / abs url>"
    apple_touch_icon: "<link / abs url>"
    safari_pinned_tab: "<link / abs url>"

  label:
    text: "Home"
    icon: /favicon-16x16.png
    iconHeight: 35

  # profile-mode
  profileMode:
    enabled: false # needs to be explicitly set
    title: ExampleSite
    subtitle: "This is subtitle"
    imageUrl: "<img location>"
    imageWidth: 120
    imageHeight: 120
    imageTitle: my image
    buttons:
      - name: Posts
        url: posts
      - name: Tags
        url: tags

  # home-info mode
  homeInfoParams:
    Title: "Hi there \U0001F44B"
    Content: Welcome to my blog

  socialIcons:
    - name: x
      url: "https://x.com/"
    - name: stackoverflow
      url: "https://stackoverflow.com"
    - name: github
      url: "https://github.com/"

  analytics:
    google:
      SiteVerificationTag: "XYZabc"
    bing:
      SiteVerificationTag: "XYZabc"
    yandex:
      SiteVerificationTag: "XYZabc"

  cover:
    hidden: true # hide everywhere but not in structured data
    hiddenInList: true # hide on list pages and home
    hiddenInSingle: true # hide on single page

  editPost:
    URL: "https://github.com/<path_to_repo>/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
    limit: 10 # refer: https://www.fusejs.io/api/methods.html#search
    keys: ["title", "permalink", "summary", "content"]
menu:
  main:
    - identifier: categories
      name: categories
      url: /categories/
      weight: 10
    - identifier: tags
      name: tags
      url: /tags/
      weight: 20
    - identifier: example
      name: example.org
      url: https://example.org
      weight: 30
# Read: https://github.com/adityatelange/hugo-PaperMod/wiki/FAQs#using-hugos-syntax-highlighter-chroma
pygmentsUseClasses: true
markup:
  highlight:
    noClasses: false
    # anchorLineNos: true
    # codeFences: true
    # guessSyntax: true
    # lineNos: true
    # style: monokai

Download Essential Tolls#

Project Setup#

Create website files#

Setup a Version Control#

Downloading a Hugo Theme#

Setting up the blog#

Adding new blogs#

Configuring your blog site#