Building a Blog using Hugo
Introduction
In this post, we will be creating a simple blog using Hugo, a really fast static site generator and host it for free on GitHub Pages. This guide is Linux focused, but on Windows you can use WSL and follow along if you wish. The final site created is the one you will be reading this post on.
Installing Hugo
I run Arch Linux, where Hugo is available in the community repository. For other distros, checkout their official documentation.
1sudo pacman -S hugo
Next, change to the directory where you wish to create the website related files.
1cd ~/Developer
2# hugo new site <name of directory which hugo will create>
3hugo new site parimal7.github.io
4cd parimal7.github.io
5:'
6The directory structure should look like this:
7.
8├── archetypes
9│ └── default.md
10├── config.toml
11├── content
12├── data
13├── layouts
14├── public
15├── static
16└── themes
17'
18# Commit files to git version control
19git init
20git add .
21git commit -m 'Added initial hugo files'
You can find information on the files and folders created by Hugo on this documentation page.
Installing Hugo theme
Themes for Hugo can be found on https://themes.gohugo.io/. I will be using Archie theme for my site, instructions for setting up a theme should be similar for most of them.
1# Run this in the root directory which we created earlier
2# i.e. parimal.codes for me
3git submodule add https://github.com/athul/archie.git themes/archie
I will copy and edit the example config given on the example website:
1baseURL = "https://parimal7.github.io/"
2languageCode = "en-us"
3title = "Parimal Prasoon"
4theme="archie"
5copyright = "© Parimal Prasoon"
6# Code Highlight
7pygmentsstyle = "monokai"
8pygmentscodefences = true
9pygmentscodefencesguesssyntax = true
10
11#disqusShortname = "yourDisqusShortname"
12
13#paginate=5 # articles per page
14
15[params]
16 mode="toggle" # color-mode → light,dark,toggle or auto
17 useCDN=false # don't use CDNs for fonts and icons, instead serve them locally.
18 #subtitle = "Software Engineer @ Bank of America"
19 mathjax = true # enable MathJax support
20 katex = true # enable KaTeX support
21
22# Social Tags
23
24[[params.social]]
25name = "GitHub"
26icon = "github"
27url = "https://github.com/parimal7"
28
29[[params.social]]
30name = "LinkedIn"
31icon = "linkedin"
32url = "http://linkedin.com/in/parimal7"
33
34[[params.social]]
35name = "Email"
36icon = "mail"
37url = "mailto:[email protected]"
38
39# Main menu Items
40
41[[menu.main]]
42name = "Posts"
43url = "/posts"
44weight = 2
45
46[[menu.main]]
47name = "About Me"
48url = "/about"
49weight = 3
50
51[[menu.main]]
52name = "Resume"
53url = "/parimal_prasoon.pdf"
54weight = 5
To test the look and feel of the current site, run
1# In root directory
2hugo server
3# This will serve static files from memory at http://localhost:1313/
When the static sites are being served on localhost, any changes to files or static files will get reflected almost immediately. Quite fast and frictionless way to check how changes look before you deploy them.
Deploying to Github Pages using Github Actions
1# Run this in the root directory
2hugo
The above command creates all the static HTML files which we will publish into a public directory. The public directory can then be published to whichever hosting site you wish. Hugo has a good summary for the same: https://gohugo.io/hosting-and-deployment/hosting-on-github/
- Creata a GitHub account if you don’t have one.
- Create a new repository <your-github-username>.github.io
- Create the below file at .github/workflows/gh-pages.yml (i.e. in your root site directory)
- If you have a custom domain (i.e. https://parimal.codes for me), also create a CNAME file under static directory with your domain name as it’s only content.
1name: GitHub Pages
2
3on:
4 push:
5 branches:
6 - master # Set a branch name to trigger deployment
7 pull_request:
8
9jobs:
10 deploy:
11 runs-on: ubuntu-20.04
12 permissions:
13 contents: write
14 concurrency:
15 group: ${{ github.workflow }}-${{ github.ref }}
16 steps:
17 - uses: actions/checkout@v3
18 with:
19 submodules: true # Fetch Hugo themes (true OR recursive)
20 fetch-depth: 0 # Fetch all history for .GitInfo and .Lastmod
21
22 - name: Setup Hugo
23 uses: peaceiris/actions-hugo@v2
24 with:
25 hugo-version: '0.85.0'
26
27 - name: Build
28 run: hugo --minify
29
30 - name: Deploy
31 uses: peaceiris/actions-gh-pages@v3
32 # If you're changing the branch from main,
33 # also change the `main` in `refs/heads/main`
34 # below accordingly.
35 if: ${{ github.ref == 'refs/heads/master' }}
36 with:
37 github_token: ${{ secrets.GITHUB_TOKEN }}
38 publish_dir: ./public
Finally, we can push our code to GitHub.
- git remote add origin https://github.com/Parimal7/parimal7.github.io.git
- git branch -M master
- git push -u origin master
This will push all our code to the master branch. Due to certain limitations of above Github action (check here), we need to do a couple of more steps before you can see your site at <username>.github.io:
First, make another commit and push to GitHub.
Second, in Github settings for your repository, i.e.
(github.com/<username>/<username>.github.io/settings/pages)
Pick the Source branch as gh-pages.
Finally, you will be able to find your site hosted on <username>.github.io.