Build Personal Blog with Hugo

Hugo, blog

Install Hugo

Install the latest version from Hugo Github releases page. E.g. download the *.deb file and install by dpkg -i *.deb.

Or use the official installation Guide (not recommended)

Step 1: Create the Required Repositories

On GitHub, create two repositories, both with the Add a README file option selected:

• Blog source file repository: Store web source files used to generate the blog site (e.g., name it blog-resources).
• Pages repository: Used to store the generated web files and can be accessed via a URL (name it <username>.github.io, where <username> is your GitHub account name. Official Documentation)

Step 2: Create Blog Files Using Hugo Commands

Using blog-resources as an example for the source file repository name:

1. Clone blog-resources to your local machine.
2. Navigate to the blog-resources directory and use the Hugo command to create the overall website file structure: hugo new site <blog-name>, replacing <blog-name> with your desired name, e.g., woods-blog.
3. The repository`s file structure and their main purposes at this stage are as follows:

    1├── README.md           # Automatically added README when creating the repo
    2└── woods-blog          # Blog folder name, matching what was created using Hugo in the previous step
    3    ├── archetypes
    4    ├── config.toml     # Custom configuration file for the blog site, to be edited further
    5    ├── content         # Blog content folder, where blog documents, images, etc., are stored
    6    ├── data
    7    ├── layouts
    8    ├── resources
    9    ├── static
   10    └── themes          # Themes folder, to install Hugo themes further
   

Step 3: Add Theme Files and Configure

1. Browse Hugo themes and choose a theme.
2. Theme introductions typically provide installation instructions; you can follow those. However, I have encountered errors when installing some themes. Here, I`ll introduce the theme I chose, Mainroad, for reference.
3. Navigate to the blog file path blog-resources/woods-blog and add the theme files using git submodule like this:

   1git submodule add https://github.com/vimux/mainroad.git themes/mainroad
   

4. If added successfully, the blog-resources/woods-blog/themes directory will contain the theme named Mainroad:

   1└── themes
   2   └── Mainroad # The name of the installed theme
   

5. In blog-resources/woods-blog/themes/Mainroad/exampleSite, copy the content and static folders and the config.toml file to blog-resources/woods-blog, overwriting existing files.
6. Configure the blog-resources/woods-blog/config.toml file. Key items to check include:

   1# Ensure the URL is the URL of the Pages repository you created, with a trailing slash
   2baseurl = "https://<username>.github.io/"
   3#The theme is the name of the installed theme
   4theme = "mainroad"
   

Step 4: Test the Blog and Publish as HTML

1. Start the Hugo server: hugo server and preview the blog theme at http://localhost:1313/.
2. To add blog documents, you can create new .md documents in blog-resources/woods-blog/content for testing. The Hugo server updates in real-time for preview.
3. Publish the blog as HTML web pages by running hugo in the blog-resources/woods-blog/ directory.
4. If the publishing is successful, a public folder will be added in blog-resources/woods-blog/ to store the HTML web page files.

Step 5: Push HTML Files to the Pages Repository

1. Go to the blog-resources/woods-blog/public directory and set it as a Pages repository:

   1# Initialize a new Git repository
   2git init
   3# Create the main branch
   4git checkout -b `main`
   5# Add the SSH of the Pages repository to your local repository
   6git remote add origin git@github.com:<username>/<username>.github.io.git
   

2. Push the local files to the repository:

   1# Synchronize local and remote commits
   2git pull --rebase origin main
   3# Add all local changes
   4git add .
   5# Commit with relevant description
   6git commit -m "commit information, e.g., add blog template"
   7# Push to the remote repository
   8git push origin main
   

3. Enter the URL in your browser to view the blog at https://<username>.github.io/, which may take a few minutes to become accessible.

Next Steps

Push the blog-resources repository to GitHub.

Reference

• https://cuttontail.blog/blog/create-a-wesite-using-github-pages-and-hugo/#14-%E8%BF%90%E8%A1%8C%E7%8E%AF%E5%A2%83