A Beginner-Friendly Tutorial for Building a Blog with Hugo, the Blowfish Theme, and GitHub Pages

中文版特供前言:

此文獻給所有想建博客卻苦於難以入門的朋友。

作為也才轉碼十個月的新手，我深知那種熟悉一個新的工具、配置一個新的環境的迷茫和挫敗感。特別是對於零coding基礎的人而言，建站這個概念可能一開始就已經讓他們望而生畏。這篇文章的閱讀時間是14分鐘，如果一步一步跟做，預估時間會在1-3小時左右，取決於configuration部分定制化的複雜程度和是否衍生閱讀。如果你花的時間更長一點也不要緊，畢竟我從頭嘗試建站+寫這篇教程用了足足將近三個星期的時間。如果你在某一步卡殼無法繼續，歡迎留言提問或者直接聯繫我。

我的方案可能不是最優最普遍的做法。相比網上搜索到的其他教程，我只用了一個GitHub repository而非兩個。GitHub Actions的自動部署也還沒搞明白，歡迎路過的大神指教😭。但我可以確保的是我將所有步驟和注意點寫得足夠詳細，並成功試驗了一遍教程所示的建站和更新流程，順便再擺個 demo版的repository供大家回頭參考。

我希望通過這篇小白級教程最小化免費建站的門檻，誘騙？ 邀請更多朋友加入我們復興博客宇宙的宏圖大業！

There are numerous ways to build a blog. You can choose popular platforms like WordPress, Medium, or Notion for simplicity, or craft static web pages using frameworks like Hugo and Hexo if you’re comfortable with a touch of coding. My personal preference leans toward the latter because it offers greater customization, cost-effectiveness, and stability. If you’re curious about selecting the right blogging tool for you, you can also check out this Chinese blog written by Douchi for valuable insights.

This article is written for people who are interested in creating a blog on their own but have minimal coding experience. It focuses on using Hugo and GitHub as the main tools for creating a blog. Hugo offers hundreds of themes with diverse styles and functions that you can explore to suit your personal needs. I would recommend the Blowfish theme, which is one of the most advanced and flexible themes in Hugo with attractive layout and detailed documentation. If you prefer to use a different theme, simply refer to the documentation of your chosen theme when it comes to theme-specific steps.

Prerequisites #

No prior background knowledge is needed. I will try to explain everything in the procedures and feel free to leave a comment if you have any questions during the setup.

However, to ensure a smooth follow-along experience, please complete the following steps before getting started:

• Sign up for a GitHub Account and generate a personal access token following this tutorial
  Copy the token and store it somewhere else, because you won’t be able to see it again on GitHub.
• Download a code editor if you don’t have one
  • Visual Studio Code, recommended for individuals with long-term coding needs
  • Sublime Text, recommended for beginners
• Install Git on your system
  • You can check whether Git is already installed by running git --version in the terminal
  • If you’re a Mac user, please install homebrew first, which will make your life much easier

For coding newbies, the installation steps are essentially copying and pasting commands into the terminal. You can find the macOS Terminal in the Utilities folder within the Applications folder, or simply search for it using Spotlight; Windows user please use PowerShell.

That’s it! You’re ready to start now.

Procedures #

1. Install Hugo #

for MacOS

• Run this command in the terminal. This will install the extended edition of Hugo.

brew install hugo

• Enter this command in the terminal to verify whether Hugo is installed successfully.

hugo version

for Windows

• Refer to Hugo Installation Instructions or this tutorial on Windows 10

2. Create a Hugo Site #

• Run the cd command to navigate to the folder where you’d like to store the code for the blog. For example, if you want to place the folder on your Desktop, the command should be:

cd ~/Desktop

cd means “change directory”, which will allow the terminal to change its current working directory to another location in the file system. ~ refers to the home directory on your system. It can be omitted if you’re already in the home directory.

If you want to place your folder in a different location, you will need to modify the code with the actual path. Learn more about the command line here for your reference.

