What is Hugo?
Hugo is a static site generator written in Go. It helps you build websites quickly using templates and programming logics like loops and conditionals. The final project will be published as a static website with no database.
Benefits of Hugo:
- You can create sites very quickly (even large sites.)
- Static sites are fast, secure and can be hosted anywhere.
- You can still manage data in form of json, yaml, toml.
Limitations of Hugo:
- Not for sites that require database obviously (like customer data.)
- Updating the site is not beginner friendly as it can require the use of the command line.
- Limited backend solutions for non-techy clients to manage site.
Though not required, it’s recommended that you know the following:
- How to use git (clone, add, commit, push, pull)
- How to use the command line (we will only use a few though)
I’ll include a short reference on both cli & git at the end of this guide.
- Your favorite text editor (microsoft vsc, atom, notepad++, sublime text)
- Git bash on windows (to clone themes & version control)
- A github account (to save all our work in a “repository”)
- Netlify account (can host github repository as a website for free)
How to install Hugo
Follow the official guide:
Mac: one line code
Windows: install chocolatey, then install hugo using chocolatey: https://chocolatey.org/
Also install git from their website: https://git-scm.com/downloads
- Go to your desktop or any location on your pc.
- Open git bash or a terminal.
- Confirm hugo is installed, run:
hugo new site myfirstsite
(myfirstsite can be any name you like)
- A new website folder will be created (mine will be called myfirstsite)
- Go to https://themes.gohugo.io/ to check out some Hugo themes.
Let’s install a theme
To install a theme, just download and move the theme folder into your site’s themes folder, open your config file in the root of your site folder and set theme there as the name of the theme folder.
For this demo we will install the agency theme: https://themes.gohugo.io/agency/
Read the instructions on their page then follow this guide:
- Open the command line in the themes folder & run:
git clone https://github.com/digitalcraftsman/hugo-agency-theme
(this command will download the agency theme into our themes folder)
- Replace the config.toml file in your site folder with their config.toml in the theme’s example folder.
- Now change directory to the root of your site folder and type this command to run the hugo server:
- Check the message has no errors and look for the address of the server (localhost:1313.)
- Open a browser and go to the address in above step, you should be able to see your website loading with the agency theme.
- Note: You can stop the server anytime by typing Ctrl + C.
Set up the theme
Take a look inside the agency theme folder. Notice that the file structure is identical to that of Hugo’s with the exception of the example folder.
Copy the contents of the example folder and paste them inside the website folder replacing any content and without altering the file structure.
Let’s look at what each of these folders do.
- this folder sets default meta data (called front matter for posts/pages (files in the content folder). You might want to add tags and categories to a page. We do this by adding it as front matter to every page manually, or automatically via archetypes.
- This is where you create post and page files. Files are created as .md (markdown) files. You can also add folders here to make directories.
- you can put content here as a data file in toml, yaml, json. For example, you might have a file called usa-states.json with a list of 50 US States in the file. Hugo has a function where you can loop through all that data and display in somewhere on your site. This can be useful for storing information on stores, customers and products that can be generated from excel.
- This is where you put the templates for your site. You need the index.html and 404.html files at the minimum. You can create the markup here using hugo functions such as loops and conditional statements.
- this folder is inside the layouts folder. You can break your site templates in small pieces and include them in various places.
- all assets such as css, js and images are stored in this folder.
Like we mentioned above, the hugo file structure is almost identical to that of the themes. Hugo will load files from it’s root folder. If files are missing in the root folder, Hugo will load the files in the themes folder. If you want to make edits to the theme, you can copy/paste it to your sites root folder and edit them there.
Publish our Hugo Site
Once we are happy with our site we can upload it to our server for the whole world to see. Make sure you check the config file and confirm that the baseurl parameter is set to your actual website’s url.
Open the command line in your site’s root folder and type:
This will generate the website and put it in the public folder. You can now upload the content of this public folder to your web host and your site should be visible to everyone.
Publish our Hugo Site - Netlify
Netlify offers a hosting solution for repositories such as github. If you have your website files saved on a github repo, you can share it with Netlify to have them host it as a website.
Now every time you push a change to github, Netlify can automatically refresh and update your website content. This will require an additional file called netlify.toml in your sites root folder.
You can just copy/paste the example they provide in netlify’s website: https://www.netlify.com/
I will make a separate short guide on hosting your Hugo website using Netlify.
Extra - helpful Commands with the cli
cd - change directory, eg:
How to cd one level up:
How to cd two levels up:
ls - list files and folders in current dir, eg:
List all files and folders:
ls -al OR
Note: Use dir in windows command line.
pwd - shows where you are now, eg:
How to copy text in cli: select with mouse and type: ctrl + insert
How to paste text in cli: type: shift + insert
Note: selecting text with mouse will automatically copy text in some cli.
How to cancel operation, like stopping hugo server: ctrl + c
The above is probably all you need for using hugo on your desktop pc.
If you want to use cli more, here’s a list of basic commands that you can google (careful with the rm command):
cd , pwd , ls , ls -al , cat , exit , ctrl + c , cp , mv , rm , rm -r , chmod , chown , tar , help
Extra - using git
What is git:
- It tracks file changes.
- Changes can be saved as versions.
How to use git:
- Install git and run git on your pc, add username & email if asked.
- You should also get an account on github, gitlab or bitbucket.
The quickest guide: http://rogerdudler.github.io/git-guide/
Downloading a project
git clone is to copy an existing project from somewhere.
Saving a version on your PC (requires 2 steps):
git add . is to add all the files to index.
git commit -m ‘add a short message here’
this will save changes as a version
Submit changes to github repo:
git push or
git push -u origin master
(Before Editing) Always get latest version from github:
git remote update git status git pull
End of guide
This concludes our guide on how to install Hugo.
Also check out my Hugo Themes for beginner series where I plan to review every single theme in the official Hugo Website.
I hope you found this tutorial helpful, if so please mash that like button.
Questions, comments and constructive criticisms are always welcome.
If you want to see more videos related to websites and photography, please subscribe to my channel : https://www.youtube.com/user/vidafuku.
I will see you all in the next video.