I set up my first Hugo-generated website on GitHub through the following steps. I wrote this file to help whose familiar with GitHub and command line and want to build their static website using Hugo by following simple command lines without detailed explanations.

I’m using a Mac mini m1.

Instll Hugo

If you have Homebrew installed on your Mac, just run:

1

brew install hugo

The Hugo will be installed on the Mac.

Create a new Hugo site

I used two repos for my website; one is called portfolio used to store my original files, and another is the susanpeng.github.io repo used to store the deployed code, static files.

Under selected folder (say Desktop folder), clone the portfolio repo to the local computer:

1

git clone https://github.com/susanpeng/portfolio.git

Get into the local repo’s folder:

1

cd portfolio

Create a new Hugo site:

1

hugo new site portfoliosite

This command creates a site with the name portfoliosite. It also creates a folder portfoliosite under the folder portfolio.

Get into the portfoliosite:

1

cd portfoliosite

You can see folders, such as archetypes, content, layouts, themes, data, and static, as well as a config.toml file.

Pick and download a theme you like

Put the theme under the themes folder:

1

cd themes

Go to Hugo site to pick a theme. You can copy or clone the picked theme into the themes folder.

Change your site’s config file

In the example folder under the picked-theme folder (portfoliosite/themes/picked-theme/exampleSite), you can see a config.toml file; copy its content to your site’s confit.toml file under your site folder (portfoliosite). Then modify your config.toml file to set:

baseURL = “https://susanpeng.github.io/"

title = “The name of your site”

theme=“The name of your picked theme”

Preview of the Hugo site

1

hugo server

This command will start a development server locally on port 1313.

Open your browser, and put “http://localhost:1313/ in the address bar. You will see your Hugo site. To stop the Hugo server, press Ctl+c and press return.

Write your content

Create a new .md file in the post folder:

1

hugo new post/my-first-post.md

Add some content in the .md file. You should see your Hugo site changed, and the content of my-first-post.md appears on the site.

Add Submodule to another repo

We want to store the static assets (deployed code) in another repo called susanpeng.github.io.

Note: You must create the repo susanpeng.github.io and push to main at least once before continuing.

Run the following command to add the submodule:

1

git submodule add -b main https://github.com/susanpeng/susanpeng.github.io.git public

“public” is the folder under portfoliosite folder; it stores all static files generated by Hugo. After adding “public” as the submodule of the repo susanpeng.github.io, you can push the files (or changes) under public to susapeng.github.io. And then you can see your site at https://susanpeng.github.io/.

When you get into the public folder, you can see that the folder is connected to the repo susanpeng.github.io:

1
2
3
4

cd public
git remote -v
origin	https://github.com/susanpeng/susanpeng.github.io.git (fetch)
origin	https://github.com/susanpeng/susanpeng.github.io.git (push)

You can see that the origin points to the repo susanpeng.github.io, because you are in the submodule of the repo susanpeng.github.io.

To generate static files:

1
2

cd .. # back to portfoliosite folder
hugo -t theme-name

All static files will automatically go to the local public folder.

To put the static files to GitHub:

1
2
3
4

cd public
git add .
git commit -m "put your static assets on the GitGub: repo username.github.io"
git push origin main

Now, you can see your new site from https://susanpeng.gitgub.io.

If you are following this how-to to build your first Hugo site on GutHub, use your GitHub username to replace susanpeng in this article.