• Run this command with your own site name to create the necessary directory structure for your website. For example, the exact command I used is hugo new site gigigatgat.

hugo new site <your-site-name>

• You should see a folder with the name <your-site-name> on your desktop or your selected location. The folder should include eight subfolders and one configuration file:

├─ archetypes
├─ assets
├─ content
├─ data
├─ hugo.toml
├─ i18n
├─ layouts
├─ static
├─ themes

ls means “list”, which will display the contents of a directory.

3. Download and Configure the Blowfish Theme #

Download the Blowfish theme #

• Run the following commands one by one. Make sure you replace <your-site-name> with the actual folder name.

cd <your-site-name>
git init
git submodule add -b main https://github.com/nunocoracao/blowfish.git themes/blowfish

• Check the themes folder in this project. The Blowfish theme should be cloned in this folder.

Set up the basic configuration files #

• In the root folder of your website project, delete the initial hugo.toml file.
• Copy all the config files from the themes/blowfish/config/_default/ folder to the config/_default/ folder in your root folder.
• After the previous steps, your folder should look as follows:

4. Dive into the Blowfish Theme #

I strongly recommend that you go through the official Blowfish Documentation Series to develop a comprehensive understanding towards the various parameters of the files and functionalities of the theme. This section serves as a quick start for a basic blog and provides some additional explanations based on the documentation.

In the theme files, you’ll see the # character frequently which is used to denote comments. Removing the # character will activate the line of code.

Modify the configuration files #

# config.toml #

Set the parameters as below and note that:

• Update the baseURL as https://<github_username>.github.io/<repository-name>. You’ll set up the repository in GitHub later. My baseURL in this case is https://avocadoTiff.github.io/gigigatgat.
• You may want to change the defaultContentLanguage to “zh-CN” for simplified Chinese or “zh-tw” for traditional Chinese. Other available languages could be found here.

# config/_default/config.toml

theme = "blowfish"
baseURL = "https://<github_username>.github.io/<repository-name>"
defaultContentLanguage = "en"

# languages.en.toml #

If your website language is English, you can just modify the following parts of the file:

# config/_default/languages.en.toml
title = "<your-site-name>"

[author]
name = "your name"
image = "img/blowfish_logo.png"
headline = "I'm only human" 
bio = "A little bit about me"
links = [
  { email = "mailto:hello@your_domain.com" },
  { instagram = "https://instagram.com/username" },
  { mastodon = "https://mastodon.instance/@username" }
]

If the defaultContentLanguage you set in the config.toml file is “zh-CN”, you should rename this file as languages.zh-CN.toml and update the code as below:

# config/_default/languages.zh-CN.toml

languageCode = "zh-CN"
languageName = "Chinese"
weight = 1
title = "<your-site-name>"

[params]
  displayName = "中文"
  isoCode = "zh-CN"
  rtl = false
  dateFormat = "2 January 2006"
  # logo = "img/logo.png"

[author]
name = "Your name"
image = "img/blowfish_logo.png"
headline = "I'm only human"
bio = "A little bit about me"
links = [
  { email = "mailto:hello@your_domain.com" },
  { instagram = "https://instagram.com/username" },
  { mastodon = "https://mastodon.instance/@username" }
]

• The images should be placed in the site’s assets/img/ folder.
• In the [params] section
  • displayName will only be displayed when the language switch function is used
  • logo represents the site’s logo
• In the [author] section
  • image is your profile image
  • headline will be displayed on the homepage
  • bio will be displayed in the articles if you set showAuthor = true in the params.toml
  • links are the social media icons with links that you’d like to share

# menus.en.toml #

Refer to the code below for basic menu settings:

# config/_default/menus.en.toml

 [[main]]
  name = "Posts"
  pageRef = "posts"
  weight = 10

[[main]]
  name = "Tech"
  parent = "Posts"
  pageRef = "categories/tech"
  weight = 20

