Creating a Hugo site on GitHub Pages
Dillon Sep 11
So I've just begun my journey as a web developer and I was stumbling along trying to create a website when I came across an awesome static site generator called Hugo!
This is my first post so I hope it's useful :)
What is Hugo?
Hugo self-proclaims that they are the "fastest framework for building websites," and I have to say they've made the task pretty simple even for a beginner like me! After a bit of trial-and-error, and some youtubing I was able to get a site up and running on GitHub Pages very quickly! With that said, there were some things I found unclear so I'm going to attempt to write a step-by-step of what I went through to help others have a smoother time getting their website up and running!
Introduction & Necessary Installations
You can also follow the Hugo Install Page for Windows or Linux, as this post is on MacOS! If you do that you can skip to the Getting Started with Hugo section of this post!
Note: If you have Homebrew and Go skip to here, also if you haven't configured git or have a github account please do both of those things. Use the email you used to create a github account to configure git!
Note: If you have Homebrew you can skip to downloading go
I'm going to start with no assumptions here so we will begin by having you install homebrew for MacOS which is super simple and makes life with other tasks way more simple later!Open the terminal by pressing Command + Space and typing "terminal" then pressing enter, then copy and paste the following (You should be in your Home directory):
/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
You'll want to accept any prompts that are thrown and BAM! done! You can now get brewing! (Note: Check out Homebrew which is where I got this code). This will make the next couple steps much nicer!
Note: If you have Go already installed go ahead and skip this as well!
Now that you have homebrew, to install Go you will need to type the following into the terminal:
brew install go
Again, accept any prompts until the download is complete and you will end up with Go installed! If you don't know what Go is it's a programming language created by Google, which is becoming more popular everyday, Hugo will leverage this language to create the website framework. If you are interested in more about Go, Go here (Pun intended)
Getting started with Hugo
If you are here you should have the following installed:
Now for installing Hugo, as you might have guessed installing Hugo is just as simple as the previous two installs. Simply type the following:
brew install hugo
That's it! we are ready to begin working with Hugo!
Setting up for Hugo
Let's set up a directory to do all our work in. In your terminal go to your home directory by typing the following:
then to make a directory name "Sites" type:
move into that directory
Now that you're in the Sites directory you can now begin to work with Hugo here.
The first step is really simple type:
hugo new site yoursitename
The hugo new site command will will create the skeleton of your site. You should see the following prompt after you execute the command
Congratulations! Your new Hugo site is created in /Users/YourName/Sites/yoursitename. 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.
These direction are the next steps you need to take to get your site where you want it. We are going to go over them lightly so you can understand what these components are and how to interact with them. Now you should
cd yoursitename and then
ls to check out the directory and you will see the following:
archetypes content layouts static config.toml themes data
This is the skeleton of your Hugo site, it is here where you will work with creating new content for your site which I've cover once we get your site posted to GitHub. The important thing to notice here is the
theme directory. The theme directory is where you will be customizing your site.
Hugo allows you to create your own themes or download pre-made open source themes that others have made! The pre-made options are perfect for getting started with Hugo so that's the route we are going here.
The premade themes can be found at the Hugo Themes page.
Pick a theme.
(for the tutorial you will see the Coder theme that I used for my site).
A simple and clean blog theme for Hugo.
HugoCoder uses Asset Pipeline now!
To use this theme you need Hugo Extended Version, v0.43 or later. But, if you still want to use the old version, you can clone the v1.0 release.
How to use this theme
hugo-coder go through the following steps.
Clone this repository into your Hugo project.
git clone https://github.com/luizdepra/hugo-coder.git themes/coder
Add the following lines to your
baseurl = "http://www.example.com" # Hostname (and path) to the root. title = "johndoe" # Site title. theme = "hugo-coder" # Set the theme. languagecode = "en" # The site’s language code used to generate RSS. defaultcontentlanguage = "en" # The default content language. paginate = 20 # Default number of pages per page in pagination. canonifyurls = true # Enable to turn relative URLs into…
Once you pick a theme click download on its page which will bring you to its github repository. Once there click the green "clone or download" button Note: make sure you click "Use SSH" on the popup box then copy the SSH key. Now that you have copied the SSH key go back to your terminal, make sure you are in the
themes directory type
git clone and press
control + v to paste it into the terminal, then enter! Note: if you do not have git configured check this article out Now you should have a repository with the name
coder or whatever theme you chose;
cd coder and then 'ls' to see the content of the directory.
These are all the files you will need to make your site look just like the theme you chose! Now
cd exampleSite and check out the files there.
Now, the easiest way I found to get your site up and running quickly is to take the files from
exampleSite and replace them with the files you created when you ran the
hugo new site sitename command. In other words, move everything from
content in the
exampleSite directory into the
content under the
yoursitename directory. So you will do that for all the files in the
exampleSite directory until that directory is completely empty. Anywhere that there's duplication like the
config.toml file remove the one created by the
hugo new site command. Then move everything else out of the coder directory even if it doesn't have a matching place just move it up out of coder and into youwebsitename directory. The only files you don't need to move are:
theme.toml README.md Makefile LICENSE.md
It is extremely important that you move everything correctly!
Once you have done that go to the config.toml file and look around. it should look like this (without the notes I have added to the right with the <- before it telling you what to change in the file to customize the website) if you use the coder theme.
Important: You need to change the baseurl to what is specified below!
baseurl = "http://examplesite" <- Change to http://yourgithubusername.github.io title = "johndoe" <- Name your website here theme = "hugo-coder" languagecode = "en" paginate = 20 canonifyurls = true pygmentsstyle = "b2" pygmentscodefences = true pygmentscodefencesguesssyntax = true disqusShortname = "yourdiscussshortname" <- Your short name for commenting [params] author = "John Doe" <- Your name description = "John Doe's personal website" <- How you would describe the site keywords = "blog,developer,personal" info = "Full Stack DevOps and Magician" <- A small description of what your are avatarurl = "images/avatar.jpg" <- your image footercontent = "Enter a text here." <- a footer (quotes are nice) hideCredits = false hideCopyright = false rtl = false # Custom CSS custom_css =  [[params.social]] name = "Github" icon = "fab fa-github fa-2x" weight = 1 url = "https://github.com/johndoe/" <- Change to your Github profile url [[params.social]] name = "Gitlab" icon = "fab fa-gitlab fa-2x" weight = 2 url = "https://gitlab.com/johndoe/" <- Change to your GitLab profile url [[params.social]] name = "Twitter" icon = "fab fa-twitter fa-2x" weight = 3 url = "https://twitter.com/johndoe/" <- Change to your twitter profile url [[params.social]] name = "LinkedIn" icon = "fab fa-linkedin fa-2x" weight = 4 url = "https://www.linkedin.com/in/johndoe/" <- Change to your Linkedin profile url [[params.social]] name = "Medium" icon = "fab fa-medium fa-2x" weight = 5 url = "https://medium.com/@johndoe" <- Change to your medium profile url [[menu.main]] name = "Blog" weight = 1 url = "/posts/" [[menu.main]] name = "About" weight = 2 url = "/about/" [[menu.main]] name = "Projects" weight = 3 url = "/projects/" [[menu.main]] name = "Contact me" weight = 5 url = "/contact/" [languages] [languages.en] languagename = "English" # The language name to be displayed in the selector. title = "John Doe" # You can configure the theme parameter for each language. [languages.en.params] author = "John Doe" <- Your name info = "Full Stack DevOps and Magician" <- What you do description = "John Doe's personal website" <- quick description keywords = "blog,developer,personal" [languages.en.menu] # It is possible to change the menu too. [[languages.en.menu.main]] name = "About" weight = 1.0 url = "/about/" [[languages.en.menu.main]] name = "Blog" weight = 2.0 url = "/posts/" [[languages.en.menu.main]] name = "Projects" weight = 3 url = "/projects/" [[languages.en.menu.main]] name = "Contact me" weight = 5 url = "/contact/" ------------------------delete below (unless you know polish) ---------------- [languages.pl] languagename = "Polski" title = "John Doe po polsku" [languages.pl.params] author = "John Doe" description = "Strona domowa John'a Doe" keywords = "blog,developer,strona domowa" info = "Full Stack DevOps i Magik" [languages.pl.menu] [[languages.pl.menu.main]] name = "O mnie" weight = 1.0 url = "/pl/about/" [[languages.pl.menu.main]] name = "Blog" weight = 2.0 url = "/pl/posts/" [[languages.pl.menu.main]] name = "projektowanie" weight = 3 url = "/projektowanie/" [[languages.pl.menu.main]] name = "kontakt" weight = 5 url = "/kontakt/" -------------------------------------------------------------------
Save the file with your changes. Now go to your terminal and go to the directory
Hosting Your Hugo Site Locally
Now that you made the basic changes to the website it's time to host your website on a locally! This will allow you to see what your website looks like before you put it on the internet for people to see!
Make sure your in the directory
yoursitename and type
read the instructions there and paste the localhost url to your browser!
Presto! You have your own website! Congratulations! All the links should work and have the
exampleSite post and info in them! If they don't you'll want to check and make sure you moved everything correctly outside of the
Now that you have an awesome site go to the
about.md file and write about yourself then refresh you browser on the about page. You should see that the website updates automatically in your browser! This is really handy for prototyping posts! Play around with the files a bit to begin to understand how things are organized in the directory and how they look on the browser website. Understanding how things are laid out will make using Hugo later much more intuitive.
The Basics of Creating New Content
To create a new file in your hugo site is really simple. First, you'll always want to be in your
yoursitename directory when creating new content then you will always us the
hugo new (contentpathhere) command. Try making a new post with the following command
hugo new posts/firstpost.md
Find firstpost.md and edit it with something, then make sure the
draft setting in the header is changed to
false instead of
true. Save that file and go to the browser and refresh the page, then go to blog and BAM! You created your very first post on your site! THis is the basic process for making new post on a hugo site, you should read more about creating new content when your more comfortable with the basics of Hugo!
Hosting on GitHub Pages
Now that you made the basic site we will host it for everyone to see on GitHub! GitHub provides this service for free so don't worry about paying for a thing!
The first thing you'll want to do is to go to github and create two repositories
1. A repository with the exact name as your website directory 'yoursitename' 2. A repository with the name 'yourgithubusername.github.io'
Once you create those repositories grab the SSH key from the repository with the exact name of your website and then go to your site directory
yoursitename and type
git init and then type
git add remote and paste the SSH key after that. Then type
git pull origin master.
cd .. to go to the
Sites directory and type
git clone and add the SSH key from the 'yourgithubusername.github.io'. Once cloned
cd yoursitename, type
hugo -d ../yourgithubusername.github.io. Then
cd ../yourgithubusername.github.io and then type
git add . git commit -m "your message" git push origin master
cd ../yoursitename and type
git add . git commit -m "your message" git push origin master
Now go to GitHub and go to the 'yourgithubusername.github.io' repository and click settings, scroll until you see the link to your website that says http://yourgitubusername.github.io. You should now see your site on the web here! Congrats! You now served a website on GitHub Pages! Now you can direct your friends, family, and potential employers to this address to show them all the cool things you post and do!
I hope this was helpful to those looking to create their first website quickly and please feel free to comment with suggested changes or questions! I will help to clarify anything!
Thank you so much for reading my first post!