Introduction
Hugo is one of the most popular open-source static generator and is written in GO. It is simple and easy to deploy. And Github Pages is a static web hosting service provided by Github which provides convenient deployment directly through Github repository.
In this brief post I’ll walk you through how I created this website in 5 simple steps using Hugo and GitHub Pages.
Step 1: Install Hugo and get a GitHub account
As I’m a mac user, I’ll provide instructions here for installing Hugo on macOS. To install Hugo on macOS, you’ll need Homebrew. Homebrew is a free and open-source software package management system that simplifies the installation of software on macOS. Run the following in the terminal:
$ /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
Now, to install Hugo simply type:
$ brew install hugo
Finally, if you don’t already have a GitHub account, head over to Github website and create one.
STEP 2: Build your site locally
First step is to go to the directory where you want to store your source code. Here is the sample command in terminal:
$ cd /Users/eddie
$ mkdir mysite
Now, from the command line, change into your new directory:
$ cd mysite
In this directory we will use Hugo to create the framework for your website. Simply type the following with “websitename” replaced with whatever you want to call your website:
$ hugo new site websitename
Change into your newly created websitename directory and view the contents using ls:
$ cd websitename
$ ls
archetypes content layouts themes
config.toml data static
These files and folders form the framework of your Hugo site:
- config.toml: configuration file of your website
- content: store all contents on your website such as blog, resume, posters.
- static: store all static file such as your background, logos, css, js.
- themes: the theme of your website which you can boostrap from hugo website
- public: generated after execute “hugo” command, the static file you pushed to Github repository
In the next step we will select a theme for your website and place it in the themes folder.
Step 3: Choose a theme for your website!
With Hugo you can create your very own website theme or download one of many different pre-made, open source themes. There are plenty of really great pre-made themes and they are perfect for getting your website up and running as quickly as possible. Head over to the Hugo themes page and select a theme for your website. I used the m10c for my website.
Go back to your terminal, cd to the themes` directory and clone the repository:
$ cd themes
$ git clone https://github.com/gcushen/hugo-academic.git
Step 4: Creating your website
Add theme = “m10c”, at the end of config.toml. You can start the hugo server by typing:
$ hugo server
Go to http://localhost:1313 and you will be able to see an empty m10c theme.
Now to add social links to your portfolio you can take a look at mysite/themes/m10c/exampleSite/config.toml. This serves as an example of adding different components to your own config.toml. You can add the social login links to your own config. Copying the params to our own config.toml, it now looks like this:
baseURL = "https://yc392.github.io/"
languageCode = "en-us"
title = "Yuhua Cai"
theme = "m10c"
[params]
author = "Yuhua Cai"
description = "Data Science and Machine Learning"
[[params.social]]
name = "github"
url = "https://github.com/yc392"
[[params.social]]
name = "linkedIn"
url = "https://www.linkedin.com/in/yuhua-cai-195080194/"
To add an avatar, simple add an image of yourself, name it avatar.jpg and place it in static/ folder.
Now that we have our image and social links on the website, it is time to add some more. In Hugo, we can create different web pages. Each webpage goes into the content/posts/ directory as a markdown file. It is there that we can write markdown and define how we want it all to lay out. Lets get started with creating a new post.
$ hugo new posts/Blogs.md
This creates a new file called Blogs.md in the content/posts/ folder. Open Blogs.md and you can start writing markdown.
---
title: "Blogs"
date: 2019-07-23T20:14:38+05:30
draft: true
---
### This is a new blog page
I can write in markdown over here
<br>
#### Index
[Links to blogs](#a)
[Links to blogs](#b)
[Links to blogs](#c)
[Links to blogs](#d)
[Links to blogs](#e)
[Links to blogs](#f)
<br>
- [X] Markdown
- [X] Is
- [X] Fun
Step 5: Hosting your website on GitHub Pages
The first thing you need to do is go to GitHub and create two empty repositories:
- a repository with the same name as the website directory you created: ‘websitename’; and,
- a repository with the name ‘yourgithubusername.github.io’.
If you haven’t created a repository before, simply click your GitHub profile at the top right-hand corner of the screen to see a drop-down menu, click Your repositories and on that page you will se a green button New which will help you create a repository. Once you’ve done that, copy the https key from the repository you created with the same name as your website and then in the terminal cd to your local directory websitename and type:
$ git init
$ git remote add origin https://github.com/User/websitename.git
$ git push -u origin master
This will create a git directory, link it to the remote GitHub repository and then push the contents of the local directory to the remote.
Now copy the https key from the repository you created with the name yourgithubusername.github.io and copy the https key. Then cd back to your initial websites directory and type:
$ git clone https://github.com/User/yourgithubusername.github.io.git # Clone the remote repo
$ cd websitename # Change directory
$ hugo -d ../yourgithubusername.github.io # Deploy your website
$ cd ../yourgithubusername.github.io
$ git add .
$ git commit -m "first commit"
$ git push -u origin master
And that’s it! Go to GitHub and go to the repository yourgithubusername.github.io, click the settings tab near the top of the page and scroll down to the subheading GitHub Pages where you will see the link to your new website: http://yourgitubusername.github.io. Click the link to see your website out in the wild. Congratulations - you can now show off your work to the world!