Dillon

Posted on Sep 11, 2018

Creating a Hugo site on GitHub Pages

#hugo #beginners #go #tutorial

Quick Backstory

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!

Installing Homebrew

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!

Installing Go

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:

Homebrew
Go

Installing Hugo

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:

cd ~

then to make a directory name "Sites" type: mkdir Sites

move into that directory cd Sites

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 Themes

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).

luizdepra / hugo-coder

A minimalist blog theme for hugo.

A simple and clean blog theme for Hugo.

Live Demo

See here.

Quick Start

Add the repository into your Hugo Project repository as a submodule, git submodule add https://github.com/luizdepra/hugo-coder.git themes/hugo-coder.
Configure your hugo.toml. You can either use this minimal configuration as a base, or look for a complete explanation about all configurations here. The hugo.toml inside the exampleSite is also a good reference.
Build your site with hugo server and see the result at http://localhost:1313/.

Documentation

See the docs folder.

License

Coder is licensed under the MIT license.

Maintenance

This theme is maintained by its author Luiz de Prá with the help from these awesome contributors.

Sponsoring

If you like my project or it was useful for you, consider supporting its development. Just:

Special Thanks

Gleen McComb, for his great article about custom pagination.
All contributors, for every PR and Issue reported.

View on GitHub

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 yoursitename

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

hugo server

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 exampleSite directory.

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.

Now 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

Then 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!

The End

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!

Top comments (9)

Nicolas Cuervo • Sep 12 '18

I've been through the same journey since a couple of weeks ago and I gotta say that you have put together some nice points in here. My two cents:

If you are here you should have the following installed:

Homebrew
Go

This is going too into the specifics, mostly because they are not necessarily a requirement. These are only valid on a fresh macOS machine, and are not the case, let's say, if you are using Ubuntu for example. I'd just point out to the hugo installation page for completeness, and leave the maintaining burden where it belongs.

When choosing a theme, you say:

Note: make sure you click "Use SSH" on the popup box then copy the SSH key.

This is also not necessarily true. If you are not going to push to a repository (which is probably the case as you are cloning something where you might have no writing rights anyway) then authentication is not the main problem. The https clone works just as well.

The rest of it is definitely on point. Personally I chose gitlab for my free website hosting because, mainly, a personal preference given the free repositories and free webhosting for each and every organization I create there. Ever since I read this post (thanks @effingkay ) I've been meaning to also try netlify, but sadly haven't have the time for it. Maybe you'd like to check it out!

Cheers!

Dillon • Sep 12 '18 • Edited

Thanks for your input! You're definitely right about installing brew and go. My intent was to make sure that the user had everything they needed to do this tutorial, but I agree that it might be getting into the details and best left to that Hugo page! I will make the edit! Thanks again!

Tom Tolleson • Mar 12 '20

This is great, thanks Dillon.

One feature I'd love to implement on a Hugo Github pages site is the ability to dynamically list my repos from the Github API with links to the repos and description. That really enhances the portfolio aspect of it, I think. In Jekyll it would be

{% for repository in site.github.public_repositories %} {{ repository.name }}

{{ repository.description }}

{% endfor %}

I've found Go modules that do the same but for Hugo beginners it might be nice to include that feature (assuming there is a fairly simple way to do that).

DBJDBJ • Apr 28 '19 • Edited

"...Now cd .. to go to the Sites directory ..." .. I have no "Sites" directory above the local hugo project root "directory" ... ?

Also. Before HUGO I had this GitHub account for years. Full of repo's and it already has dbjdbj.github.io/ ... And I do not want to loose that. Are we saying I need new github account to be abple to publish on the GitHub, Hugo made site?

Please advise ...

Dillon • Apr 28 '19

Hey dbj!

"Sites was the working directory we created in the beginning of the tutorial. If you didn't make a "Sites" working directory just replace "Sites" with the directory you placed your files in.

For using your dbjdbj account I'm pretty sure you can create more Github Pages using a project page. FOr more informations regarding project pages check this out:

help.github.com/en/articles/user-o...

I haven't used HUGO for a project page but it is worth a shot!

Hope this helps!