Rudy's Notes


Hugo: Quick and Easy Setup

We will start this tutorial with a TL;DR section to get a simple Hugo project up and running, followed by the remaining sections to describe it.

TL;DR #

These are a few CLI commands which I summarize from the official Hugo documentation page to get a simple Hugo project up and running.

# Install Hugo static site generator
brew install hugo

# Create a new project
hugo new site homepage
cd homepage
git init

# Download and select preferred theme
git submodule add https://github.com/Lednerb/bilberry-hugo-theme.git themes/bilberry
echo "theme = 'bilberry'" >> config.toml

# Create a new post
hugo new posts/hello-world.md
echo "Hello, **world**." >> content/posts/hello-world.md

# Run built-in development server (http://localhost:1313)
hugo server -D

Easy, isn’t it!

Now that we have a brief idea of how it works, let’s describe the above commands one by one to understand them.

Installation #

First of all, we need to install the Hugo CLI. On macOS, it can be installed with Homebrew. It might be slightly different on other platforms, which in that case you can check the official documentation.

brew install hugo
hugo version # to verify a successful installation

Create a new project #

After we have our Hugo CLI ready, we can now easily create a project from the command line. We will also need to initialize the project with the Git versioning system as we will likely save this project in the Git repository later. Here we name the project as homepage, but it could be anything meaningful.

hugo new site homepage
cd homepage
git init

Select theme #

We need to download and select our preferred theme as well since a new Hugo project does not come with a default theme. There are a lot of free themes that we can choose from. I found that themes.gohugo.io and jamstackthemes.dev have plenty of great themes suitable for any website purpose.

So basically, we need to get the theme’s URL which is in form of a Git repository URL. We then need to clone it into the themes/ directory. After that, we have to update Hugo’s configuration file to use the new theme we have downloaded. Here is how we typically do it:

git submodule add https://github.com/Lednerb/bilberry-hugo-theme.git themes/bilberry
echo "theme = 'bilberry'" >> config.toml

Create the first content #

After everything is set up, we can now create our first content. We will create a new post here. Hugo uses Markdown formatting to render content.

hugo new posts/hello-world.md
echo "Hello, **world**." >> content/posts/hello-world.md

Run a development server #

When all the above steps are done, now is the time to see the actual site looks in the browser. Hugo comes with a built-in development server that we can easily run it locally. After we run the following command, we can check it on its default address at http://localhost:1313.

hugo server -D

Conclusion #

So that is a quick setup to start working with Hugo.

As a static site generator, Hugo comes with advantages which a few that I can think of are:

comments powered by Disqus