Create a Hugo Static Site on GitLab Pages

Posted on Dec 25, 2020

Hugo sites hosted on Gitlab are straighforward to set up, free to host and provide a wonderful workflow using git and markup text editors to create new pages and posts!

Requirements

  1. Git
  2. GitLab account
  3. Hugo installed

Create a new GitLab repository

We need to set up the git repository your Hugo site will live in.

  1. Go to gitlab.com and sign in, or sign up.
  2. Select “New project” in the top right, or click here
  3. Click “Create from template”
  4. Find “Pages/Hugo”, or click here , and select “Use template”
  5. Name your project, leave it Private and select “Create project”
  6. Clone your repository locally on your computer. In the command line run git clone https://gitlab.com/{username}/{repository-name}.

Add a Theme (Optional)

A theme will already be installed, but it may not be the theme you want.

There are a number of free Hugo themes avaialable that you can use.

  1. Create a new branch called feature/theme. In the command line run git checkout -b feature/theme.
  2. Select a theme .
  3. Download the files for the theme. Generally through downloading a zip file from GitHub.com . Do not follow the theme instructions and clone the repository as this will cause problems customizing and rendering the theme.
    • Make sure you unzip the download before copying it into themes/
    • The folder may have -master at the end. Themes are referenced by the name of the folder they are in within themes. The -master could interfere with this. Check the config file within the theme’s exampleSite folder to see what the theme = is set to there and make sure your folder name matches that.
  4. Copy the theme into the themes/ folder in your Hugo project repository.
  5. Add your changes. git add *.
  6. Commit your changes. git commit -m "added a new theme"
  7. Push the branch to GitLab. git push --set-upstream origin feature/theme
  8. Go to your repo, create a merge request and merge it by clicking Merge. The CI/CD Pipeline may fail. We will fix it in the next steps.

Update the Config File

In Hugo the config file in the root directory will unsuprisingly determine a lot of the configuration of the site. This will either be a .toml, or .yml file. In the config file you will specify elements like:

  • Site title and subtitle
  • The theme
  • Site menu items and links
  • Authors and author details

Depending on the theme there may also be other elements you can specify here.

To set up your config file:

  1. Create a new git branch. git checkout -b feature/config
  2. Optional - If you added a custom theme copy the config file from themes/{yourTheme}/exampleSite/config.{type} to your root directory. E.g. from the root direcotry of your repository run the command cp themes/archie/exampleSite/config.toml config.toml.
  3. Make sure the theme variable is set to the name of the folder that the theme you want to use is in in the themes/ folder. E.g. if you are using the archie theme and it is located in themes/archie/ in your config.toml set theme = archie.
  4. Update the baseURL to be "/"
  5. Look through the config file and update anything else you want.
  6. To see the impact your changes are having run hugo server from the root directory of the project.
    • If you are getting an error due to the gallery missing delete the file /content/post/2017-03-20-photoswipe-gallery-sample.md
  7. When you are happy commit your changes, push your branch to GitLab and merge it (see the last steps of Add a Theme for more details).

Customize the Design

You may want to make some updates to the theme beyond what is possible in the config file. This will require some knowledge of html, css and Hugo syntax .

For more granular customization you will want to update the theme files.

  1. Navigate to themes/{your-theme}.
  2. CSS is located in the static folder.
  3. HTML is in the layouts folder.
    • To modify the header and footer HTML look in the layouts/partials/ folder.
    • To modify the home page layouts/index.html

Remove the Example Content

The example content is useful for getting your site looking like you want it to, but GitLab’s example content probably is not what you want on your site.

  1. Delete all of the posts in content/post/.
  2. Delete all the pages in content/page/.

Add a Custom Domain (Optional)

By default your content will be hosted on https://{usrename}.gitlab.io/{repository-name}, but GitLab gives you the option to host this on your own domain .

This process will vary a bit depending on your domain registrar (e.g. godaddy.com ), but I will write up the GitLab side of it.

  1. Navigate to your repository in GitLab.
  2. In the left hand navigation bar select Settings > Pages.
  3. In the top right select New Domain.
  4. Add in your Domain.
    • This should probably be a subdomain like www.{your-domain-name}.com since most hosting providers do not support pointing the root url ({your-domain-name}.com) to a CNAME record like GitLab provides.
  5. Add the DNS record to your registrar.
    • The string they give you to copy consists of two parts, the full domain name you added and the CNAME record. In godaddy your entry will only consist of the subdomain (e.g. www) in the Name section and the {your-username}.gitlab.io part in the Value section.
    • Do not just copy the entirety of what GitLab gives you into your DNS
  6. Add SSL.
    • As with the DNS record The TXT record should be split into two parts as well and the TXT component will not be input.
    • Ensure you remove the domain name from the record if your DNS provider is godaddy .

Update the Default Branch from master to main (Optional)

The Hugo example project uses master as the default branch, so creating your project off of this template will mean your project is using the master branch as well. Standards are moving towards using main instead of master. You can follow the steps in this post to make this update. You will need to update the .gitlab-ci.yml file.

Issues Encountered

  1. Styling not appearing
    1. Incorrect root domain.
      • Make sure the baseURL in your config file is set to "/", or your full root domain including the http.
      • Whatever your baseURL is set to will be added to any url, including styling files and links.
    2. Theme cloned, but not copied.
      • Most of the themes tell you to git clone the theme into your themes/ folder. This will add the theme’s git repository as a dependency, but not download all of the files. I have found that when this is the case GitLab does not apply the theme.