How to host your personal website on Github using Hugo (1/2)
A beginner’s tutorial for building a static website on Github with Hugo.
Finally, my website is live. 🙂 I am fairly new to Github and markdown, so I thought I’d write down how I did it. This blog is for complete beginners (and Mac users).
Table of Contents
Step 1: Install essentials
First, you need to install Hugo, which is a generator for static websites. Once everything is set up, you can simply write blogs as markdown files and Hugo will automatically generate all the html pages for you. Cool.
A detailed tutorial for Hugo can be found here. Install
Homebrew, and then:
brew install hugo
hugo new site Yue_blog
cd Yue_blog git init git submodule add https://github.com/kakawait/hugo-tranquilpeak-theme.git themes/hugo-tranquilpeak-theme
Step 2: Build a site locally
The quickest way to get a working site is to copy everything from the exampleSite folder provided by the theme. 🙂
# Start from the site directory pwd # get path to this directory cd themes/hugo-tranquilpeak-theme/exampleSite/ cp -a * /Path/to/site/directory/Yue_blog # Get back to the site directory cd ../../..
Similarly, update the files in the layouts and the archetypes folders with the provided layouts and archetypes from the theme.
cd themes/hugo-tranquilpeak-theme/layouts/ cp * /Path/to/site/directory/Yue_blog/layouts cd themes/hugo-tranquilpeak-theme/archetypes/ cp * /Path/to/site/directory/Yue_blog/archetypes
Now, try the following command and see what happens:
Open a web browser and navigate to localhost:1313.
Step 3: Customize your site
Your new website is working (locally). But it’s not quite yours yet. Better add some original content. From now on, all you need to do is to edit the configuration file config.toml, and stuff in the content folder. I will provide a few examples in the following blog post.
Step 4: Create Github respositories
You will need to create two repositories, one (BLOG) will contain all the source files, and the other one (USERNAME.github.io) will contain the generated website. A detailed tutorial can be found in here.
Link the BLOG repository to your local directory.
cd Yue_blog git remote add origin https://github.com/YueYvetteHao/Yue_blog.git
Sync the local and remote repositories
git pull origin master
Remove the public folder and add it back as a git submodule.
rm -rf public git add . git commit -m "updates ..." git push origin master git submodule add -b master firstname.lastname@example.org:YueYvetteHao/YueYvetteHao.github.io.git public
Step 5: Deploy - hello world!
Get the deploy script here and save it in the BLOG repo. Run the shell script to compile the markdown files into html, git add and git commit to the USERNAME.github.io repo:
Done! The website is now running. 🙂
This is how I built my first personal website. I hope this tutorial is helpful!
I recently migrated my website to netlify, which makes continuous deployment possible. Now after I push changes to the BLOG repository on github, the site will be automatically deployed within seconds. Even cooler. :)