This is a quick-start guide to setting up Hugo with GitHub pages, since it took too much effort to find the full instructions anywhere else. It should hopefully take you ~15 minutes to complete the entire thing.
-
Make two GitHub repositories, i.e., https://github.com/ehotinger/blog and https://github.com/ehotinger/ehotinger.github.io - the first repository is for the unrendered Hugo content, and the second is for the rendered content. Note: you could just have one repository as your GitHub page, but this approach allows you to easily switch off GitHub pages if you want to.
-
Install Hugo from the releases page.
-
Run
hugo new site blog
to make the skeleton of your blog website. -
Install a theme you want. I chose
hyde
initially and just didcd themes
andgit clone https://github.com/spf13/hyde
. More info about themes here. -
Update the
config.toml
generated from step 2 to use the theme. I.e, addtheme = "hyde"
to the toml. -
Make a new post using
hugo new posts/installing-hugo.md
or something simimlar. Edit its content to be whatever you want. -
Run
hugo server -D
and browse tohttp://localhost:1313/
to make sure the theme and content are as you expected. You can peruse the other files to edit the description of the website or refer to this website’s source code to see additional options. See also the “front matter” link at the bottom of this post. -
Now add a
git remote
for theblog
repository that you made in step 1.git remote add origin https://github.com/ehotinger/blog
. You can then do agit fetch origin
andgit merge origin/master
. Make sure you havepublic
folder with arm -rf public/
and then you’re free togit push -u origin master
. -
Link the two repos you made in step one together. I made a simple git submodule that links Hugo’s
public
subfolder to the second repository you made in the first step. I.e.,git submodule add -b master https://github.com/ehotinger/ehotinger.github.io.git public
. -
Finally, it’s time to deploy. A simple bash script like the following is all you need:
hugo -t hyde
cd public
git add .
msg="Automatically rebuilt - `date`"
if [ $# -eq 1 ]
then msg="$1"
fi
git commit -m "$msg"
git push origin master
cd ..
Straightforward to read, but this will just make a commit automatically on your behalf for the 2nd repository you made. You can now commit freely to your unrendered blog website as well as your GitHub pages.
Other useful things:
- Hugo front matter - a list of all the metadata you can put on individual content. Description, tags, title, etc.