Setting up a static site with Hugo, Gitlab and Netlify
Tags: netlify
Published: 2021-04-12 10:11:03

How fitting that the first post on a blog is how to essentially set one up. This is my first time using Hugo, so this post is targeting absolute beginners with experience using Unix.

# Install Hugo
The first thing you need to do is install the hugo CLI. I did this via Nix, but you can find the instructions for your platform on their site https://gohugo.io/getting-started/installing/.

Nix:
```
nix-env -i hugo
```

What I really liked about hugo is that it is simple to use for just writing plain markdown and builds very quickly compared to other static site generators like Gatsby or Jekyll. This really follows in the tradition of golang, which hugo is written in.

# Set up local git repository
Next, you can create a new static site with
```
hugo new site my-site
```

This should create a directory called my-site and fill it with a template to get started on your site. Then inside the directory, you can create an interactive preview of your site using `hugo server`. This hosts a local version of your site on port 1313 on `localhost`. It was kind enough to bind the address to your `localhost` too so only you should be able to see it. It should look something like this:

```
$ hugo server

Start building sites … 

                   | EN  
-------------------+-----
  Pages            | 10  
  Paginator pages  |  0  
  Non-page files   |  0  
  Static files     |  1  
  Processed images |  0  
  Aliases          |  2  
  Sitemaps         |  1  
  Cleaned          |  0  

Built in 54 ms
Watching for changes in /Users/kvwu/workspace/kvwu-blog/{archetypes,content,themes}
Watching for config changes in /Users/kvwu/workspace/kvwu-blog/config.toml
Environment: "development"
Serving pages from memory
Running in Fast Render Mode. For full rebuilds on change: hugo server --disableFastRender
Web Server is available at http://localhost:1313/ (bind address 127.0.0.1)
Press Ctrl+C to stop
```

Notice how fast it builds! 54ms is quite good. This is really good for a personal blog where I don't want to waste a lot of time watching the build process run.

You can initialize git at this point in the `my-site` directory with `git init`.

The next thing that I did was set up a nice theme. You can find a lot of great themes available at https://themes.gohugo.io/. I just found one that I liked and added it as a submodule of my new site repository.

```
git submodule add $THEME_URL themes/$THEME_NAME
# For example for my theme
git submodule add https://github.com/vaga/hugo-theme-m10c.git themes/m10c
```

This copies the repository at the `$THEME_URL` in the themes directory, and should have added `themes/$THEME_NAME` to staging. You can take a look at the theme by adding `theme = $THEME_NAME` to your `config.toml` and looking at `http://localhost:1313/`, and if it looks good to you, commit these changes.
```
git commit -m 'add theme'
```

I also found it useful to edit some other information in `config.toml`.
I changed the `author` and `params.description` to better fit my needs. These changed the values on the sidebar for my theme. I suppose you could play around and find which configurations change your page.

# Set up Gitlab remote repository
Gitlab is a site that allows you to host a git repository online. You could also use Github, but I used Gitlab, so my instructions will be for that.

As far as I know, there isn't a great way to set up a remote repository on Gitlab through CLI, and it's not easy to describe how to use their website with words. Their instructions on how to do this can be found here https://docs.gitlab.com/ee/user/project/working_with_projects.html#create-a-project.

Once you have set up a remote repository, you can add your local repository to it
```
git remote add origin git@github.com:username/projectpath.git
git push
```

# Set up Netlify
Netlify is a service that will host your site for you. This particular section suffers from the same problem as the Gitlab one. Netlify does have a cli, but I used their web UI. However, luckily for us, Netlify provides really detailed instructions on their site for how to host your site: https://gohugo.io/hosting-and-deployment/hosting-on-netlify/.

The tutorial, at least at time of writing, shows how to set up using Github but it's pretty easy to set up with Gitlab as well by just clicking Gitlab instead of Github when prompted.

When prompted to select your repo, select the repo you just created and your master branch. This will create a hook so that whenever you push your master branch, you will deploy a new version of the website. 

One issue that I encountered with the compatibility was that my theme required at least hugo 0.55, but Netlify was using 0.54 by default. In this case you can create a `netlify.toml` file e.g.
```
[context.production.environment]
HUGO_VERSION = "0.81.0"
```
to specify your hugo version. I chose 0.81 because that was the version that I had installed, which I think should lead to the most consistent experience. You can find out which version you're using by running `hugo version`.