Hugo Blog and Host it with Github Pages

Prerequists

Windows Platform
Hugo Engine
- One of the most popular open-source static site generators.
Visual Studio Code (Optional)
- A lightweight but powerful source code editor.
Markdown
- A lightweight markup language for creating formatted text using a plain-text editor.
Git (Optional)
- A free and open source distributed version control system.
GitHub
- GitHub is an internet hosting service for software development and version control using Git.

Download the Hugo

Download the latest Hugo from https://github.com/gohugoio/hugo/releases.
It’s a portable package and can be launched directly after extracting, doesn’t need the installation process.

NOTICE: There are many different types of packages to run on multiple platforms, use the following command to check which one should be downloaded.
echo %PROCESSOR_ARCHITECTURE%
Prefer to download the extended version.

Create a new website

Extract the downloaded package above and run the following command pattern to create a new website.

For example:

cd C:\Users\xxx\Downloads\hugo_extended_0.111.3_windows-amd64
C:\Users\xxx\Downloads\hugo_extended_0.111.3_windows-amd64\hugo.exe new site FirstSite

Output:

Congratulations! Your new Hugo site is created in C:\Users\xxx\Downloads\hugo_extended_0.111.3_windows-amd64\FirstSite.

Just a few more steps and you're ready to go:

1. Download a theme into the same-named folder.
   Choose a theme from https://themes.gohugo.io/ or
   create your own with the "hugo new theme <THEMENAME>" command.
2. Perhaps you want to add some content. You can add single files
   with "hugo new <SECTIONNAME>\<FILENAME>.<FORMAT>".
3. Start the built-in live server via "hugo server".

Visit https://gohugo.io/ for quickstart guide and full documentation.

Download a Hugo theme

Go to https://themes.gohugo.io and choose a theme to download.
Take iTheme as an example:

Go to https://github.com/floyd-li/hugo-theme-itheme.
Click Code button to expend download menu.
Choose Download ZIP to download the theme package.

Optional: Also can use the Git command to download the theme.
git clone https://github.com/floyd-li/hugo-theme-itheme.git themes/itheme

Once download done, extract package if download by Download ZIP.

Apply a Hugo theme

Copy the theme folder under FistSite folder created above, the directory hierarchy is following:

├───archetypes
├───assets
├───content
├───data
├───layouts
├───public
├───static
└───themes
    └───hugo-theme-itheme-master
        ├───archetypes
        ├───exampleSite
        │   └───content
        │       └───posts
        ├───images
        ├───layouts
        │   ├───partials
        │   ├───posts
        │   ├───taxonomy
        │   └───_default
        │       └───_markup
        └───static
            ├───css
            └───js

Typically, the theme author will provide an exampleSite folder that includes sample contents using the created theme.

If no such folder, the creation of the content using the theme needs to refer to the corresponding theme description site.

Copy all of files in exampleSite folder to FistSite folder, the directory hierarchy is following:

├───archetypes
├───assets
├───content
│   └───posts
├───data
├───layouts
├───public
├───static
└───themes
    └───hugo-theme-itheme-master
        ...

Choose “Replace the config.toml in the desination” to overwrite the default one.

Run the following command to start the server locally:

C:\Users\xxx\Downloads\hugo_extended_0.111.3_windows-amd64\hugo.exe server -D

If the below errors occur:

Error: module “iTheme” not found; either add it as a Hugo Module or store it in “C:\\Users\\xxx\\Downloads\\hugo_extended_0.111.3_windows-amd64\\FirstSite\\themes”.: module does not exist

Open the config.toml file and check the value of the theme property, then make the folder name of this theme consistent with this value.

For example: Rename the folder name from hugo-theme-itheme-master to iTheme.

Output (if previous configurations are correct):

Start building sites …
hugo v0.111.3-5d4eb5154e1fed125ca8e9b5a0315c4180dab192+extended windows/amd64 BuildDate=2023-03-12T11:40:50Z VendorInfo=gohugoio

                   | ZH-HANS
-------------------+----------
  Pages            |      58
  Paginator pages  |       1
  Non-page files   |       0
  Static files     |       5
  Processed images |       0
  Aliases          |       1
  Sitemaps         |       1
  Cleaned          |       0

Built in 152 ms
Watching for changes in C:\Users\xxx\Downloads\hugo_extended_0.111.3_windows-amd64\FirstSite\{archetypes,assets,content,data,layouts,static,themes}
Watching for config changes in C:\Users\xxx\Downloads\hugo_extended_0.111.3_windows-amd64\FirstSite\config.toml
Environment: "development"
Serving pages from memory
Running in Fast Render Mode. For full rebuilds on change: hugo server --disableFastRender
Web Server is available at //localhost:1313/ (bind address 127.0.0.1)
Press Ctrl+C to stop

Go to http://localhost:1313 to check if the theme works well and press Ctrl + C to stop the local server.

Create a new post

Run the following command to create a new markdown post file:

C:\Users\WangZhon\Downloads\hugo_extended_0.111.3_windows-amd64\hugo.exe new post/FirstPost.md

Output:

Content "C:\\Users\\WangZhon\\Downloads\\hugo_extended_0.111.3_windows-amd64\\FirstSite\\content\\post\\FirstPost.md" created

The FirstPost.md is created in content/post/ folder.

Open the newly added post file with the Visual Studio Code and start drafting the blog content by the markdown grammar.

The modification can be continued during the local server is running, the Hugo engine will automatically rebuild the site if files are changed.

Hosting the site with GitHub Pages

Create a GitHub account (Optional)

NOTICE: It is necessary to have a GitHub account to continue the hosting progress.

Run the following command to generate the static site files.

C:\Users\WangZhon\Downloads\hugo_extended_0.111.3_windows-amd64\hugo.exe

The generated files are saved in the public folder, empty this folder before generating.

Create a new repository on GitHub and finish the following configuration:

Name the repository as <ProfileName>.github.io.

Go go the newly created repository and click Settings, and Click Pages menu in the left side.

Select Deploy from a branch in the Souce option of the Build and deployment section.

Select main and root options in the Branch option.

NOTICE: Refresh the page and Your site is live... message will appear at the top of the page.

Run the following command to clone the new repository to local disk.

git clone https://github.com/xxx/<RepoName>.git public

The files in public folder will be used to commit to the GitHub server.

Prefer to select another directory to clone. Copies all files in public folder to the specified folder.

Copy all files in the public folder to the specified folder created above.
Run the following commands one by one to push the site contents to GitHub server.

git add .  
git commit  
git push

NOTICE: If any errors occur with above three commands, please refer to the Git command guide.

Visit the blog site.

https://<ProfileName>.github.io