Apply Universal
Tags: hugo, jamstack, tutorial
Published: 2023-06-21 23:01:18

Learn how to apply the Hugo's "Universal" theme.

## Goal

Below are the components of a blogging environment with Hugo + GitLab Pages.
The goal here is to change the theme body in the GitLab Hugo theme/content repository to Universal, replace the theme settings/content with the Universal sample, change the CI/CD settings for Universal, and build/publish the sample site.

![Blogging environment with Hugo + GitLab Pages : Hugo theme/content repository position and file structure](https://ayaco.gitlab.io/zerogravity/en/docs/theme/universal-apply/feature.svg)


## Assumption

This explanation assumes that you have followed the "[Server with Hugo + GitLab Pages](https://ayaco.gitlab.io/zerogravity/en/docs/setup/server/)", "[Dev client with VSCode](https://ayaco.gitlab.io/zerogravity/en/docs/setup/client/)" and prepared a server environment built with the GitLab Pages/Hugo template and a development client environment using Visual Studio Code.

## Application method

### Modify theme body, theme settings/contents in Visual Studio Code

1. Delete all Hugo repository assets managed by Visual Studio Code except for `/.gitlab-ci.yml`.

1. Create a symbolic link to the Universal repository under `/themes` in the Hugo repository assets managed by Visual Studio Code by running the following in the Visual Studio Code terminal.

	```
	> cd (the root directory of the Git project)
	> mkdir themes
	> git submodule add https://github.com/devcows/hugo-universal-theme.git themes/hugo-universal-theme
	```

1. Copy `/themes/hugo-universal-theme/*` in the Hugo repository assets managed by Visual Studio Code to `/`.

	```
	Hugo repository assets
	├ content           ← copy from exampleSite
	├ data              ← copy from exampleSite
	├ static            ← copy from exampleSite
	├ themes
	├ .gitlab-ci.yml
	├ .gitmodules
	└ config.toml       ← copy from exampleSite
	```

1. Open `/config.toml` in Visual Studio Code and change `baseurl` to [root URL of the sample site](https://docs.gitlab.com/ee/user/project/pages/getting_started_part_one.html#project-website-examples).

Caution
: "["Error: failed to load modules:..." when applying theme](#error-failed-to-load-modules-when-applying-theme)" may need to be addressed.

### Change CI/CD settings in Visual Studio Code to match the theme

1. Delete `/.gitlab-ci.yml` in the Hugo repository assets managed by Visual Studio Code.

1. Open [.gitlab-ci.yml for GitLab Pages/Hugo template](https://gitlab.com/pages/hugo/-/blob/main/.gitlab-ci.yml) in your browser, download it, and copy it to the `/` of the Hugo repository assets you manage in Visual Studio Code.

1. Open `/.gitlab-ci.yml` in Visual Studio Code, change `image` to non `hugo_extended`, comment out the `hugo mod` description and add a git submodule description.

	```
	...
	image: registry.gitlab.com/pages/hugo:latest                   ← change

	variables:
	  HUGO_ENV: production
	  #THEME_URL: "github.com/theNewDynamic/gohugo-theme-ananke"   ← comment out

	default:
	  before_script:
	    - apk add --no-cache go curl bash nodejs
	    - git submodule update --init --recursive                  ← add
	    #- hugo mod get -u $THEME_URL                              ← comment out
	    ## Uncomment the following if you use PostCSS...
	    #- npm install postcss postcss-cli autoprefixer
	...
	```

### Upload changes made in Visual Studio Code to GitLab

Implement "[Upload Hugo repository assets modified in Visual Studio Code to GitLab - Dev client with VSCode](https://ayaco.gitlab.io/zerogravity/en/docs/setup/client/#upload-hugo-repository-assets-modified-in-visual-studio-code-to-gitlab)".

### Check the build/publish results done automatically in GitLab

Implement "[Check the build/publish results done automatically in GitLab - Dev client with VSCode](https://ayaco.gitlab.io/zerogravity/en/docs/setup/client/#check-the-buildpublish-results-done-automatically-in-gitlab)".

## Troubleshooting

### "Error: failed to load modules:..." when applying theme

#### Phenomenon

When applying a theme using `/themes/hugo-universal-theme/exampleSite/config.toml`, the following error occurs.

```
: Error: failed to load modules: module "universal" not found in "/builds/universal"; either add it as a Hugo Module or store it in "/builds".: module does not exist
```

#### Cause

Error in `themesDir` in `config.toml`. The value has been set to `"../.."`.

#### Remedy

Correct the value of `themesDir` in `config.toml` to `"themes"`.

```
	...
	themesDir = "themes"
	...
```