Building a Personal Website with Hugo and GitHub
Note: The following tutorial applies only to building a personal website on Windows, using Hugo and GitHub.
–
Step 1: Install and configure Hugo
1. Download Hugo
Download the latest version of Hugo: Click to download
2. Create the directory
Once downloaded, extract it. Create a Hugo folder on drive D, and place the extracted hugo.exe file in the bin directory.
3. Configure the environment variables –> System variables
After downloading, you need to configure the path. Press the Win+S key combination, type path, and click “Edit the system environment variables”. A “System Properties” dialog will pop up. Click “Environment Variables” in the lower-right corner of the dialog, and an “Environment Variables” dialog will appear. In the “System variables (S)” section at the bottom, double-click the “Path” row. An “Edit environment variable” dialog will appear. Click the “New” button and paste in the path to hugo.exe (something like: D:\Hugo\bin). Then click “OK” one by one — three clicks in total.
4. Verify
To verify that the installation and configuration succeeded, press the Win+R key combination. A “Run” dialog will appear. Type “CMD” in the dialog and click OK. A “Command Prompt” window will appear. Type D：, press Enter, then type cd hugo/bin, then type hugo version. If you see something like: hugo v0.110.0-e32a493b7000000763c3b79623952e6254000000+extended windows/amd64 BuildDate=2023-01-17T12:16:09Z VendorInfo=gohugoio, the installation was successful.
That completes the installation and configuration of Hugo.
–
Step 2: Install Visual Studio Code
Download the latest version of Visual Studio Code: Click to download
Once downloaded, just double-click to install. Installing it on drive D is recommended. Click OK and Next all the way through, and keep the default configuration.
That completes the installation and configuration of Visual Studio Code.
–
Step 3: Install and configure Git
1. Download Git
Download the latest version of Git: Click to download
Once downloaded, just double-click to install. Installing it on drive D is recommended. Click OK and Next all the way through, and keep the default configuration.
2. Configure Git
In the “Command Prompt” window from the steps above, type git config --global user.name "Jack" (please replace "Jack" with your own username) and press Enter.
Then type git config --global user.email "[email protected]" (please replace "[email protected]" with your own email address) and press Enter.
That completes the installation and configuration of Git.
–
Step 4: Initialize the website and configure the theme
1. Initialize the website
Here we take creating the personal website repository folder on drive D as an example. In the “Command Prompt” window, type D：, press Enter, then type hugo new site jack.com (please replace "jack.com" with the repository name you want to use; English is recommended), then press Enter.
If you see text similar to the following, the website was initialized successfully.
Congratulations! Your new Hugo site is created in D:\jack.com.
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.
Go to drive D and open the jack.com. folder. You will see 7 folders and one file, which represent:
- archetypes: stores the front matter templates applied to md files created with the hugo command
- content: stores content pages, such as the Blog
- layouts: stores the styles that define the website; styles written under the layouts folder override same-named styles in the layouts of the installed theme
- static: stores all static files, such as images
- data: stores other data Hugo uses when creating the site
- public: stores the static web pages generated by Hugo
- themes: stores theme files
- config.toml: the website configuration file
2. Configure the theme
Here we use the hugo-bearblog theme used by this site as an example. For more Hugo themes, click here to download.
Click to preview this site’s theme
Click to download this site’s theme. If the download link no longer works, please click here to download it.
Once downloaded, extract it to get the hugo-bearblog-master folder. Copy the hugo-bearblog-master folder directly into the jack.com/themes directory created on drive D in the previous step, and rename the copied hugo-bearblog-master folder to hugo-bearblog (i.e., remove “master” — this step is essential, otherwise the theme may not be recognized later).
Then go into the exampleSite folder under the hugo-bearblog directory, and copy the content, static, and config.toml files from the exampleSite folder directly into the jack.com directory on drive D. Note: a “Replace or skip files” dialog will pop up — choose “Replace the files in the destination”. This is highly recommended, as it solves many problems.
3. Verify that the theme was installed successfully
In the “Command Prompt” window, type D：, press Enter, then type cd jack.com
Then type hugo server, and text similar to the following will appear.
Start building sites …
hugo v0.110.0-e32a493b7826d02763c3b79623952e625402b168+extended windows/amd64
BuildDate=2023-01-17T12:16:09Z VendorInfo=gohugoio
…………………………………………
Built in 38 ms
Watching for changes in D:\reardon.com\{archetypes,assets,content,data,layouts,static,themes}
Watching for config changes in D:\reardon.com\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 http://localhost:1313/ (bind address 127.0.0.1)
–
Once the above text appears successfully, type http://localhost:1313/ in your browser to open the example page of the theme website.
That completes the website initialization and theme configuration.
–
Step 5: Use Visual Studio Code to customize the website information and write website content
Now we will use the Visual Studio Code installed earlier. Using Visual Studio Code directly to write content and adjust theme parameters is highly recommended.
Double-click to open Visual Studio Code. An initial setup interface will appear; just choose the defaults.
Click the File button in the upper-right corner, click “Open Folder”, then select the jack.com folder on drive D and click “Select Folder”. You can then modify the example pages and add new pages.
From there, you can customize the website information and write your own website content according to your needs.
Click here for reference information on the theme.
Click here for the official Hugo documentation.
–
Step 6: Deploy the finished site to GitHub
1. Create a GitHub repository
Register a GitHub account. Once registered, click the “+” next to your profile avatar in the upper-right corner, and click New repository.
On the page that opens, fill in the repository name.
You can fill in a description in the Description field.
Check Public to make it a public repository. (It is checked by default, so no change is needed.)
Check Add a README file. This will set the main branch as the repository’s default main branch, which is important when committing and pushing website content later.
3. Initialize Git locally and connect it to the GitHub repository
After completing the steps above, in the “Command Prompt” window, type D：, press Enter, then type cd jack.com, press Enter, then type cd public to enter the public folder.
Then type git init to initialize the local repository.
Then type git remote add origin https://github.com/ReardonYang/ReardonYang.github.io.git. After this step, you will be prompted to enter your GitHub account and password.
After completing the steps above, it is recommended to sync data from the GitHub repository once. Type git pull origin master.
4. Generate the website pages locally and sync them to the GitHub repository
In the “Command Prompt” window, type D：, press Enter, then type cd jack.com, press Enter. Then type hugo and press Enter. At this point, page files will be generated in the public folder; these generated files are the ones we want to upload to the GitHub repository. (From now on, each time you update the website, it is recommended to delete the generated pages in the public directory, regenerate the pages following this step, and then upload.)
Once that is done, in the “Command Prompt” window, type git add ., then type git commit -m "Add your upload notes here".
Finally, type git push -u origin master to sync the files to the GitHub repository.
Step 7: Done
That completes all the steps.
Open the repository you created on GitHub, go to the Setting page, then click Pages on the left side of the page to find the address of the website you built. Click the address link to visit it.
Common commands:
Initialize: git init
Link the local repository to GitHub: git remote add origin https://github.com/ReardonYang/ReardonYang.github.io.git
Get files from the GitHub repository: git pull origin master
Stage the updates: git add .
Add a note: git commit -m "Add your upload notes here"
Sync the files to the GitHub repository: git push -u origin master