How to set up a HUGO project for GitLab pages

Content

Also see this article: How to set up a minimal Jekyll project for GitLab Pages.

It requires some initial investment. What you get is a GitLab -website with blog-posts. The alternative is to use gitlab artifacts , please refer to Continuous Integration on Gitlab.

Step-by-step guide

To create your own HUGO page you can start by building on existing work and fork this project or cleaner: this template project

1. To create a fork:

Click the Fork button on the top right corner.

And finally, for better management rename the repository and change the path to it to match the name you want for your site. This is because Gitlab automatically generates the URL for the project and it takes into consideration the actual name of the project, the username (for projects under your own namespace), the group the project is under (for projects under a specific group) and even the subgroup if it exists.
You can see your pages' URL under Settings → Pages.

For example, if a user creates a project under a group called “leia” (e.g. https://git.rwth-aachen.de/leia/gitlab-ci-presentation and the right files are there, the GitLab page will be available under https://leia.pages.rwth-aachen.de/gitlab-ci-presentation, where we can see that the name of the group is mentioned in the beginning of the URL and the project name at the end of the URL.

2. Build from scratch/GitLab templates:

GitLab has template files available for HUGO, Jekyll and others.

Check your git repository for the following characteristics.

.gitlab-ci.yml

Your .gitlab-ci.yml starts the CI/CD- pipeline and therefore is responsible to deploy your website.

It should look similar to this:

# All available Hugo versions are listed here:
# https://gitlab.com/pages/hugo/container_registry
image: registry.gitlab.com/pages/hugo:latest

variables:
GIT_SUBMODULE_STRATEGY: recursive

test:
script:
- hugo
except:
- master

pages:
script:
- ls themes/hugo-theme-learn/
- hugo
artifacts:
paths:
- public
only:
- master



Adapt - ls themes/hugo-theme-learn/ to fit your path and/or theme.

.gitmodules

In .gitmodules submodules are declared. In this case it could look like this:

[submodule "themes/hugo-theme-learn"]
path = themes/hugo-theme-learn
url = /themes/hugo-theme-learn


The line url =  can possibly contain an actual url, e.g. url = https://github.com/dataCobra/hugo-vitae.git, if the module is present as a git instance.

config.toml

baseurl = "https://moritz.schwarzmeier.pages.rwth-aachen.de/knowledge-base/"
languageCode = "en-us"
title = "SFB1194 Knowledge Base"
theme = "hugo-theme-learn"

contentdir    = "content"
layoutdir     = "layouts"
publishdir    = "public"
canonifyurls  = true

# check the documentation of your hugo theme, e.g. https://learn.netlify.app/en for the HUGO learn theme
#
# For search functionality
[outputs]
home = [ "HTML", "RSS", "JSON"]

[params]
...

.gitignore

Add a file called .gitignore with the single line

public/


.gitkeep

Put a .gitkeep with no content in empty folders, e.g. themes/, static/ and layouts/. The relevant folders will otherwise be displayed in the GitLab like this, e.g.: static/images, where the sub-folder is displayed in the hierarchically-higher level.

# Knowledge Base