Hugo Troubleshoot
Build and BaseURL
When using css or fonts in our <head>, we use.
<link rel="stylesheet" href="/css/bootstrap.min.css">
When we test the site on local, we use hugo serve -w to watch the process. However if we already defined baseURL in config.toml, like I have defined:
basURL = "http://dyang.io"
You may counter problems with links locally, one way to fix this is when we run hugo serve, we can modified basURL using -b command.
hugo serve -w -b "localhost:1313"
Hosting on Github Pages
GitHub Pages naturally support Jekyll, However it’s not natively support Hugo. We can create one repository for Jekyll and that’s it. Our source code will be automatically generated by GitHub Pages. With Hugo we need to build the website ourselves. And upload as gh-pages branch. It’s really not very convenient to put content and source code in separate repository. Hugo website provide nice way to Hosting on GitHub Pages in single repository with worktree gh-pages branch. However, I’m not hosting a project website. I’m host my website on username.github.io which require our contents sit in master branch to work. Therefore, I modified the method. Delete master branch and use dev as default branch store all of our source code. And then create a worktree master branch to store all our website.
Preparations
Create dev branch to replace master branch first. And delete master branch. In this case my upstream is origin. And put public in .gitignore.
git checkout --orphan master
git reset --hard
git commit --allow-empty -m "initializing"
git push origin master
git checkout dev
Building
rm -rf public
git worktree add -B master public origin/master
hugo
cd public && git add --all && git commit -m "update pages" & cd ..
git push origin master
Repeat
In osx or linux you can find bash script updating is above tutorials from Hugo. Meanwhile I create this cmd script file for windows user. When updating website to github, just run following update.cmd
@echo off
echo Update public to master branch...
echo Deleting old publication
rm -rf public
mkdir public
git worktree prune
rm -rf .git/worktrees/public/
echo Checking out master branch into public
git worktree add -B master public origin/master
echo Removing existing files
rm -rf public/*
echo Generating site
hugo
echo Updating master branch
cd public && git add --all && git commit -m "update pages" & cd ..
git push origin master
One last thing
When using customized domain, you can put a CNAME file in statis folder. This will automatically put CNAME in root.
Keep empty folders
Since Hugo generated a lot of folders and I’m not using al of the folders. Some are empty, and will not be updated to GitHub Pages. One way to solve this is put a README.md in each folders. Another way, is just put a file .gitkeep in each folders. Since there are not much to ‘read’ in a empty folder.