[[main]]
  name = "Kitchen"
  parent = "Posts"
  pageRef = "categories/kitchen"
  weight = 30

[[main]]
  name = "About"
  pageRef = "about"
  weight = 70

[[main]]
  identifier = "github"
  pre = "github"
  url = "your-url-link"
  weight = 100

 [[footer]]
   name = "Tags"
   pageRef = "tags"
   weight = 10

 [[footer]]
   name = "Categories"
   pageRef = "categories"
   weight = 20

• name specifies the text will be displayed in the menu link.
• pageRef specifies where the Hugo page would be directed to. You need to have corresponding pages in the content folder to be linked to.
• parent is used for nested menus.
• identifier and pre are used to place icons in the menu.
• url is for linking to external URLs.
• weight is used to sort the menu links in ascending order. The lowest weight will be displayed as the first item in the menu.

Similar with above, rename the file as menus.zh-CN.toml if simplified Chinese is your site’s defaultContentLanguage.

# params.toml #

This file specifies a wide range of theme parameters that you can use to customize your site. To ensure a smooth start, I suggest you modify the following lines in the file:

# config/_default/params.toml

mainSections = ["posts"]
disableImageOptimization = false

defaultBackgroundImage = "/img/ocean.jpg"
defaultFeaturedImage = "/img/ocean.jpg"

highlightCurrentMenuArea = true
smartTOC = true
smartTOCHideUnfocusedChildren = false

[header]
  layout = "fixed" # valid options: basic, fixed, fixed-fill, fixed-fill-blur

[homepage]
  layout = "background" # valid options: page, profile, hero, card, background, custom
  # homepageImage = "/img/ocean.jpg" # used in: hero, and card
  showRecent = true
  showRecentItems = 10
  showMoreLink = false
  showMoreLinkDest = "posts"
  cardView = false
  cardViewScreenWidth = false
  layoutBackgroundBlur = true # only used when layout equals background

[article]
  showTableOfContents = true
  showTaxonomies = true

• Again, the images should be placed in the site’s assets/img/ folder. For now you can copy all the files from the themes/blowfish/exampleSite/assets/ folder to the assets folder in your root folder for convenience.
• mainSections is related to the content you’d like to display in the Recent articles on the homepage.
• Refer to the Blowfish Configuration article for more details and experiment with the rest parameters later.

Add pages to your site #

- Content Organization #

All content is placed within the content folder. Below is an example of the content structure based on the above menu:

.
├── assets
│   └── img
│       └── ocean.jpg
|       └── logo.png
├── config
│   └── _default
├── content
│   ├── _index.md
│   ├── about.md
│   ├── categories
│   │   ├── _index.md
│   │   ├── tech
│   │   │   └── _index.md
│   │   └── kithen
│   │       └── _index.md
│   ├── tags
│   │   └── _index.md
│   └── posts
│       ├── _index.md
│       └── first-post
│           ├── featured.jpg
│           └── index.md
└── themes
    └── blowfish

- Add Content #

There are two ways to add content in the site project: you can either use the GUI (Graphical User Interface) or the CLI (Command Line Interface).

• GUI: Simply create new folders, copy and paste files, edit them in your code editor. The example files can be found at themes/blowfish/exampleSite/content/ folder.

• CLI: Copy default.md from themes/blowfish/exampleSite/archetypes/ folder to replace the initial one in the archetypesfolder in your root directory. Use the terminal to run this Hugo command to create a new page:

hugo new content posts/my-first-post/index.md

This command will create an index.md file in the content/posts/my-first-post folder based on the front matter template defined in the archetypes folder. If you open the file in your code editor, it will now look like this:

---
title: "Index"
date: 2023-11-02T16:21:18-04:00
draft: true
---

- Branch pages #

Branch pages include the homepage, section listings, and taxonomy pages. The filename for this content type is _index.md. As you can see in the above content structure, the  content/_index.md file defines the content of the homepage, and the content/posts/_index.md file defines the content of the posts page. In this example, I only specified the title, description, and whether the posts list on this page would be grouped by year:

