My Blog Site

Jan 21, 2022 - 3 min read - 486 words

Installing Hugo

Hugo is a static site generator written in go. We can install hugo easily using any of the package manager available for the different platforms. Since I am using macOS the below command worked for me. We can get the detailed installation steps from the hugo quick-start guide.

brew install hugo

Creating a new Hugo Site

Created a new repository which will act as the source repository for the blog site. And use the new hugo command to generate a new site.

hugo new site <SITE NAME>

Cloning the new repository, and creating a new hugo site in the cloned repository, --force option is used to force the site creation when the directory is not empty. -f yml option is used to create the hugo repository using the config.yml instead of config.toml.

hugo new site . --force -f yml

Updating the default archetypes

Archetypes contain the default template which will be used while creating new posts/blogs etc using the hugo command. Hence, updating the below config file to the default.md. Read more on archetypes.

---
title: "{{ replace .Name "-" " " | title }}"
date: {{ .Date }}
tags: []
author: ["Me"]
showToc: false
TocOpen: false
hidemeta: true
comments: false
summary: ""
description: ""
disableHLJS: true # to disable highlightjs
disableShare: false
disableHLJS: false
hideSummary: false
searchHidden: true
ShowReadingTime: true
ShowBreadCrumbs: true
ShowPostNavLinks: 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
draft: true
---

Add a theme for the Hugo site

We will be using the hugo-PaperMod theme for our blog site. The themes can be imported by adding the themes as sub-modules to the existing repository. Read more quick-start.

git submodule add https://github.com/adityatelange/hugo-PaperMod.git themes/PaperMod --depth=1

Update the config file

We need to update the config file with the needed configuration for the theme.

baseURL: "your base URL"
languageCode: en-us
title: "title"
theme: "PaperMod"
paginate: 5

params:
  env: production # to enable google analytics, opengraph, twitter-cards and schema.
  title: title
  description: ""
  keywords: []
  author: [Me]
  DateFormat: "January 2, 2006"
  defaultTheme: auto # dark, light, auto
  disableThemeToggle: false

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

  # home-info mode
  homeInfoParams:
    Title: "Title"
    Content: >
      - Lorem Ipsum is simply dummy text of the printing and typesetting
        industry. Lorem Ipsum has been the industry's standard dummy text
        ever since the 1500s, when an unknown printer took a galley of type
        and scrambled it to make a type specimen book. It has survived not
        only five centuries, but also the leap into electronic typesetting,
        remaining essentially unchanged.

      - It was popularised in the 1960s with
        the release of Letraset sheets containing Lorem Ipsum passages, and
        more recently with desktop publishing software like Aldus PageMaker
        including versions of Lorem Ipsum.

  socialIcons:
    - name: email
      url: "mailto://abc@gmail.com"
    - name: twitter
      url: "https://twitter.com/"
    - name: stackoverflow
      url: "https://stackoverflow.com"
    - name: github
      url: "https://github.com/"
    - name: gitlab
      url: "https://gitlab.com/"
    - name: linkedin
      url: "https://linkedin.com/"

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

menu:
  main:
    - identifier: Posts
      name: Posts
      url: /posts/
      weight: 20
    - identifier: tags
      name: Tags
      url: /tags/
      weight: 20

Local testing using hugo server

For local testing of the static site we can use the local server which comes with the Hugo for testing.

hugo server

or

hugo server -D

Adding a new post to the blog/posts site

We can use the new command to create a new post. It will create a new post named my-first-post in the content/posts directory and the new file which is created will have the base template as of default.md archetypes created and updated earlier.

hugo new posts/my-first-post.md

Generate the static files for deployment

We can use the hugo command for generating/building the static site which can later be used for deployment.

hugo

Please refer the hugo documentation for all the flags and options or refer the man pages for hugo.

Implementing the CI/CD pipeline for automatic build & deployment

We will be using the Github actions to build and deploy the static site in Github pages.

Generate Github tokens

We need to generate a new personal access token from Github Tokens and use the same token in the repository which will be pushing the static build site for deployment to the external repository. Please refer this site.

Create the workflow

We need to enable the github actions for automatically deploying the site. We will be deploying the site to an external repository. Please refer actions-gh-pages.

name: project-build-deployment

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

  workflow_dispatch:

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - name: repository-checkout
        uses: actions/checkout@v2

      - name: update-submodule-theme-repo
        run: git submodule update --init --recursive

      - name: install-hugo
        uses: peaceiris/actions-hugo@v2

      - name: build-project
        run: hugo -D --minify

      - name: deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
          personal_token: ${{ secrets.TOKEN }}
          external_repository: XXXXXX/YYYYYYYY
          publish_dir: ./public
          user_name: XXXXXX
          user_email: XXXXXX@XXXXXX.com
          publish_branch: main

Enable the github pages for the external repository

Enable the github pages in the <PROJECT>/Settings/Pages.

Conclusion

We just need to update the markdown files for the new posts and push it. And the CI/CD pipeline will automatically build and deploy the static site.