---
title: "Posts"
description: "All posts"
groupByYear: true
---

- Leaf pages #

Leaf pages are single pages that don’t contain a list of sub-pages. It is named as index.md in the corresponding post folder for an individual article page or about.md for an about page. My index.md file in the content/posts/Getting Started with Entity Framework Core in Visual Studio folder looks like this:

---
title: "Getting Started with Entity Framework Core in Visual Studio"
date: 2023-10-24
draft: false
description: "How to use Entity Framework Core to connect database in Visual Studio"
slug: "how to use Entity Framework Core"
tags: ["tutorial", "code", "ASP.NET", "VisualStudio"]
categories: ["Tech"]
---

Entity Framework Core is a powerful tool for simplifying database integration with web applications...

• draft determines whether this content is ready to be published or not. If it is set to true, the content will not be visible when you build the site.
• slug is used in the URL path when the content is published. In my case, the link for this post would be https://tiffahahahu7.github.io/gigigatgat/posts/how-to-use-entity-framework-core/.
• tags and categories are defined here to be displayed on the Tags and Categories pages.
• The body of the post is written in markdown, an easy-to-use text formatting language. I strongly recommend familiarizing yourself with it.

For more explanations, you can refer to Blowfish’s Content Examples and Front Matter.

5. Preview and Publish #

• Run this command in the terminal to preview the site in your browser, with the given URL address http://localhost:1313/ or http://localhost:1313/<repository-name> depending on your baseURL.

hugo server

If you site doesn’t render your posts correctly, double-check the rules for content organization.

• Modify the content and configuration until you’re satisfied with the preview. Tags and Categories may not be updated immediately. In this case, try to exit by pressing Ctrl + C and restart hugo server to see the changes.
• In the root directory, run the following command to publish the site. It will create a public folder with the entire static files necessary for your website.

hugo

6. How to Deploy the Site with GitHub Pages #

• Go to your GitHub Account and create a new repository. The repository name should be in accordance with your baseURL in the config.toml file.

• Run the following commands to add the GitHub repository as a remote repository and push all the local files to it. Remember to replace with your own remote URL.

git init
git add .
git commit -m "first commit"
git branch -M main
git remote add origin https://github.com/avocadoTiff/gigigatgat.git
git push -u origin main

• Change your directory into public. Run the following commands to connect to the remote repository and create a gh-pages branch

cd public
git init
git remote add origin https://github.com/avocadoTiff/gigigatgat.git
git checkout --orphan gh-pages

• Run the following commands to upload the files to gh-pages branch

git add .
git commit -m "upload site files"
git push -u origin gh-pages

• In the Settings > Pages, ensure that the GitHub Pages site is being built from the gh-pages branch

• Wait for a few minutes and refresh the page. You’ll see a message like this: Your site is live at https://avocadotiff.github.io/gigigatgat/.

🎉 Congrats! Your blog is now live online!

7. How to Update Your Blog #

Once you make any modification or add new posts to your blog, you can update your blog by three steps:

• In the root directory, review you site preview by executing the command hugo server and then run the command hugo to update the site files in the public folder.
• Ensure that you’re still in the in the root directory and run the following commands:

git add .
git commit -m "add new posts"
git push -u origin main

• Change your directory into public by the command cd public and run the following commands:

git add .
git commit -m "add new posts"
git push -u origin gh-pages

This is the most basic way of updating your blog manually. You can also automate the deployment process with GitHub Actions, which is a more advanced and efficient method. I’m still in the process of learning GitHub Actions, and I’ll keep you updated if I come across an easier way to comprehend and make use of this tool.

Thank you for reading this far! I hope this tutorial can help you in building your personal blog smoothly. If you have any questions during the process, please feel free to reach out. I’m more than happy to help create another blog in the universe.

Reference #

• Hugo Documentation
• Blowfish Documentation Series
• Create a static website with Hugo and Host it with Github Pages